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

main
mdx 127 lines 8.39 KB
Raw
1 ---
2 title: CLI
3 description: Every alchemy command at a glance — the command map, common options, and how the interactive TUI decides when to render.
4 ---
5
6 ```sh
7 bun alchemy <command> [options]
8 ```
9
10 Every command operates on an `alchemy.run.ts` stack file (or a custom entrypoint passed with `--config <file>`, which must exist) and targets a [stage](/environments/stages).
11
12 ## Command map
13
14 ```sh
15 alchemy
16 ├─ deploy # plan → approve → apply
17 ├─ plan # preview changes, apply nothing
18 ├─ destroy # delete every resource in a stage
19 ├─ drift # detect (and optionally repair) infrastructure drift
20 ├─ unsafe nuke # delete everything a provider can list, tracked or not
21 │
22 ├─ dev # hot-reloading development loop
23 ├─ logs # fetch past log entries, or tail live with --tail
24 │
25 ├─ profile create|rename|edit|refresh|current|list|show|delete
26 │ # manage credentials and accounts (bare `profile` opens the dashboard)
27 │
28 ├─ state list|read|delete # inspect and manage the state store (bare `state` opens the explorer)
29 ├─ state bootstrap|teardown|logs # provision, delete, or debug a provider's state store (--backend)
30 │
31 └─ provider
32 ├─ check-env # CI preflight: verify required provider env vars are set
33 ├─ aws bootstrap|teardown # the deploy assets bucket
34 ├─ cloudflare token
35 └─ prisma generate
36 ```
37
38 Each command has its own page: [deploy](/cli/deploy), [plan](/cli/plan), [destroy](/cli/destroy), [drift](/cli/drift), [unsafe nuke](/cli/nuke), [dev](/cli/dev), [logs](/cli/logs), [profile](/cli/profile), [state](/cli/state), [AWS provider commands](/cli/aws), and [Cloudflare provider commands](/cli/cloudflare). The workflow guides cover [adopting resources](/cli/adopting-resources) and [inspecting state](/cli/inspecting-state). To run the same operations from a script, see the [Programmatic API](/cli/api).
39
40 ## Common options
41
42 | Option | Description |
43 | ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
44 | `--stage <name>` | Stage to target. Falls back to `$ALCHEMY_STAGE`, then `live_$USER` (`dev_$USER` for `alchemy dev`). Must match `[a-z0-9]+([-_a-z0-9]+)*`. |
45 | `--profile <name>` | Auth profile from `~/.alchemy/profiles.json`. Overrides `$ALCHEMY_PROFILE`; defaults to `default`. |
46 | `--env-file <path>` | File to load environment variables from. Defaults to `.env`. |
47 | `--yes` | Yes to all prompts. |
48 | `--no-input` | Disable prompts and the interactive TUI. Commands that would need input fail instead of hanging. |
49 | `--config, -c <file>` | Stack entrypoint. Defaults to `alchemy.run.ts`; must exist. |
50 | `--fast-distilled` | Under Node, load each distilled SDK operation on first use. This lowers the CLI's memory and startup time for stacks that import whole providers. Same as `ALCHEMY_FAST_DISTILLED=1`. |
51
52 Use `--profile` with `deploy`, `plan`, `destroy`, `dev`, `logs`, `drift`, or `state`.
53
54 ## The interactive TUI
55
56 In an interactive terminal, `deploy`, `destroy`, and `plan` render a live TUI: the rendered plan, an arrow-key approval prompt, and per-resource apply progress that unmounts into the final output. Everywhere else the same commands emit plain line-oriented logs.
57
58 The `--no-input` flag and environment variables override the detection, in this order:
59
60 | Signal | Effect |
61 | ------------------------------------------------------------------------------------------------- | ----------------- |
62 | `--no-input` flag | Force plain output |
63 | `ALCHEMY_PLAIN=1` or `ALCHEMY_NO_TUI=1` | Force plain output |
64 | `ALCHEMY_TUI=1` | Force the TUI |
65 | No TTY, `CI=1`, or a known agent env var (`CLAUDECODE`, `CLAUDE_CODE_ENTRYPOINT`, `CURSOR_AGENT`, `AIDER_MODEL`, `CODEX_CLI`) | Force plain output |
66
67 Interactive terminals use the animated TUI; redirected and non-interactive runs use append-only output.
68
69 Plain mode never prompts — it prints the plan, makes no changes, and fails with `error: Cannot approve this operation without terminal input. Pass --yes to continue.` In CI, always pass `--yes`.
70
71 ## Log output
72
73 Every log line is a record. Output from child processes (dev servers, workerd, the local provider sidecar) is captured as records too, so it can be shown either way:
74
75 | Option | Description |
76 | --- | --- |
77 | `--log-format pretty\|json` | `pretty` (default) prints lines; `json` prints one record per line on stderr, with child output as written. Also `$ALCHEMY_LOG_FORMAT`. |
78 | `--log-level <level>` | Lowest level printed. Defaults to `info`. Also `$ALCHEMY_LOG_LEVEL`. |
79
80 Every record has the same keys:
81
82 | Key | Value |
83 | --- | --- |
84 | `time` | Unix time in milliseconds |
85 | `level` | `trace`, `debug`, `info`, `warn`, `error` or `fatal` |
86 | `kind` | `log`, `event`, `output` or `run` (see below) |
87 | `process` | The alchemy process that produced it: `cli`, `exec` (the `alchemy dev` worker) or `sidecar` |
88 | `scope` | `project` or `global` |
89 | `trace` | `{ traceId, spanId }` of the span it was logged in, or of the process outside any span. Child processes and sidecar calls join their caller's trace. |
90 | `attributes` | Annotations on the record, including `fqn` when it is about a resource |
91 | `data` | Depends on `kind` |
92
93 | `kind` | `data` |
94 | --- | --- |
95 | `log` | `{ message, cause }`: a line alchemy logged |
96 | `event` | A typed event, as `Alchemist.onEvent` receives it |
97 | `output` | `{ stream, text }`: a line a child process wrote, exactly as written, ANSI styling included |
98 | `run` | `{ version, pid, cwd, argv }`: the first line of a run log |
99
100 ```json
101 {"time":1793186948542,"level":"info","kind":"output","process":"sidecar","scope":"project","trace":{"traceId":"4bf92f3577b34da6a3ce929d0e0e4736","spanId":"00f067aa0ba902b7"},"attributes":{"fqn":"Web"},"data":{"stream":"stdout","text":"\u001b[32mready\u001b[39m on http://localhost:4321"}}
102 ```
103
104 Each run also writes its records at debug level to a run log, one record per line. Project work goes to the project's `.alchemy/log/<time>-pid<pid>.ndjson`; account-level work (the state store, auth and credentials, `profile` and `provider` commands) goes to `~/.alchemy/logs/<time>-pid<pid>.ndjson`. A file is created only when a record goes to it. Child processes send their records through the CLI, so `jq` filters such as `select(.kind == "output" and .attributes.fqn == "Api")` find any of them.
105
106 Logs never leave your machine. Telemetry sends only usage spans and metrics; when reporting a problem, attach the run log.
107
108 ## Exit codes
109
110 Exit codes are script-safe: `0` only means the command actually completed.
111
112 | Code | Meaning |
113 | ----- | --------------------------------------------------------------------------------------------------- |
114 | `0` | Command completed |
115 | `1` | Failure, including a declined plan or bare `profile`/`state` without a terminal |
116 | `130` | Cancelled by the user (Ctrl-C, or Escape inside a prompt) |
117
118 Running these commands in a pipeline? See [CI](/environments/ci).
119
120 ## Where next
121
122 - [deploy](/cli/deploy) — plan, approve, and apply changes
123 - [dev](/cli/dev) — hot-reloading development loop
124 - [profile](/cli/profile) manages credentials and connected accounts
125 - [state](/cli/state) — inspect and manage the state store
126 - [Stages](/environments/stages) — how environments are isolated
127 - [CI](/environments/ci) — run the CLI in pipelines