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. Run it with no arguments inside a repository to open the interactive TUI; pass a prompt with --headless to run non-interactively. This page is the reference for its command line. It also installs a short alias, em.
empryo [prompt] [flags]
empryo <subcommand> [args] # hearth · remote · addon · presetsFlags
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. | |
--session | --resume, -s | <id> | Resume a saved session by id (or short id prefix). |
--save-session | — | Save the session after a headless run completes. | |
--model | provider/model | Override the model for this run. | |
--mode | <mode> | Set the mode: default, architect, socratic, challenge, plan, auto. | |
--system | "…" | Append to the system prompt. | |
--include | <file> | Pre-load a file into context. Repeatable; image files attach as vision parts. | |
--image | <file> | Attach an image as a multimodal part. Repeatable. | |
--max-steps | <n> | Cap the number of agent steps. | |
--timeout | <ms> | Abort the run after this many milliseconds (exit code 2). | |
--cwd | <dir> | 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. | |
--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 | <provider> <key> | Store an API key (keychain or file), then exit. | |
--plugin | <spec> | Load a preset 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. |
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 <list\ | install\ | remove\ | update> [proxy\ | neovim]` | Manage the two optional add-ons: the CLIProxyAPI relay and the bundled Neovim. addons works too. |
empryo presets | Open the presets wizard (also --presets). | ||||
empryo hearth <…> | Manage Hearth, the remote-control daemon. | ||||
empryo remote <…> | The companion approval CLI used by Hearth to grant remote tool calls. |
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. |
empryo --headless "run the test suite and fix any failures" --json --timeout 600000
echo "exit: $?" # 0 pass · 1 error · 2 timeout · 130 abortedManaging keys
Keys are stored in your OS keychain when available, with a file fallback. See key storage for the per-platform backends.
empryo --set-key anthropic sk-ant-... # store a key
empryo --list-providers # which providers have a key
empryo --list-models anthropic # models for one providerYou can also pass a provider's environment variable inline for a one-off session — nothing is persisted:
ANTHROPIC_API_KEY=sk-ant-... empryoPiped input
With --headless and no prompt argument, empryo reads the prompt from stdin:
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.
| 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. |
Every Empryo variable accepts the legacy SOULFORGE_ prefix as a fallback, so older scripts keep working.