@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 133 lines 3.66 KB
Raw
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