Skip to content
stack
Get started
CLI

stack add

Set up one provider, attempt credential and MCP/config writes, and optionally install its SDK. Cleanup on failure is best-effort.

Basic usage

stack add supabase
stack add clerk
stack add resend

For the full flag reference, see the CLI reference. This page covers the three behaviours that aren't obvious from the synopsis: optional SDK installation, best-effort rollback, and env export.

SDK auto-install

After provisioning and persisting a service's secrets, Stack checks whether the provider ships an SDK package (e.g. @supabase/supabase-js, @clerk/nextjs). If it does, Stack detects your project's package manager and prompts once: 

◇  Install @supabase/supabase-js? (detected: bun)
│  Yes / No (illustrative prompt)

Detection order: bun.lock → pnpm-lock.yaml → yarn.lock → package-lock.json → package.json. Falls back to npm if none are found.

Override the prompt with the --install flag:

# Always install without asking
stack add supabase --install=always

# Never install (useful in CI or monorepos where you manage deps separately)
stack add supabase --install=never

# Default: prompt once (same as omitting the flag)
stack add supabase --install=ask

Best-effort cleanup

stack add runs a multi-step pipeline: provider auth → resource creation or attachment → materialization → credential writes → MCP merge → split-config writes. New managed login inputs are staged; resource-critical credentials can be committed before materialization completes. On failure, Stack attempts cleanup of its owned writes and newly created resources. Existing resources and stored keys are separate, and partial state can remain. 

# Illustrative failure; inspect the actual cleanup result
┌  stack add neon
│
◆  Provisioning neon...
│  ✓ Created project "my-app" (ep-quiet-frost-a1b2c3d4)
│  ✗ Failed to write DATABASE_URL to Phantom: vault locked
│
◆  Rolling back...
│  ✓ Deleted neon project ep-quiet-frost-a1b2c3d4
│
└  ✗ neon was not added. Phantom vault must be unlocked.

Supabase, Neon, Turso and Vercel have resource cleanup implementations, but cleanup can fail or refuse. Vault removal requires the installed Phantom interface and confirmation; headless cleanup may keep keys. Inspect the original failure, retained resource references and cleanup result before deciding on manual recovery.

Use --dryRun to inspect the add plan before provider setup. The add parser has no rollback-disable flag. Multi-service stack init --template, stack apply and stack swap accept --noRollback, but a failed real setup or cleanup attempt is not proof that all earlier effects were undone.

Swap has its own setup and local cleanup sequence; it is not atomic. See stack swap. See Provider swap for details.

Generating .env.example

After adding services, generate an empty-value .env.example that lists declared secret keys with empty values for teammates and CI: 

stack env export --example
# .env.example — illustrative empty-key skeleton; review before sharing
# Values are placeholders only. Run `stack add <service>` to provision.

SUPABASE_URL=
SUPABASE_ANON_KEY=
SUPABASE_SERVICE_ROLE_KEY=
CLERK_SECRET_KEY=
CLERK_PUBLISHABLE_KEY=

The file is written to .env.example in the current working directory. Use --stdout to print the skeleton, or --force to overwrite an existing example. Dedicated values are not read from Phantom; the command emits catalog or declared key names with empty values. Review user-supplied names before sharing.