clover's git

the-knife

1	---
2	title: state
3	description: Browse, read, and delete entries in the state store.
4	---
5
6	```sh
7	alchemy state [subcommand] [options]
8	```
9
10	Inspect and manage the state store — the record of which resources
11	alchemy thinks exist for each stack/stage. Reads from whatever state
12	layer the stack file configures (e.g. `Cloudflare.state(...)`), or
13	from the on-disk `.alchemy/state` directory with `--backend local`.
14	See [State Store](/state-store).
15
16	Run `alchemy state` with no subcommand in an interactive terminal to
17	open the **state explorer**. It shows stacks, stages, resources, and a YAML
18	preview of the selected resource's persisted state. Mark
19	entries with Space and delete them with `d`; a confirm dialog lists the
20	exact records before anything is removed. The subcommands below are the
21	scriptable equivalents.
22
23	The stack file is imported only to resolve its configured state layer
24	Pass it with `--config`, which defaults to `alchemy.run.ts`. There is no
25	deploy-style `--stage` flag here: state commands address what they
26	inspect explicitly through positional arguments.
27
28	All subcommands share these options:
29
30	| Option | Description |
31	| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
32	| `--backend <configured\|local>` | `configured` uses the stack's state layer; `local` reads `.alchemy/state`, including orphaned state after a failed bootstrap |
33	| `--profile <name>` | Auth profile to use (defaults to `$ALCHEMY_PROFILE` or `default`) |
34	| `--env-file <path>` | Load environment variables from a file |
35	| `--config, -c <file>` | Stack entrypoint to resolve the state layer from (defaults to `alchemy.run.ts`) |
36
37	## `state list`
38
39	```sh
40	alchemy state list [path] [options] # alias: ls
41	```
42
43	State is addressed like a filesystem: `<stack>/<stage>/<namespace…>/
44	<resource>`, plus one `output` entry per stage holding the stack's
45	evaluated outputs. `list` prints one directory level; `--recursive`/`-r`
46	walks the whole subtree.
47
48	```sh
49	alchemy state list # every stack
50	alchemy state list my-app # stages under my-app
51	alchemy state list my-app/prod # resource entries under my-app/prod
52	alchemy state list my-app -r # every path under my-app
53	```
54
55	## `state read`
56
57	```sh
58	alchemy state read [path] [options] # alias: cat
59	```
60
61	Print persisted state as JSON. A resource path prints that record; a
62	directory path with `--recursive` prints every record beneath it, keyed
63	by path. Output uses the same encoding the store persists: redacted
64	secrets are unwrapped into `{ __redacted__: ... }` and Resources are
65	flattened.
66
67	```sh
68	# one resource record
69	alchemy state read my-app/prod/Bucket
70
71	# a whole stage as one JSON document for jq
72	alchemy state read my-app/prod -r | jq 'to_entries[] | select(.value.resourceType == "AWS.EC2.Instance")'
73
74	# diff two stages
75	diff <(alchemy state read my-app/dev -r) \
76	<(alchemy state read my-app/prod -r)
77	```
78
79	## `state delete`
80
81	```sh
82	alchemy state delete <path> [options] # alias: rm
83	```
84
85	Delete state records. Deleting a stack or stage path removes everything
86	beneath it; a directory path below stage level needs `--recursive`.
87	`output` cannot be deleted independently. Alchemy removes it with its
88	stage.
89
90	| Option | Description |
91	| ------------------- | ---------------------------------- |
92	| `--recursive`, `-r` | Operate recursively on directories |
93
94	:::caution
95	**Destructive but local-only** — the actual cloud resources are not
96	touched, only alchemy's record of them. A subsequent `deploy`
97	re-imports owned resources automatically; see
98	[Inspecting State](/cli/inspecting-state) for the recovery workflow
99	and [Adopting Resources](/cli/adopting-resources) for when `--adopt`
100	is needed.
101	:::
102
103	## Where next
104
105	- [Inspecting State](/cli/inspecting-state) — debugging and recovery workflows
106	- [Adopting Resources](/cli/adopting-resources) — how deploy reclaims existing infrastructure
107	- [State Store](/state-store) — where resource state lives