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 22 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 projects Manage the cross-project registry at ~/.stack/projects.json. stack upgrade Check npm for a newer @ashlr/stack release. stack completion Emit shell completion for bash, zsh, or fish. stack ci Scaffold CI integrations that run `stack doctor` on pushes + nightly.

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 <name>] [--force] [--noInteractive]

Flags

Flag	Type	Description
`--template <name>`	string	Name of a starter template to apply (e.g. nextjs-supabase-posthog). Omit to pick one interactively.
`--force`	boolean default: `false`	Overwrite an existing .stack.toml.
`--noInteractive`	boolean default: `false`	Skip the template picker — always create a blank .stack.toml.

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 <dir>] [--auto] [--confidence low|medium|high]

Flags

Flag	Type	Description
`--path <dir>`	string default: `.`	Directory to scan.
`--auto`	boolean default: `false`	After scanning, offer to run `stack add` for each detected provider interactively.
`--confidence <low\|medium\|high>`	string default: `medium`	Minimum confidence to surface.

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 <git-url> [dir]

Flags

Flag	Type	Description
`<git-url>` req	positional	GitHub / git URL to clone. Only https://, http://, ssh://, and git@host:org/repo forms are allowed.
`[dir]`	positional	Optional target directory (defaults to the repo name).

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 <r>] [--dryRun]

Flags

Flag	Type	Description
`[service]`	positional	Service name (supabase, neon, vercel, …). Omit for the interactive picker.
`--use <id>`	string	Attach to an existing resource by id instead of creating a new one.
`--region <r>`	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.

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] [--keepRemote]

Flags

Flag	Type	Description
`[service]`	positional	Service name. Omit with --all to remove every service in this stack.
`--all`	boolean default: `false`	Remove every service in this stack. Requires typing `remove all` to confirm.
`--keepRemote`	boolean default: `false`	Leave the provider-side resource untouched.

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

Subcommands

stack env show Show which secrets are present in Phantom.

stack env show [--env <name>]

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

stack env show

stack env show --env prod

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]

Flags

Flag	Type	Description
`--fix`	boolean default: `false`	Attempt auto-remediation by re-running `stack add` for failing services (asks before each).
`--all`	boolean default: `false`	Run doctor across every registered project on this machine.
`--json`	boolean default: `false`	Emit machine-readable JSON to stdout. Exit code: 0 if all healthy, 1 if any service failed.

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

Examples

stack exec -- bun dev

stack exec -- npm test

`stack sync`

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

Synopsis

stack sync --platform <vercel|railway|fly>

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 in the template.

stack templates apply <name> [--continueOnError]

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

stack templates apply nextjs-supabase-posthog

`stack providers`

List every curated provider Stack can wire up.

Synopsis

stack providers

Examples

stack providers

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

Examples

stack upgrade

`stack completion`

Emit shell completion for bash, zsh, or fish.

Synopsis

stack completion <bash|zsh|fish>

Flags

Flag	Type	Description
`<bash\|zsh\|fish>` req	positional	Shell to emit completion for.

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