Skip to content

state

Terminal window
alchemy state <subcommand> [file] [options]

Inspect and manage the state store — the record of which resources alchemy thinks exist for each stack/stage. Reads from whatever state layer the stack file configures (e.g. Cloudflare.state(...)), or from the on-disk .alchemy/state directory with --local. See State Store.

The stack file is imported only to resolve its configured state layer — pass it via the standard [file] positional (defaults to alchemy.run.ts). There is no deploy-style --stage here: state commands address what they inspect explicitly, so --stack, --stage, and --fqn are addressing flags that appear only on the subcommands that need them.

All six subcommands share these options:

OptionDescription
--localRead from local .alchemy/state instead of the stack’s configured state store — e.g. to inspect orphaned local state after a partially-failed bootstrap
--profile <name>Auth profile to use (defaults to default or $ALCHEMY_PROFILE)
--env-file <path>Load environment variables from a file

state stacks

Section titled “state stacks”
Terminal window
alchemy state stacks [file] [options]

List every stack name present in the state store.

state stages

Section titled “state stages”
Terminal window
alchemy state stages --stack <stack> [file] [options]

List every stage that has state recorded under --stack.

state resources

Section titled “state resources”
Terminal window
alchemy state resources --stack <stack> --stage <stage> [file] [options]

List the fully-qualified resource names (FQNs) tracked under a given stack/stage.

state get

Section titled “state get”
Terminal window
alchemy state get --stack <stack> --stage <stage> --fqn <fqn>

Print a single resource’s persisted state as JSON. Output uses the same encoding the store persists: redacted secrets are unwrapped into { __redacted__: ... } and Resources are flattened. If no entry exists, it prints (not found: <stack>/<stage>/<fqn>).

Terminal window
# get the FQN from `state resources`, then:
alchemy state get --stack MyApp --stage prod --fqn Bucket

state tree

Section titled “state tree”
Terminal window
alchemy state tree [file] [options]

Render the entire state store as a tree of stacks → stages → resources. See Inspecting State for a worked example.

state clear

Section titled “state clear”
Terminal window
alchemy state clear [--stack <stack>] [--stage <stage>] [file] [options]

Delete state entries from the store.

  • Omit --stack to clear all stacks in the store.
  • Pass --stack to clear every stage under that stack.
  • Pass --stack and --stage to clear a single stage.
  • --stage without --stack is an error.

A confirmation prompt lists the exact scope before anything is deleted.

OptionDescription
--yesSkip the confirmation prompt

Where next

Section titled “Where next”