Help

FAQ

Q: Is this production-ready?

These docs describe reviewed source 0.2.1, not a new release or production acceptance. Recorded public CLI/MCP packages are 0.1.1; historical native 0.2.0 is separate. Interfaces and provider coverage vary. Check the installed version and help; no future CLI stability or migration guarantee follows from this source.

Q: Which providers still fall back to paste-a-token?

Most source adapters accept a supplied PAT or API-key input. Supabase has an available OAuth branch and GitHub has a device-flow branch, with fallback requirements. Verification can be a limited endpoint or local structure check; catalog authKind alone is not evidence of account access or every credential.

Q: Does Stack touch the internet without asking?

Authorized setup, login, health checks, sync, cloning, optional inference and dependency installation can contact external services. The CLI also starts a version check unless suppressed and can send opted-in telemetry. Review each command and its current configuration; this is not an exhaustive no-network guarantee.

Q: What happens if I delete .stack.toml?

Deleting .stack.toml does not delete upstream resources or Phantom secrets. Preserve a copy if you need its service references. stack remove or stack remove --all removes local service/MCP configuration and attempts Phantom secret cleanup; upstream resources are kept in every mode. --keepRemote is a compatibility flag. Headless cleanup or refused confirmation can leave secrets stored; inspect the result and use the Phantom Secrets guidance for manual cleanup.

Q: Can I commit .env.local with phm_ tokens?

Keep env and local-instance files private and review them before sharing. Stack does not establish that phm_ strings or user-supplied metadata are harmless or safe to commit. Export an empty-key .env.example with stack env export --example when you need a shareable starting point.

Q: How do I use Stack with a monorepo?

Run commands in the intended app directory. The local projects registry records known registrations and can prune missing entries; it is not an inventory of every project on the machine. Doctor --all covers registered projects and available checks. Shared vault names can collide or be reused; verify ownership and each consumer.

Q: What does stack doctor --fix actually do?

It can attempt setup for failed entries after its current checks and confirmations. Existing vault names can cause a repair to be skipped; cached credentials or cleanup may refuse in a noninteractive terminal. Inspect the reported effects and unchecked services. Fix does not rotate dashboard credentials or guarantee complete repair.

Q: Can I use a template without its MCP servers?

Use stack init --template --noProvision to inspect config without provider setup. The mcp name in config is metadata; editing it does not regenerate every descriptor. Review the project .mcp.json and client configuration before startup; add/remove only affect entries they actually manage.

The honest answers. Pre-alpha caveats, the Phantom requirement, OAuth app status, and what happens when things go sideways.

Is this production-ready?

These docs describe source 0.2.1. Recorded public CLI/MCP packages are 0.1.1; historical native 0.2.0 is separate. Neither the docs nor a source version establishes production or provider acceptance.

The two-file .stack.toml format and conditional MCP/credential operations are described in source. Check installed help during the 0.x period; no future compatibility policy at 1.0 is established by these implementations.

Why is Phantom required?

Real credential-writing workflows use the installed Phantom interface and project preflight. Stack records dedicated names rather than filling .env files automatically; it still handles values in memory.

Phantom configuration, permissions, supported execution and any sync integration need their own setup and verification. Confirm those before real stack add credential operations.

Which providers still fall back to paste-a-token?

Source adapters use different authentication branches. These include personal-access-token paste and key inputs; available verification may check a limited endpoint or only local structure:

Neon, Turso, Vercel, Cloudflare, Sentry — provider-specific PAT inputs and checks.
Railway, Fly.io, Render, Upstash, Convex, Linear, Resend, PostHog, Clerk, Stripe, OpenAI, Anthropic, xAI, DeepSeek — API key paste.
Firebase — service-account JSON paste.
AWS — IAM access key pair paste.

OAuth branches exist in source for Supabase and GitHub, with configuration and fallback requirements. Catalog labels such as authKind: "api_key" | "pat" | "oauth_pkce" | "oauth_device" do not prove live account access or future behavior.

Does Stack touch the internet without asking?

These workflows can contact services; this list is not exhaustive:

stack add — runs adapter-specific auth, creation or attachment and credential steps.
stack doctor — runs available adapter checks, whose coverage varies.
stack upgrade — pings the npm registry to check for a newer @ashlr/stack.
stack login — refreshes OAuth / PAT credentials.
stack sync — pushes secrets to Vercel / Railway / Fly.
stack clone — git clones the specified URL, then scans locally.

The CLI also starts a version check unless suppressed, and telemetry can send opted-in command metadata. Optional inference and dependency installation have their own contacts. Review current settings and effects.

What happens if I delete `.stack.toml`?

Your upstream resources stay exactly as they were. Stack would just lose its map of what it had wired. The secrets in Phantom also stay put. You'd see "no services configured" on stack status; running stack init again would start fresh.

stack remove <service> or stack remove --all removes local service and MCP configuration and attempts Phantom secret cleanup. Upstream resources are kept in every mode; --keepRemote is a compatibility flag. Headless cleanup or refused confirmation can leave secrets stored. Inspect the result and consult the Phantom Secrets guidance for manual cleanup.

Can I commit `.env.local` with phm_ tokens?

Keep phm_ strings, user-supplied metadata and local-instance data private unless separately reviewed. Do not assume a token is harmless. Keep .env.local out of shared commits with .gitignore; use an empty-key env example when sharing setup documentation.

How do I use Stack with a monorepo?

Each .stack.toml is per-project, and most monorepos want one stack per app (marketing site, dashboard, worker all have different services). Run stack init inside each app directory. The cross-project registry (stack projects list) shows known local registrations and may prune missing entries. stack doctor --all covers those projects and available checks.

Shared secrets (e.g. one DATABASE_URL used by every app) can reuse or collide with existing vault names. Check the intended ownership and each app's inputs before sharing a slot across .stack.toml files.

What does `stack doctor --fix` actually do?

The fix path can attempt stack add for failed entries after its checks and confirmations. Existing vault names can skip repair; cached credentials and cleanup may refuse in a noninteractive terminal. Inspect reported effects and unchecked services rather than assuming credential rotation or complete repair.

Why not just use `.env` files like everyone else?

Stack can coordinate repeated provider setup and local configuration. It does not automatically populate .env files or replace application integration. Its usefulness depends on the adapters you need.

Stack earns its keep when (a) your stack has 5+ services, (b) two or more of them have MCP servers worth wiring, or (c) you're onboarding someone new and don't want to write a wiki page about where every key lives.

Can I use a template without its MCP servers?

Use template init with --noProvision to inspect .stack.toml first. A mcp = "…" name is metadata; editing it does not regenerate all descriptors. stack add and stack remove affect entries they actually manage. Review .mcp.json and client configuration before startup.

Where does Stack store OAuth access tokens?

Credential persistence uses per-provider Phantom names (e.g. SUPABASE_STACK_PAT, GITHUB_TOKEN). Setup can stage new inputs; explicit login stores immediately. Existing values are not automatically overwritten or rotated. Use installed Phantom guidance for phantom remove <slot> and reconcile dependent consumers.

How do I uninstall Stack?

# Optional local cleanup: upstream resources are kept; secrets may remain
stack remove --all

# Uninstall the CLI
bun remove -g @ashlr/stack   # or: npm uninstall -g @ashlr/stack

# Inspect and back up project configuration and the local registry
# before deleting files. Phantom is a separate install; follow its
# qualified cleanup guidance at https://phm.dev/secrets.

Where do I report bugs / request providers?

github.com/ashlrai/ashlr-stack/issues. Provider requests are most useful when they include: the secret slots you'd expect, whether the provider has an API for creating resources (upstream provisioning) or only an API for reading them, and whether there's an existing MCP server worth wiring.

FAQ