sailfork / t3code-github / .repos/ alchemy-effect/ website/ src/ content/ docs/ cli/ inspecting-state.mdx

import Terminal from "../../../components/Terminal.astro";

What does alchemy think is deployed?

bun alchemy state

<Terminal content={AlchemyEffectWebsite ├─ dev_sam │ ├─ Bucket │ └─ Worker └─ prod ├─ Bucket └─ Worker} />

In an interactive terminal, bare alchemy state opens the state explorer. It is a browsable tree of stacks, stages, and resources with a YAML preview of the selected state. This is the record used by the next plan, not the live cloud. See State Store. Full flag reference: state.

For scripts, drill down one level at a time with state list:

bun alchemy state list

Lists every stack in the store.

bun alchemy state list myapp

Lists every stage recorded under myapp.

bun alchemy state list myapp/dev_sam

Prints the state entries tracked under that stack and stage. Pass these paths to state read.

Or skip the drilling entirely and read the whole estate at once:

bun alchemy state read -r | jq 'to_entries[] | select(.value.resourceType == "AWS.EC2.Instance")'

One call returns every record across all stacks and stages as a single JSON document to filter locally — see state read.

Debugging a bad diff

bun alchemy state read myapp/dev_sam/Bucket

This is the persisted props/attrs the planner diffs against — see state for the output encoding. Compare it with what alchemy plan says it wants to change. Three usual causes:

Wrong stage. --stage defaults to live_$USER (e.g. live_sam), so a plan that "wants to create everything" often just means you're looking at a stage you never deployed. Run state list myapp and confirm which stage actually has state.

Drift. The cloud changed out-of-band — someone edited the resource in a console or another tool. state read shows what alchemy last persisted; the reconciler converges observed cloud state to the desired state on the next deploy (see Resource Lifecycle).

Stale state from a partially-failed deploy. If a deploy crashed after mutating the cloud but before persisting, the record lags reality. Check the persisted attributes against what actually exists before reaching for state delete.

Recover from bad state

When the record is beyond repair, delete it and redeploy. state delete only deletes Alchemy's local record. It does not delete cloud resources:

# one stage
bun alchemy state delete myapp/pr-42

# a whole stack
bun alchemy state delete myapp

Then deploy — resources alchemy owns are re-imported automatically:

bun alchemy deploy

If the deploy fails with OwnedBySomeoneElse, escalate:

bun alchemy deploy --adopt

See Adopting Resources for why the flag is usually unnecessary.

Orphaned local state

Pass --backend local to any state subcommand to read the on-disk .alchemy/state directory instead of the stack's configured store. The canonical use: a Cloudflare state-store bootstrap was interrupted and left resources recorded only locally.

# wipe local state after a botched bootstrap
bun alchemy state delete myapp --backend local

See cloudflare for bootstrap repair.

Where next