Reference

CLI reference

Every `stack` subcommand, every flag, every default — sourced from the citty `defineCommand` calls in `packages/cli/src/commands/`.

At a glance

stack ships with 27 top-level commands. The core loop is init → add → doctor — everything else is context, migration, or ops.

stack init Scaffold a .stack.toml in the current directory. stack import Import an existing .env into Phantom + .stack.toml. stack scan Detect providers used by this repo (package.json, config files, .env.example). stack clone Clone a GitHub repo and auto-detect its Stack services. stack add Provision a service and wire its secrets + MCP entry. stack remove Remove local service config and MCP wiring; attempt Phantom secret removal (headless runs may retain secrets). stack list List services configured in this stack. stack info Show everything Stack knows about a configured service. stack status Show stack health at a glance. stack env Inspect the effective env-var map for this stack. stack deps Show the service dependency graph for this stack. stack doctor Verify every service is reachable and credentials are valid. stack exec Run a command with Phantom's secret proxy active. stack swap Migrate a project from one provider to an equivalent in the same category. stack sync Push secrets to a deployment platform (via phantom sync). stack onboard Detect Codex, Claude Code, Cursor and Gemini CLI and register the Phantom gateway in each (plan by default). stack open Open a service's dashboard in your browser. stack login Refresh OAuth / PAT credentials for a specific provider. stack telemetry Opt into / out of anonymous usage telemetry. See docs/PRIVACY.md. stack templates List or apply starter stack templates. stack providers List every curated provider Stack can wire up. stack recommend Pick the right providers for what you're building (AI-assisted). stack apply Apply a saved recipe: provision each provider, check its secrets in Phantom, and add webhook stubs. stack projects Manage the cross-project registry at ~/.stack/projects.json. stack ci CI workflow generation (unavailable; use `stack doctor` instead). stack completion Emit shell completion for bash, zsh, or fish. stack upgrade Check npm for a newer @ashlr/stack release.

Global behaviour

Commands that mutate state (add, remove, import) refuse to run unless Phantom is on PATH.
Interactive commands auto-detect TTY. In non-interactive contexts (CI, an MCP tool call) they fall through to a sensible default or exit with a structured error instead of prompting.
All output honours NO_COLOR. Structured JSON is available on stack doctor --json for CI.
Exit codes: 0 on success, 1 on any failure that wasn't a cancellation, 127 if a required dependency (Phantom, git) isn't installed.

`stack init`

Scaffold a .stack.toml in the current directory.

Warns (but proceeds) if Phantom isn't on $PATH. `stack add` requires Phantom; `stack init` does not.

Synopsis

stack init [--template <template>] [--force] [--noInteractive] [--noProvision] [--dryRun] [--noRollback]

Flags

Flag	Type	Description
`--template <template>`	string	Name of a starter template to apply (e.g. nextjs-supabase-posthog).
`--force`	boolean default: `false`	Overwrite an existing .stack.toml.
`--noInteractive`	boolean default: `false`	Skip template picker — always creates a blank .stack.toml.
`--noProvision`	boolean default: `false`	Write the .stack.toml shape from the template but skip provisioning services.
`--dryRun`	boolean default: `false`	Print what would be provisioned without doing it (implies --noProvision for real calls).
`--noRollback`	boolean default: `false`	On partial provisioning failure, keep successfully-added services instead of rolling them back.

Examples

stack init

# apply a starter template up front
stack init --template nextjs-supabase-posthog

# CI-safe blank init
stack init --noInteractive

`stack import`

Import an existing .env into Phantom + .stack.toml.

Routes every secret into Phantom, then best-guesses which provider each belongs to and writes matching service entries into .stack.toml.

Synopsis

stack import [--from <path>] [--dryRun] [--json]

Flags

Flag	Type	Description
`--from <path>`	string default: `.env`	Path to the .env file to import.
`--dryRun`	boolean default: `false`	Print what would happen without writing anything.
`--json`	boolean default: `false`	Emit machine-readable JSON (schema ashlr.stack.import/v1, names only): what was stored, skipped and wired.

Examples

stack import

stack import --from .env.local --dryRun

`stack scan`

Detect providers used by this repo (package.json, config files, .env.example).

Synopsis

stack scan [--path <path>] [--auto] [--yes] [--confidence <low|medium|high>] [--json]

Flags

Flag	Type	Description
`--path <path>`	string default: `.`	Directory to scan.
`--auto`	boolean default: `false`	After scanning, offer to run `stack add` for each detected provider.
`--yes`	boolean default: `false`	Non-interactive: accept all hits at/above --confidence threshold. Implies --auto.
`--confidence <low\|medium\|high>`	string default:	Minimum confidence to surface/act on: low \| medium \| high.
`--json`	boolean default: `false`	Output detection results as JSON and exit 0. No prompts, no add.

Examples

stack scan

# auto-wire only signals we're sure about
stack scan --auto --confidence high

`stack clone`

Clone a GitHub repo and auto-detect its Stack services.

After cloning, runs `stack scan` automatically. If the repo already ships a committed .stack.toml, it prints next-step guidance instead.

Synopsis

stack clone <url> [dir]

Flags

Flag	Type	Description
`<url>` req	positional	GitHub / git URL to clone.
`[dir]`	positional	Optional target directory.

Examples

stack clone https://github.com/acme/webapp

stack clone git@github.com:acme/webapp.git my-app

`stack add`

Provision a service and wire its secrets + MCP entry.

Requires Phantom to be on $PATH. Runs the provider's four-step lifecycle: login → provision → materialize → persist.

Synopsis

stack add [service] [--use <id>] [--region <region>] [--dryRun] [--install <mode>]

Flags

Flag	Type	Description
`[service]`	positional	Service name (e.g. supabase, neon, vercel). Omit for interactive picker.
`--use <id>`	string	Attach to an existing resource by id instead of creating a new one.
`--region <region>`	string	Region hint for providers that need one (e.g. us-east-1).
`--dryRun`	boolean default: `false`	Preview what would happen (no network calls, no vault writes, no MCP edits).
`--install <mode>`	string default: `ask`	SDK install behaviour after provisioning: ask (default), always, never.

Examples

stack add supabase

stack add neon --region us-east-2

# attach to an existing Vercel project
stack add vercel --use prj_abc123

stack add --dryRun

`stack remove`

Remove local service config and MCP wiring; attempt Phantom secret removal (headless runs may retain secrets).

Synopsis

stack remove [service] [--all] [--allOrphans] [--keepRemote] [--json]

Flags

Flag	Type	Description
`[service]`	positional	Service name. Omit with --all to remove every service.
`--all`	boolean default: `false`	Remove every local service entry; prompt for confirmation in a terminal.
`--allOrphans`	boolean default: `false`	Detect services in .stack.toml no longer present in source, then remove their local entries.
`--keepRemote`	boolean default: `false`	Compatibility flag; upstream resources are kept for every removal.
`--json`	boolean default: `false`	Emit machine-readable JSON (schema ashlr.stack.remove/v1) naming the secrets Phantom kept. Never prompts.

Examples

stack remove supabase

stack remove --all --keepRemote

`stack list`

List services configured in this stack.

Synopsis

stack list [--json]

Flags

Flag	Type	Description
`--json`	boolean	Emit machine-readable JSON (schema ashlr.stack.list/v1).

Examples

stack list

# ashlr.stack.list/v1 for agents
stack list --json

`stack info`

Show everything Stack knows about a configured service.

Prints provider, resource id, region, secret slots (with vault presence), MCP wiring, dashboard URL, and runs a fresh healthcheck.

Synopsis

stack info <service> [--json]

Flags

Flag	Type	Description
`<service>` req	positional	Service name.
`--json`	boolean default: `false`	Emit machine-readable JSON (schema ashlr.stack.info/v1, secret names only).

Examples

stack info supabase

`stack status`

Show stack health at a glance.

Synopsis

stack status [--json]

Flags

Flag	Type	Description
`--json`	boolean	Emit machine-readable JSON (services, config, phantom).

Examples

stack status

`stack env`

Inspect the effective env-var map for this stack.

Synopsis

stack env <show|export|diff>

Flags

Flag	Type	Description
`--env <env>`	string default: `dev`	Environment overlay to preview.
`--json`	boolean default: `false`	Emit machine-readable JSON (schema ashlr.stack.env/v1, secret names only).

Subcommands

stack env show Show which secrets are present in Phantom.

stack env show [--env <env>] [--json]

Flag	Type	Description
`--env <env>`	string default: `dev`	Environment overlay to preview.
`--json`	boolean default: `false`	Emit machine-readable JSON (schema ashlr.stack.env/v1, secret names only).

stack env show

stack env show --env prod

stack env export Write a .env.example skeleton from the catalog secrets.

stack env export [--example] [--stdout] [--force]

Flag	Type	Description
`--example`	boolean default: `false`	Write .env.example (required flag to distinguish from future sub-verbs).
`--stdout`	boolean default: `false`	Print to stdout instead of writing a file.
`--force`	boolean default: `false`	Overwrite an existing .env.example without prompting.

stack env export --example

stack env export --stdout

stack env diff Which declared secrets are missing from the vault?

stack env diff [--json]

Flag	Type	Description
`--json`	boolean default: `false`	Emit machine-readable JSON (schema ashlr.stack.env-diff/v1, secret names only). Exits 1 when any are missing.

stack env diff

`stack deps`

Show the service dependency graph for this stack.

Renders an ASCII tree grouped by category, with every secret slot annotated beneath its service.

Synopsis

stack deps [--json]

Flags

Flag	Type	Description
`--json`	boolean	Emit machine-readable JSON (schema ashlr.stack.deps/v1).

Examples

stack deps

# ashlr.stack.deps/v1 for agents
stack deps --json

`stack doctor`

Verify every service is reachable and credentials are valid.

Synopsis

stack doctor [--fix] [--all] [--json] [--reconcile]

Flags

Flag	Type	Description
`--fix`	boolean default: `false`	Attempt to auto-remediate by re-running `stack add` for failing services.
`--all`	boolean default: `false`	Run doctor across every registered project on this machine.
`--json`	boolean default: `false`	Emit machine-readable JSON (exit 0/1 on pass/fail). CI-friendly.
`--reconcile`	boolean default: `false`	Check whether .stack.toml services are still present in source code.

Examples

stack doctor

stack doctor --fix

# CI-friendly
stack doctor --json > report.json

# every Stack project on this box
stack doctor --all

`stack exec`

Run a command with Phantom's secret proxy active.

Thin wrapper over `phantom exec` so env vars with phm_ tokens get swapped for real secrets at the network layer.

Synopsis

stack exec

Examples

stack exec -- bun dev

stack exec -- npm test

`stack swap`

Migrate a project from one provider to an equivalent in the same category.

Synopsis

stack swap <path> <to> [--dryRun] [--noRollback] [--keepFrom]

Flags

Flag	Type	Description
`<path>` req	positional	Provider to remove (e.g. clerk).
`<to>` req	positional	Provider to provision (e.g. auth0).
`--dryRun`	boolean default: `false`	Print the plan without executing any steps.
`--noRollback`	boolean default: `false`	On failure, leave partial state in place instead of rolling back.
`--keepFrom`	boolean default: `false`	Provision `to` without removing `from` (side-by-side migration).

`stack sync`

Push secrets to a deployment platform (via phantom sync).

Synopsis

stack sync --platform <name>

Flags

Flag	Type	Description
`--platform <name>` req	string	One of: vercel, railway, fly

Examples

stack sync --platform vercel

`stack onboard`

Detect Codex, Claude Code, Cursor and Gemini CLI and register the Phantom gateway in each (plan by default).

Synopsis

stack onboard [--apply] [--undo] [--client <client>] [--all] [--home <home>] [--json]

Flags

Flag	Type	Description
`--apply`	boolean	Write the changes. Without this flag nothing is written.
`--undo`	boolean	Restore the files saved by the last --apply.
`--client <client>`	string	Comma list: claude,codex,cursor,gemini. Default: all.
`--all`	boolean	Also wire clients that are not detected.
`--home <home>`	string	Home directory to use (default: your home).
`--json`	boolean	Emit JSON.

Examples

plan only, nothing is written
stack onboard

stack onboard --apply

stack onboard --undo

`stack open`

Open a service's dashboard in your browser.

Synopsis

stack open <service>

Flags

Flag	Type	Description
`<service>` req	positional	Service name.

Examples

stack open supabase

stack open vercel

`stack login`

Refresh OAuth / PAT credentials for a specific provider.

Synopsis

stack login <service>

Flags

Flag	Type	Description
`<service>` req	positional	Provider name.

Examples

stack login github

stack login supabase

`stack telemetry`

Opt into / out of anonymous usage telemetry. See docs/PRIVACY.md.

Synopsis

stack telemetry <status|enable|disable>

Subcommands

stack telemetry status Show telemetry opt-in status.

stack telemetry status

stack telemetry enable Opt in to anonymous usage telemetry.

stack telemetry enable

stack telemetry disable Opt out of telemetry.

stack telemetry disable

`stack templates`

List or apply starter stack templates.

Synopsis

stack templates <list|apply>

Flags

Flag	Type	Description
`--json`	boolean default: `false`	Emit machine-readable JSON (schema ashlr.stack.templates/v1).

Subcommands

stack templates list List available templates.

stack templates list [--json]

Flag	Type	Description
`--json`	boolean default: `false`	Emit machine-readable JSON (schema ashlr.stack.templates/v1).

stack templates list

stack templates apply Apply a template — runs `stack add` for each service listed.

stack templates apply <name> [--continueOnError]

Flag	Type	Description
`<name>` req	positional	Template name.
`--continueOnError`	boolean default: `true`	Keep going when a single service fails (default: true).

stack templates apply nextjs-supabase-posthog

`stack providers`

List every curated provider Stack can wire up.

Synopsis

stack providers [--category <category>] [--json]

Flags

Flag	Type	Description
`--category <category>`	string	Only this category, any case (database, deploy, cloud, ai, analytics, observability, errors, payments, code, tickets, email, auth, featureflags).
`--json`	boolean	Emit machine-readable JSON (schema ashlr.stack.providers/v1).

Examples

stack providers

# ashlr.stack.providers/v1 for agents
stack providers --json

`stack recommend`

Pick the right providers for what you're building (AI-assisted).

Synopsis

stack recommend [query] [--k <n>] [--category <category>] [--json] [--save] [--synth]

Flags

Flag	Type	Description
`[query]`	positional	Free-text description of the project (in quotes).
`--k <n>`	string	Max results to return (default 6).
`--category <category>`	string	Restrict to a single category, any case (Database, Deploy, Cloud, AI, Analytics, Observability, Errors, Payments, Code, Tickets, Email, Auth, FeatureFlags).
`--json`	boolean	Machine-readable JSON output.
`--save`	boolean	Persist the result as .stack/recipes/<id>.toml so you can run `stack apply <id>`.
`--synth`	boolean	Call the local SLM (LM Studio / Ollama) to synthesize rationales. Silently falls back to retrieval-only when no endpoint is reachable.

Examples

stack recommend "next.js app with auth and postgres"

stack recommend --json "realtime websockets"

`stack apply`

Apply a saved recipe: provision each provider, check its secrets in Phantom, and add webhook stubs.

The golden path is `stack recommend --save && stack apply <id>`. Auto-inits a blank .stack.toml if none exists.

Synopsis

stack apply [id] [--noWire] [--noRollback]

Flags

Flag	Type	Description
`[id]`	positional	Recipe id (filename stem in .stack/recipes). Omit for picker.
`--noWire`	boolean default: `false`	Skip the Phantom vault check and webhook stubs.
`--noRollback`	boolean default: `false`	On partial failure, leave successfully-added services in .stack.toml instead of rolling them back.

Examples

stack apply

stack apply my-recipe

`stack projects`

Manage the cross-project registry at ~/.stack/projects.json.

Synopsis

stack projects <list|register|remove|where>

Flags

Flag	Type	Description
`--json`	boolean default: `false`	Emit machine-readable JSON (schema ashlr.stack.projects/v1).

Subcommands

stack projects list List every Stack-enabled project on this machine.

stack projects list [--json]

Flag	Type	Description
`--json`	boolean default: `false`	Emit machine-readable JSON (schema ashlr.stack.projects/v1).

stack projects list

stack projects register Register the current directory in the registry.

stack projects register

stack projects register

stack projects remove Remove a project from the registry (does not delete files).

stack projects remove <name|path>

Flag	Type	Description
`<name\|path>` req	positional	Project name or absolute path.

stack projects remove my-app

stack projects where Print the path of a registered project.

stack projects where <name>

Flag	Type	Description
`<name>` req	positional	Project name.

# jump into a project by name
cd $(stack projects where my-app)

`stack ci`

CI workflow generation (unavailable; use `stack doctor` instead).

Synopsis

stack ci <init>

Flags

Flag	Type	Description
`--json`	boolean default: `false`	Emit the refusal as JSON ({ error }) on stdout.

Subcommands

stack ci init Unavailable: refuses with what to run instead (stack doctor). Never writes a workflow.

stack ci init [--force] [--json]

Flag	Type	Description
`--force`	boolean default: `false`	Compatibility flag; generation is unavailable and no workflow is overwritten.
`--json`	boolean default: `false`	Emit the refusal as JSON ({ error }) on stdout.

stack ci init

`stack completion`

Emit shell completion for bash, zsh, or fish.

Synopsis

stack completion <shell>

Flags

Flag	Type	Description
`<shell>` req	positional	One of: bash, zsh, fish.

Examples

stack completion zsh > ~/.local/share/zsh/site-functions/_stack

stack completion bash | sudo tee /etc/bash_completion.d/stack

stack completion fish > ~/.config/fish/completions/stack.fish

`stack upgrade`

Check npm for a newer @ashlr/stack release.

Checks the npm registry for a newer version, prints an install hint — does not auto-install.

Synopsis

stack upgrade [--dryRun] [--json]

Flags

Flag	Type	Description
`--dryRun`	boolean	Print what would be installed without running the install command.
`--json`	boolean default: `false`	Emit machine-readable JSON (schema ashlr.stack.upgrade/v1): current, latest, status and the install command.

Examples

stack upgrade