The best way to control Claude Code, Codex and more from any computer or phone
| 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 |