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 seven subcommands share these options:

Option Description
--local Read 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 export

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

Bulk state read: print every matching resource record as one JSON document, so a whole estate is read in a single invocation instead of state resources + one state get per FQN per stack/stage.

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

The output is a flat resources array; each entry carries its stack, stage, and fqn alongside the same encoded record state get prints (props and attr intact, secrets as { __redacted__: ... }):

{
  "resources": [
    {
      "stack": "my-app",
      "stage": "prod",
      "fqn": "WebServer",
      "state": {
        "resourceType": "AWS.EC2.Instance",
        "props": { "instanceType": "t3.large" },
        "attr": { "instanceId": "i-0456" }
      }
    }
  ]
}

The flat shape is made for local filtering — one call, then jq:

Terminal window
# every EC2 instance across all stacks and stages
alchemy state export | jq '.resources[] | select(.state.resourceType == "AWS.EC2.Instance")'


# diff two stages
diff <(alchemy state export --stack my-app --stage dev) \
     <(alchemy state export --stack my-app --stage prod)

Entries are ordered deterministically (stack, then stage, then FQN), so exports are stable across runs and safe to diff or assert on in CI.

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.

Option Description
--yes Skip the confirmation prompt

Where next

Section titled “Where next”