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 24 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 a service from the stack (vault entries and MCP config). 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 sync Push secrets to a deployment platform (via phantom sync). stack open Open a service's dashboard in your browser. stack login Refresh OAuth / PAT credentials for a specific provider. 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 + pre-wire Phantom rotation. stack projects Manage the cross-project registry at ~/.stack/projects.json. stack ci Scaffold CI integrations that run `stack doctor` on pushes + nightly. 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]

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.

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 a service from the stack (vault entries and MCP config).

Synopsis

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

Flags

Flag	Type	Description
`[service]`	positional	Service name. Omit with --all to remove every service.
`--all`	boolean default: `false`	Remove every service in this stack (with confirmation).
`--allOrphans`	boolean default: `false`	Detect services configured in .stack.toml but no longer present in source, then remove them.
`--keepRemote`	boolean default: `false`	Leave the provider-side resource untouched (don't deprovision).

Examples

stack remove supabase

stack remove --all --keepRemote

`stack list`

List services configured in this stack.

Synopsis

stack list

Examples

stack list

`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>

Flags

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

Examples

stack info supabase

`stack status`

Show stack health at a glance.

Synopsis

stack status

Examples

stack status

`stack env`

Inspect the effective env-var map for this stack.

Synopsis

stack env <show|export|diff>

Subcommands

stack env show Show which secrets are present in Phantom.

stack env show [--env <env>]

Flag	Type	Description
`--env <env>`	string default: `dev`	Environment overlay to preview.

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

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

Examples

stack deps

`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 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 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 templates`

List or apply starter stack templates.

Synopsis

stack templates <list|apply>

Subcommands

stack templates list List available templates.

stack templates list

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

Examples

stack providers

`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 (e.g. Database, Auth).
`--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 + pre-wire Phantom rotation.

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 Phantom envelope + webhook pre-wiring (opts out of the moat).
`--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>

Subcommands

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

stack projects list

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`

Scaffold CI integrations that run `stack doctor` on pushes + nightly.

Synopsis

stack ci <init>

Subcommands

stack ci init Write .github/workflows/stack-ci.yml for GitHub Actions.

stack ci init [--force]

Flag	Type	Description
`--force`	boolean default: `false`	Overwrite an existing stack-ci.yml.

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]

Flags

Flag	Type	Description
`--dryRun`	boolean	Print what would be installed without running the install command.

Examples

stack upgrade