@devries-cameron20 / t3code Mirror · read-only
Fork 0

The best way to control Claude Code, Codex and more from any computer or phone

Mirrored from https://github.com/Camo67/t3code.git

Synced Nov 21, 04:45 UTC

main
mdx 185 lines 7.79 KB
Raw
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 <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 |
33 | `--name <name>` | With a provider store, address one other than the account's default, by logical name (1-20 lowercase letters, digits and hyphens) |
34 | `--profile <name>` | Auth profile to use (defaults to `$ALCHEMY_PROFILE` or `default`) |
35 | `--env-file <path>` | Load environment variables from a file |
36 | `--config, -c <file>` | Stack entrypoint to resolve the state layer from (defaults to `alchemy.run.ts`) |
37
38 ## `state list`
39
40 ```sh
41 alchemy state list [path] [options] # alias: ls
42 ```
43
44 State is addressed like a filesystem: `<stack>/<stage>/<namespace…>/
45 <resource>`, plus one `output` entry per stage holding the stack's
46 evaluated outputs. `list` prints one directory level; `--recursive`/`-r`
47 walks the whole subtree.
48
49 ```sh
50 alchemy state list # every stack
51 alchemy state list my-app # stages under my-app
52 alchemy state list my-app/prod # resource entries under my-app/prod
53 alchemy state list my-app -r # every path under my-app
54 ```
55
56 ## `state read`
57
58 ```sh
59 alchemy state read [path] [options] # alias: cat
60 ```
61
62 Print persisted state as JSON. A resource path prints that record; a
63 directory path with `--recursive` prints every record beneath it, keyed
64 by path. Output uses the same encoding the store persists: redacted
65 secrets are unwrapped into `{ __redacted__: ... }` and Resources are
66 flattened.
67
68 ```sh
69 # one resource record
70 alchemy state read my-app/prod/Bucket
71
72 # a whole stage as one JSON document for jq
73 alchemy state read my-app/prod -r | jq 'to_entries[] | select(.value.resourceType == "AWS.EC2.Instance")'
74
75 # diff two stages
76 diff <(alchemy state read my-app/dev -r) \
77 <(alchemy state read my-app/prod -r)
78 ```
79
80 ## `state delete`
81
82 ```sh
83 alchemy state delete <path> [options] # alias: rm
84 ```
85
86 Delete state records. Deleting a stack or stage path removes everything
87 beneath it; a directory path below stage level needs `--recursive`.
88 `output` cannot be deleted independently. Alchemy removes it with its
89 stage.
90
91 | Option | Description |
92 | ------------------- | ---------------------------------- |
93 | `--recursive`, `-r` | Operate recursively on directories |
94
95 :::caution
96 **Destructive but local-only** — the actual cloud resources are not
97 touched, only alchemy's record of them. A subsequent `deploy`
98 re-imports owned resources automatically; see
99 [Inspecting State](/cli/inspecting-state) for the recovery workflow
100 and [Adopting Resources](/cli/adopting-resources) for when `--adopt`
101 is needed.
102 :::
103
104 ## `state bootstrap`
105
106 ```sh
107 alchemy state bootstrap [--backend <name>] [options]
108 ```
109
110 Provision a state store, or adopt it when it already exists.
111 Idempotent. You normally don't need it: the first deploy that uses the
112 store provisions it. Run it to provision ahead of time (for example
113 before CI uses the store), or to repair an interrupted bootstrap.
114
115 Without `--backend` it provisions the store your entrypoint
116 (`alchemy.run.ts`, or `--config`) configures, with every option it sets,
117 such as a custom Worker or bucket name, a pinned account or a domain.
118 With `--backend` it provisions a provider's default store, or the one
119 `--name` names.
120
121 - `cloudflare`: deploys the state-store Worker and creates its auth
122 token and encryption key in the account's Secrets Store when they are
123 missing. Existing secrets are never changed. An existing Worker is
124 adopted and its credentials
125 (`~/.alchemy/profiles/<profile>/state-stores/cloudflare.json`) are
126 refreshed.
127 - `aws`: creates the state bucket with versioning, encryption, a public
128 access block and owner-enforced ownership, or converges an existing one
129 to those settings.
130
131 | Option | Description |
132 | --------- | ------------------------------------------------------------------------------------------------------------- |
133 | `--force` | `cloudflare`: redeploy the Worker even when it exists, keeping its secrets (with `--backend`) |
134
135 ```sh
136 alchemy state bootstrap
137 alchemy state bootstrap --backend cloudflare
138 alchemy state bootstrap --backend cloudflare --profile staging --force
139 alchemy state bootstrap --backend aws --name team-a
140 alchemy state bootstrap --backend cloudflare --name team-a
141 ```
142
143 ## `state teardown`
144
145 ```sh
146 alchemy state teardown --backend <name> [options]
147 ```
148
149 Delete a provider's state store and its backing resources: the
150 Cloudflare Worker, its secrets and cached credentials; or the S3 bucket
151 with every object version. Asks for confirmation unless `--yes`.
152
153 :::danger
154 This deletes the state itself. Stacks whose state lived in the store
155 lose their record of what they deployed; the cloud resources remain.
156 :::
157
158 ## `state logs`
159
160 ```sh
161 alchemy state logs --backend <name> [options]
162 ```
163
164 Fetch or stream the state store's own logs, to debug the store itself.
165 Only `cloudflare` keeps logs (from the state-store Worker, through the
166 Workers Observability API), which needs the `workers_observability:read`
167 and `workers_observability_telemetry:write` OAuth scopes (re-run
168 `alchemy profile edit --reconfigure Cloudflare` on older profiles).
169
170 | Option | Description |
171 | ---------------- | ------------------------------------------------------------------------ |
172 | `--tail`, `-t` | Stream logs as they happen instead of fetching past entries |
173 | `--limit <n>` | Number of entries to fetch (default: 100). Ignored with `--tail` |
174 | `--since <time>` | Fetch logs since a duration (`1h`, `30m`, `2d`) or ISO date |
175
176 ```sh
177 alchemy state logs --backend cloudflare --since 30m --limit 200
178 alchemy state logs --backend cloudflare --tail
179 ```
180
181 ## Where next
182
183 - [Inspecting State](/cli/inspecting-state) — debugging and recovery workflows
184 - [Adopting Resources](/cli/adopting-resources) — how deploy reclaims existing infrastructure
185 - [State Store](/state-store) — where resource state lives