Skip to content

state

Terminal window
alchemy state [subcommand] [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 --backend local. See State Store.

Run alchemy state with no subcommand in an interactive terminal to open the state explorer. It shows stacks, stages, resources, and a YAML preview of the selected resource’s persisted state. Mark entries with Space and delete them with d; a confirm dialog lists the exact records before anything is removed. The subcommands below are the scriptable equivalents.

The stack file is imported only to resolve its configured state layer Pass it with --config, which defaults to alchemy.run.ts. There is no deploy-style --stage flag here: state commands address what they inspect explicitly through positional arguments.

All subcommands share these options:

Option Description
--backend <configured|local> configured uses the stack’s state layer; local reads .alchemy/state, including orphaned state after a failed bootstrap
--profile <name> Auth profile to use (defaults to $ALCHEMY_PROFILE or default)
--env-file <path> Load environment variables from a file
--config, -c <file> Stack entrypoint to resolve the state layer from (defaults to alchemy.run.ts)

state list

Section titled “state list”
Terminal window
alchemy state list [path] [options]      # alias: ls

State is addressed like a filesystem: <stack>/<stage>/<namespace…>/ <resource>, plus one output entry per stage holding the stack’s evaluated outputs. list prints one directory level; --recursive/-r walks the whole subtree.

Terminal window
alchemy state list                       # every stack
alchemy state list my-app                # stages under my-app
alchemy state list my-app/prod           # resource entries under my-app/prod
alchemy state list my-app -r             # every path under my-app

state read

Section titled “state read”
Terminal window
alchemy state read [path] [options]      # alias: cat

Print persisted state as JSON. A resource path prints that record; a directory path with --recursive prints every record beneath it, keyed by path. Output uses the same encoding the store persists: redacted secrets are unwrapped into { __redacted__: ... } and Resources are flattened.

Terminal window
# one resource record
alchemy state read my-app/prod/Bucket


# a whole stage as one JSON document for jq
alchemy state read my-app/prod -r | jq 'to_entries[] | select(.value.resourceType == "AWS.EC2.Instance")'


# diff two stages
diff <(alchemy state read my-app/dev -r) \
     <(alchemy state read my-app/prod -r)

state delete

Section titled “state delete”
Terminal window
alchemy state delete <path> [options]    # alias: rm

Delete state records. Deleting a stack or stage path removes everything beneath it; a directory path below stage level needs --recursive. output cannot be deleted independently. Alchemy removes it with its stage.

Option Description
--recursive, -r Operate recursively on directories

Where next

Section titled “Where next”