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 <name> | configured (default) uses the stack's state layer; local reads .alchemy/state, including orphaned state after a failed bootstrap; a provider's store (aws, cloudflare) is reached from the profile alone, without a stack file |
--name <name> | With a provider store, address one other than the account's default, by logical name (1-20 lowercase letters, digits and hyphens) |
--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
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.
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
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.
# 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
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 |
:::caution
Destructive but local-only — the actual cloud resources are not
touched, only alchemy's record of them. A subsequent deploy
re-imports owned resources automatically; see
Inspecting State for the recovery workflow
and Adopting Resources for when --adopt
is needed.
:::
state bootstrap
alchemy state bootstrap [--backend <name>] [options] Provision a state store, or adopt it when it already exists. Idempotent. You normally don't need it: the first deploy that uses the store provisions it. Run it to provision ahead of time (for example before CI uses the store), or to repair an interrupted bootstrap.
Without --backend it provisions the store your entrypoint
(alchemy.run.ts, or --config) configures, with every option it sets,
such as a custom Worker or bucket name, a pinned account or a domain.
With --backend it provisions a provider's default store, or the one
--name names.
cloudflare: deploys the state-store Worker and creates its auth token and encryption key in the account's Secrets Store when they are missing. Existing secrets are never changed. An existing Worker is adopted and its credentials (~/.alchemy/profiles/<profile>/state-stores/cloudflare.json) are refreshed.aws: creates the state bucket with versioning, encryption, a public access block and owner-enforced ownership, or converges an existing one to those settings.
| Option | Description |
|---|---|
--force | cloudflare: redeploy the Worker even when it exists, keeping its secrets (with --backend) |
alchemy state bootstrap
alchemy state bootstrap --backend cloudflare
alchemy state bootstrap --backend cloudflare --profile staging --force
alchemy state bootstrap --backend aws --name team-a
alchemy state bootstrap --backend cloudflare --name team-a state teardown
alchemy state teardown --backend <name> [options] Delete a provider's state store and its backing resources: the
Cloudflare Worker, its secrets and cached credentials; or the S3 bucket
with every object version. Asks for confirmation unless --yes.
:::danger This deletes the state itself. Stacks whose state lived in the store lose their record of what they deployed; the cloud resources remain. :::
state logs
alchemy state logs --backend <name> [options] Fetch or stream the state store's own logs, to debug the store itself.
Only cloudflare keeps logs (from the state-store Worker, through the
Workers Observability API), which needs the workers_observability:read
and workers_observability_telemetry:write OAuth scopes (re-run
alchemy profile edit --reconfigure Cloudflare on older profiles).
| Option | Description |
|---|---|
--tail, -t | Stream logs as they happen instead of fetching past entries |
--limit <n> | Number of entries to fetch (default: 100). Ignored with --tail |
--since <time> | Fetch logs since a duration (1h, 30m, 2d) or ISO date |
alchemy state logs --backend cloudflare --since 30m --limit 200
alchemy state logs --backend cloudflare --tail Where next
- Inspecting State — debugging and recovery workflows
- Adopting Resources — how deploy reclaims existing infrastructure
- State Store — where resource state lives