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
| 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 |