clover's git

the-knife

1	---
2	title: Inspecting State
3	description: See what alchemy thinks is deployed, debug a bad diff, and recover from bad state.
4	---
5
6	import Terminal from "../../../components/Terminal.astro";
7
8	## What does alchemy think is deployed?
9
10	```sh
11	bun alchemy state
12	```
13
14	<Terminal content={`AlchemyEffectWebsite
15	├─ dev_sam
16	│ ├─ Bucket
17	│ └─ Worker
18	└─ prod
19	├─ Bucket
20	└─ Worker`} />
21
22	In an interactive terminal, bare `alchemy state` opens the state
23	explorer. It is a browsable tree of stacks, stages, and resources with a YAML
24	preview of the selected state. This is the record used by the next plan, not
25	the live cloud. See [State Store](/state-store). Full flag reference:
26	[state](/cli/state).
27
28	For scripts, drill down one level at a time with `state list`:
29
30	```sh
31	bun alchemy state list
32	```
33
34	Lists every stack in the store.
35
36	```sh
37	bun alchemy state list myapp
38	```
39
40	Lists every stage recorded under `myapp`.
41
42	```sh
43	bun alchemy state list myapp/dev_sam
44	```
45
46	Prints the state entries tracked under that stack and stage. Pass these paths to
47	`state read`.
48
49	Or skip the drilling entirely and read the whole estate at once:
50
51	```sh
52	bun alchemy state read -r | jq 'to_entries[] | select(.value.resourceType == "AWS.EC2.Instance")'
53	```
54
55	One call returns every record across all stacks and stages as a
56	single JSON document to filter locally — see
57	[state read](/cli/state#state-read).
58
59	## Debugging a bad diff
60
61	```sh
62	bun alchemy state read myapp/dev_sam/Bucket
63	```
64
65	This is the persisted props/attrs the planner diffs against — see
66	[state](/cli/state) for the output encoding. Compare it with what
67	`alchemy plan` says it wants to change. Three usual causes:
68
69	**Wrong stage.** `--stage` defaults to `live_$USER` (e.g. `live_sam`),
70	so a plan that "wants to create everything" often just means you're
71	looking at a stage you never deployed. Run
72	`state list myapp` and confirm which stage actually has state.
73
74	**Drift.** The cloud changed out-of-band — someone edited the
75	resource in a console or another tool. `state read` shows what alchemy
76	last persisted; the reconciler converges observed cloud state to the
77	desired state on the next deploy (see
78	[Resource Lifecycle](/infrastructure-as-code/resource-lifecycle)).
79
80	**Stale state from a partially-failed deploy.** If a deploy crashed
81	after mutating the cloud but before persisting, the record lags
82	reality. Check the persisted attributes against what actually exists
83	before reaching for `state delete`.
84
85	## Recover from bad state
86
87	When the record is beyond repair, delete it and redeploy.
88	`state delete` only deletes Alchemy's local record. It does not delete cloud
89	resources:
90
91	```sh
92	# one stage
93	bun alchemy state delete myapp/pr-42
94
95	# a whole stack
96	bun alchemy state delete myapp
97	```
98
99	Then deploy — resources alchemy owns are re-imported automatically:
100
101	```sh
102	bun alchemy deploy
103	```
104
105	If the deploy fails with `OwnedBySomeoneElse`, escalate:
106
107	```sh
108	bun alchemy deploy --adopt
109	```
110
111	See [Adopting Resources](/cli/adopting-resources) for why the flag is
112	usually unnecessary.
113
114	## Orphaned local state
115
116	Pass `--backend local` to any `state` subcommand to read the on-disk
117	`.alchemy/state` directory instead of the stack's configured store.
118	The canonical use: a Cloudflare state-store bootstrap was interrupted
119	and left resources recorded only locally.
120
121	```sh
122	# wipe local state after a botched bootstrap
123	bun alchemy state delete myapp --backend local
124	```
125
126	See [cloudflare](/cli/cloudflare) for bootstrap repair.
127
128	## Where next
129
130	- [state](/cli/state) — full subcommand and flag reference
131	- [Adopting Resources](/cli/adopting-resources) — ownership and `--adopt`
132	- [cloudflare](/cli/cloudflare) — state-store bootstrap
133	- [State Store](/state-store) — where resource state lives