# CLI reference > Every empryo command-line flag, subcommand, exit code, and environment variable. The interface that launches the TUI, desktop app, and headless runs. `empryo` is a single binary that launches all three [surfaces](/docs/surfaces/overview). Run it with no arguments inside a repository to open the interactive [TUI](/docs/surfaces/tui), pass a prompt with `--headless` to run [non-interactively](/docs/surfaces/headless). This page is the reference for its command line. It also installs a short alias, `em`. ```bash Synopsis empryo [prompt] [flags] empryo [args] # hearth · remote · addon · presets ``` ## Flags Flags are parsed before the UI boots. Anything not starting with `--` is collected into the prompt. | Flag | Alias | Value | What it does | |------|-------|-------|--------------| | `--headless` | |, | Run without the TUI, streaming to stdout. See [headless](/docs/surfaces/headless). | | `--session` | `--resume`, `-s` | `` | Resume a saved session by id (or short id prefix). | | `--save-session` | |, | Save the session after a headless run completes. | | `--trust` | |, | Grant durable repo trust for the working directory before config loads, the CI twin of `/trust`. Without it an untrusted checkout runs with `mcpServers`, `providers`, `extraBody` and presets withheld. Also accepted alongside `--set-key`, `--list-providers` and `--list-models`, so a project-scoped [custom provider](/docs/providers/custom) can be named at all. | | `--model` | | `provider/model` | Override the model for this run. | | `--mode` | | `` | Set the mode: `default`, `architect`, `socratic`, `challenge`, `plan`, `auto`. | | `--agent` | | `` | Run the session under a custom [agent definition](/docs/tools/agents). | | `--effort` | | `` | Reasoning effort for the run, validated against the model family's ladder. | | `--locale` | | `` | UI language for this run (`ar`, `ja`, `zh-Hans`). Beats config and `EMPRYO_LOCALE`; headless reads cached catalogs only. | | `--voice` | | `[prompt]` | Record a spoken prompt (mic → speech-to-text, needs a TTY). The transcript joins any typed or piped prompt. See [voice input](/docs/surfaces/voice-input). | | `--routines` | |, | Run this repo's [scheduled routines](/docs/tools/routines) until Ctrl+C, the daemon that fires detached headless runs. | | `--marionette` | |, | Compile the prompt into a repo map before the run ([the Marionette](/docs/concepts/marionette)). | | `--marionette-mode` | | `` | Locator lane: `none`, `fast`, `assist`, `deep`. `--marionette-fast` is the alias for `fast`. | | `--marionette-model` | | `` | Model for the pre-pass. `--marionette-max-steps ` caps its steps. | | `--system` | | `"…"` | Append to the system prompt. | | `--include` | | `` | Pre-load a file into context. Repeatable; image files attach as vision parts. | | `--image` | | `` | Attach an image as a multimodal part. Repeatable. | | `--skill` | | `` | Load a [skill](/docs/tools/skills) into context. Repeatable; installs when missing. | | `--max-steps` | | `` | Cap the number of agent steps. | | `--loop` | | `""` | [Goal loop](/docs/agents/goal-loop): coder⟷reviewer rounds until a fresh judge passes the goal (exit code = verdict). | | `--max-iterations` | | `` | Cap goal-loop iterations (default 5). | | `--review` | | `[what to check]` | Judge this session's edits (or the uncommitted tree) with a fresh agent. Exit codes: PASS `0`, FAIL `3`, PARTIAL `4`. The brief is optional. | | `--timeout` | | `` | Abort the run after this many milliseconds (exit code `2`). | | `--cwd` | | `` | Set the working directory before launch. | | `--json` | |, | Headless: print one JSON result object. | | `--events` | |, | Headless: stream JSONL events in real time. | | `--diff` | |, | Headless: print the list of files changed after the run. | | `--quiet` | `-q` |, | Suppress the header/footer progress lines. | | `--render` / `--no-render` | |, | Force or disable Markdown/ANSI rendering of output. Defaults to on when stdout is a TTY. | | `--chat` | |, | Headless multi-turn chat over stdin. Auto-saves the session on exit. | | `--no-genome` | |, | Skip the Genome scan for this run. | | `--no-browser` | |, | With `--login`, print the URL instead of opening a browser. | | `--proxy-quota` | |, | Print [proxy subscription](/docs/providers/proxy) quota per account, then exit. | | `--list-providers` | |, | Print every provider and whether a key is configured, then exit. | | `--list-models` | | `[provider]` | Print available models for one provider, or all configured providers. | | `--set-key` | | ` ` | Store an API key (keychain or file), then exit. | | `--capabilities` | | `[model]` | Print every [provider tool](/docs/context/provider-tools) for a model, computer use, code execution, text editor, provider-side search, with the backend it resolves to or the reason it has none. Defaults to your configured model. | | `--login` | | `[account] [host\|key]` | Sign in to a subscription or gateway account, then exit, `claude`, `codex`, `codex-device`, `grok`, `cursor`, `devin`, `google-gemini-cli`, `google-antigravity`, `kimi-code`, `firepass `, `ollama-cloud `, `copilot`, `llmgateway`; see [Subscriptions](/docs/providers/subscriptions). `--login copilot octocorp.ghe.com` signs in to a [Copilot](/docs/providers/copilot) seat on an enterprise GitHub. | | `--replay` | | `` | Write a printable HTML timeline of a run's [computer use](/docs/tools/computer-use), statuses, elapsed time, redacted actions, costs, screenshots. | | `--plugin` | | `` | Load a [preset](/docs/reference/presets) for this launch. Repeatable. | | `--wizard` | |, | Force the first-run setup wizard. | | `--presets` | |, | Open the interactive presets wizard, then exit. | | `--version` | `-v` |, | Print the version and exit. | | `--help` | `-h` |, | Print usage and exit. | ## Provider tuning Per-run overrides for the knobs [provider options](/docs/context/provider-options) usually holds in config. Each applies only to models whose provider supports it, the rest are ignored. | Flag | Value | Provider | |------|-------|----------| | `--thinking` | `` | Anthropic extended thinking. `--thinking-budget ` pins a fixed budget. | | `--speed` | `` | Provider speed modes. | | `--service-tier` | `off\|auto\|default\|flex\|priority` | OpenAI. | | `--reasoning-summary` | `off\|auto\|detailed` | OpenAI reasoning summaries. | | `--verbosity` | `` | OpenAI answer length. | | `--google-thinking-budget` | `` | Gemini budget (`dynamic`, `off`, or a number). `--include-thoughts` adds thought summaries. | | `--deepseek-thinking` | `` | DeepSeek switchable thinking. | | `--openrouter-reasoning-tokens` | `` | OpenRouter reasoning cap. `--hide-reasoning` suppresses the output. | | `--groq-reasoning-format` | `off\|parsed\|raw\|hidden` | Groq. | | `--sequential-tools` |, | Disable parallel tool calls. | | `--no-tool-streaming` |, | Wait for complete tool-call arguments before executing. | | `--no-send-reasoning` |, | Do not replay prior reasoning content. | | `--preserve-thinking` |, | Keep thinking blocks for prompt-cache stability. | | `--context-compact` |, | Enable provider-side context compaction. | | `--context-clear-tools` |, | Let the provider clear old tool results. | > **Note:** > The legacy `--no-repomap` flag and `EMPRYO_NO_REPOMAP` variable still map to the Genome scan, but the current name is `--no-genome` (and `EMPRYO_NO_GENOME`). Prefer the new name. ## Subcommands These run before the agent boots and exit when done. | Subcommand | What it does | |------------|--------------| | `empryo addon [proxy\|neovim]` | Manage the two optional [add-ons](/docs/tools/addons): the CLIProxyAPI relay and the bundled Neovim. `addons` works too. | | `empryo presets` | Open the presets wizard (also `--presets`). | | `empryo hearth <…>` | Manage [Hearth](/docs/tools/hearth), the remote-control daemon. | | `empryo remote <…>` | The companion approval CLI used by Hearth to grant remote tool calls. | | `empryo doctor` | Runtime self-check: native FFI, tree-sitter, the highlight pipeline, the genome and io workers, optional add-ons. What the release smoke tests run, `--version` returns before any native import, so it cannot catch a missing native lib. | | `empryo lsp ` | [Language servers](/docs/tools/lsp): what is installed and running, start them now, or install one from the registry. `empryo lsp --help` for the rest. | ## Exit codes | Code | Meaning | |------|---------| | `0` | Success (also `--help` / `--version`). | | `1` | Error, model resolution failed, no model set, max steps hit, a stream error, or bad arguments. | | `2` | Timeout, the `--timeout` deadline fired. | | `130` | Aborted (Ctrl+C / SIGINT). The signal is re-raised so the parent shell sees a real interrupt. | ```bash CI gate empryo --headless "run the test suite and fix any failures" --json --timeout 600000 echo "exit: $?" # 0 pass · 1 error · 2 timeout · 130 aborted ``` ## Managing keys Keys are stored in your OS keychain when available, with a file fallback. See [key storage](/docs/reference/configuration#auth-key-storage) for the per-platform backends. ```bash empryo --set-key anthropic sk-ant-... # store a key empryo --list-providers # which providers have a key empryo --list-models anthropic # models for one provider ``` You can also pass a provider's environment variable inline for a one-off session, nothing is persisted: ```bash ANTHROPIC_API_KEY=sk-ant-... empryo ``` ## Piped input With `--headless` and no prompt argument, `empryo` reads the prompt from stdin: ```bash echo "summarize the architecture" | empryo --headless git diff | empryo --headless "review this diff for bugs" ``` ## Environment variables The most useful runtime variables. The full list (build flags, Hearth, addons) is in [configuration](/docs/reference/configuration#environment-variables). | Variable | Purpose | |----------|---------| | `EMPRYO_NO_GENOME=1` | Skip the Genome scan, like `--no-genome`. | | `EMPRYO_MAX_OUTPUT_TOKENS` | Per-step output cap for all agents (default `64000`). | | `EMPRYO_PRESETS` | Comma/space-separated preset specs to load on boot (set by `--plugin`). | | `EMPRYO_NO_PROMPT=1` | Skip the first-run add-on wizard (useful in CI). | | `EMPRYO_DEBUG_API` | Dump per-step API requests for debugging, and let AI SDK warnings through to stderr. | > **Tip:** > Every Empryo variable accepts the legacy `SOULFORGE_` prefix as a fallback, so older scripts keep working. ## Next #### Terminal UI Keybindings, slash commands, tabs, and panels in the interactive TUI. #### Headless & output JSON and JSONL output shapes, chat mode, and pipeline patterns.