<!-- Markdown mirror. Canonical: https://empryo.com/docs/reference/cli -->

# CLI reference

> Every empryo command-line flag, subcommand, exit code, and environment variable, for the terminal app and for headless runs in scripts and CI.

The `empryo` command starts Empryo. Run it with no arguments inside a project to open the interactive [terminal app](/docs/surfaces/tui). Add `--headless` and a prompt to run a task [without the UI](/docs/surfaces/headless), for example in a script or a CI job. The short alias `em` works everywhere `empryo` does.

```bash Synopsis
empryo [prompt] [flags]
empryo <subcommand> [args]      # addon, presets, doctor, lsp
```

Any argument that does not start with `--` becomes part of the prompt.

## Common flags

| Flag | Value | What it does |
|------|-------|--------------|
| `--headless` | | Run without the UI and print the result to stdout. See [headless](/docs/surfaces/headless). |
| `--model` | `provider/model` | Use this model for this run only. |
| `--mode` | `<mode>` | Start in a mode: `default`, `architect`, `socratic`, `challenge`, `plan`, `auto`, `duck`, `orchestrate`. |
| `--agent` | `<name>` | Run as one of your [custom agents](/docs/tools/agents). |
| `--effort` | `<level>` | Reasoning effort, such as `low`, `medium`, or `high`. Levels the model does not support are rejected. |
| `--session` | `<id>` | Resume a saved session. A short prefix of the id is enough. Aliases: `--resume`, `-s`. |
| `--save-session` | | Save the session when a headless run finishes, so you can resume it. |
| `--session-id` | `<id>` | Start a new session with this id, so a terminal host knows the id before any hook fires. Letters, digits, `-` and `_`; a UUID works. Fails if the id is taken. |
| `--fork` | `<id>` | Start a new session that copies a saved one. The original is left untouched. Combine with `--session-id` to choose the new id. |
| `--cwd` | `<dir>` | Run as if you had started Empryo in this folder. |
| `--trust` | | Trust the current repository before its config loads. This is the command-line version of `/trust`. Without it, a repository you have not trusted cannot start MCP servers, add providers, load presets, or add request fields from its own config. |
| `--locale` | `<tag>` | Interface language for this run, such as `ja`, `zh-Hans`, or `ar`. |
| `--version`, `-v` | | Print the version and exit. |
| `--help`, `-h` | | Print usage and exit. |

## Prompt and context

| Flag | Value | What it does |
|------|-------|--------------|
| `--system` | `"…"` | Add your own instructions to the system prompt. |
| `--include` | `<file>` | Add a file to the context before the run. Repeat for more files. Images are attached as images. |
| `--image` | `<file>` | Attach an image. Repeatable. |
| `--skill` | `<name>` | Load a [skill](/docs/tools/skills). Installs it first if needed. Repeatable. |
| `--voice` | | Record the prompt from your microphone. Needs a terminal. The transcript is added to any typed or piped prompt. See [voice input](/docs/surfaces/voice-input). |
| `--no-genome` | | Skip the Genome scan for this run. The Genome is Empryo's index of your code. Skipping it makes quick questions start faster. |
| `--bare` | | Run without project context. Also skips the Genome scan. |
| `--marionette` | | Experimental. Before the run, map which files matter for the prompt. See [the Marionette](/docs/concepts/marionette). |
| `--marionette-mode` | `<lane>` | How hard that step looks: `none`, `fast`, `assist`, or `deep`. `--marionette-fast` is short for `fast`. |
| `--marionette-model` | `<id>` | Model for that step. `--marionette-max-steps <n>` limits its steps. |

## Limits

| Flag | Value | What it does |
|------|-------|--------------|
| `--max-steps` | `<n>` | Stop after this many agent steps. |
| `--timeout` | `<ms>` | Stop after this many milliseconds. Exits with code `2`. |

## Headless output

These apply with `--headless`.

| Flag | What it does |
|------|--------------|
| `--json` | Print one JSON object with the result when the run ends. |
| `--events` | Print one JSON event per line while the run happens. See [the event types](/docs/surfaces/headless#events---events). Every model call is a `model-call` event with `lane` and `effort`. |
| `--diff` | Print the list of changed files at the end. |
| `--quiet`, `-q` | Hide the progress lines at the start and end. |
| `--render` / `--no-render` | Turn Markdown formatting of the output on or off. It is on by default when the output is a terminal. |
| `--chat` | Multi-turn chat over stdin. The session is saved when you exit. |

## Review and goal loops

| Flag | Value | What it does |
|------|-------|--------------|
| `--review` | `[what to check]` | Have a fresh agent review this session's edits, or your uncommitted changes, and exit with the verdict. The description is optional. Exit codes: PASS `0`, FAIL `3`, PARTIAL `4`. |
| `--loop` | `"<goal>"` | Run a [goal loop](/docs/agents/goal-loop): the agent works, a separate reviewer checks, and it repeats until the goal passes. |
| `--max-iterations` | `<n>` | Maximum rounds for `--loop`. Default `5`. |
| `--routines` | | Run this repository's [scheduled routines](/docs/tools/routines) until you press Ctrl+C. |
| `--replay` | `<path>` | Write an HTML timeline of a run's [computer use](/docs/tools/computer-use) to this path. |

## Accounts and keys

These print something and exit without starting a session.

| Flag | Value | What it does |
|------|-------|--------------|
| `--set-key` | `<provider> <key>` | Save an API key. |
| `--list-providers` | | List every provider and whether it has a key. |
| `--list-models` | `[provider]` | List models for one provider, or for every provider with a key. |
| `--login` | `<account>` | Sign in to a subscription or gateway account. Accepts the same account ids as [`/login`](/docs/reference/commands#sign-in-options), such as `claude`, `codex`, or `copilot`. For Copilot on an enterprise GitHub, add the host: `--login copilot octocorp.ghe.com`. See [subscriptions](/docs/providers/subscriptions). |
| `--no-browser` | | With `--login`, print the sign-in link instead of opening a browser. |
| `--proxy-quota` | | Show the plan limits for each [proxy](/docs/providers/proxy) account. |
| `--capabilities` | `[model]` | Show which [provider tools](/docs/context/provider-tools) a model can use (computer use, code execution, text editor, web search), and why a tool is unavailable. Uses your default model if you leave it out. |

`--trust` also works with `--set-key`, `--list-providers`, and `--list-models`. You need it when the provider is a [custom provider](/docs/providers/custom) defined in the project's config.

## Setup

| Flag | Value | What it does |
|------|-------|--------------|
| `--wizard` | | Run the first-time setup wizard. |
| `--presets` | | Open the [presets](/docs/reference/presets) wizard, then exit. |
| `--plugin` | `<spec>` | Load a [preset](/docs/reference/presets) for this launch. Repeatable. |
| `--verbose-presets` | | Print one line per preset as it loads. |

## Provider options

These override [provider options](/docs/context/provider-options) for one run. Each one only affects providers that support it.

| Flag | Value | Applies to |
|------|-------|------------|
| `--thinking` | `<mode>` | Claude extended thinking. `--thinking-budget <n>` sets a fixed token budget. |
| `--speed` | `<mode>` | Providers with speed modes. |
| `--service-tier` | `off`, `auto`, `default`, `flex`, `priority`, `ultrafast` | OpenAI. `ultrafast` is available for GPT-6 Astra with US/global processing. On a ChatGPT subscription the tier is sent as set: `priority` is Codex Fast mode (2.5x plan usage), `ultrafast` is GPT-6 Astra Ultrafast (8x plan usage where your plan has it). A tier ChatGPT refuses is dropped once and the request runs at Standard. |
| `--reasoning-summary` | `off`, `auto`, `detailed` | OpenAI reasoning summaries. |
| `--verbosity` | `<level>` | OpenAI answer length. |
| `--google-thinking-budget` | `<n>`, `dynamic`, `off` | Gemini. `--include-thoughts` adds thought summaries. |
| `--deepseek-thinking` | `<mode>` | DeepSeek. |
| `--openrouter-reasoning-tokens` | `<n>` | OpenRouter reasoning limit. `--hide-reasoning` hides the reasoning output. |
| `--groq-reasoning-format` | `off`, `parsed`, `raw`, `hidden` | Groq. |
| `--sequential-tools` | | Run tool calls one at a time instead of in parallel. |
| `--no-tool-streaming` | | Wait for a tool call's full arguments before running it. |
| `--no-send-reasoning` | | Do not send earlier reasoning back to the model. |
| `--preserve-thinking` | | Keep earlier thinking blocks in the conversation. |
| `--context-compact` | | Let the provider shorten the context on its side. |
| `--context-clear-tools` | | Let the provider drop old tool results. |

## Subcommands

These run on their own and exit when done.

| Subcommand | What it does |
|------------|--------------|
| `empryo addon <list\|install\|remove\|update> [proxy\|neovim]` | Manage the optional [add-ons](/docs/tools/addons): the subscription proxy and the bundled Neovim editor. `addons` also works. |
| `empryo soulstack [status\|check\|install\|update\|remove\|auto on\|off]` | Detect, install, update or remove [SoulStack](/docs/tools/addons#soulstack). Off until you install it. Once installed, it updates daily. |
| `empryo presets` | Open the presets wizard. Same as `--presets`. |
| `empryo doctor` | Check that Empryo's bundled components load on this machine. Useful after an install or upgrade. |
| `empryo phone` | Continue the chat your phone is running, in this terminal, in its folder. With several phone chats running it asks which one. The phone keeps following the chat. |
| `empryo phone <on\|off\|status\|list>` | `on` keeps phone access running when no terminal or desktop is open and shows the pairing code. `off` turns that off. `status` and `list` show what your phone is running, with each chat's id for `empryo --resume <id>`, which also works from any folder. |
| `empryo cua [status\|install\|libraries\|update\|start\|allow\|preview] [--json]` | Set up [Cua Driver](/docs/tools/computer-use#cua-driver), the recommended computer-use driver: see its status, install or update it, start it, grant its macOS permissions, or toggle its live preview. Works over SSH. |
| `empryo lsp <status\|start\|install>` | [Language servers](/docs/tools/lsp): see which are installed and running, start them, or install one. Run `empryo lsp --help` for details. |
| `empryo hearth <…>` | Deprecated. [Hearth](/docs/tools/hearth) is turned off, so this prints a notice and starts nothing. |
| `empryo remote <…>` | Deprecated. Approved tool calls for Hearth. Prints a notice and starts nothing. |

## Exit codes

| Code | Meaning |
|------|---------|
| `0` | Success. Also returned by `--help`, `--version`, and a PASS review. |
| `1` | Error. For example: no model is set, the model could not be found, the step limit was reached, the provider failed, or an argument was wrong. |
| `2` | The `--timeout` limit was reached. |
| `3` | `--review` verdict: FAIL. |
| `4` | `--review` verdict: PARTIAL. |
| `5` | A computer-use action needs a person to take over, and the run cannot ask one. |
| `130` | Stopped with Ctrl+C. |

```bash CI gate
empryo --headless "run the test suite and fix any failures" --json --timeout 600000
echo "exit: $?"   # 0 success, 1 error, 2 timeout, 130 stopped
```

## Managing keys

Empryo stores keys in your system keychain when one is available, and in a protected file otherwise. See [key storage](/docs/reference/configuration#auth-key-storage) for details per platform.

```bash
empryo --set-key anthropic sk-ant-...     # save a key
empryo --list-providers                   # which providers have a key
empryo --list-models anthropic            # models for one provider
```

To use a key for one session without saving it, set the provider's environment variable:

```bash
ANTHROPIC_API_KEY=sk-ant-... empryo
```

## Piped input

With `--headless` and no prompt, Empryo reads the prompt from stdin. With a prompt, piped text is added to it:

```bash
echo "summarize the architecture" | empryo --headless
git diff | empryo --headless "review this diff for bugs"
```

## Environment variables

The most useful ones. The full list is in [configuration](/docs/reference/configuration#environment-variables).

| Variable | What it does |
|----------|--------------|
| `EMPRYO_NO_GENOME=1` | Skip the Genome scan, like `--no-genome`. |
| `EMPRYO_MAX_OUTPUT_TOKENS` | Output-token cap for models whose limit is not declared by the provider or models.dev. Default `64000`. A declared limit always wins. |
| `EMPRYO_PRESETS` | Presets to load at startup, separated by commas. `--plugin` sets this for you. |
| `EMPRYO_NO_PROMPT=1` | Skip the first-run add-on prompt. Useful in CI. |
| `EMPRYO_VOICE_LIVE_URL` | WebSocket address for [live dictation](/docs/surfaces/voice-input). Defaults to OpenAI's Realtime transcription endpoint. Point it at a compatible gateway or a test server. |

> **Tip:**
> Older names still work. `--no-repomap` and `EMPRYO_NO_REPOMAP` mean the same as `--no-genome`, and every `EMPRYO_` variable also accepts the old `SOULFORGE_` prefix.

## Next

**Terminal UI**

Keyboard shortcuts, slash commands, tabs, and panels in the terminal app.

**Headless & output**

JSON and event output, chat mode, and scripting patterns.