CLI reference
Every empryo command-line flag, subcommand, exit code, and environment variable — the interface that launches the TUI, desktop app, and headless runs.
Copy & share
Loading sections…
Connect MCP or install the Empryo skillSection exports contain only that heading’s content. Markdown and text links fetch the selected content directly, without the rest of the page.
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. | ||
--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 can be named at all. | ||
--model | provider/model | Override the model for this run. | ||
--mode | <mode> | Set the mode: default, architect, socratic, challenge, plan, auto. | ||
--agent | <name> | Run the session under a custom agent definition. | ||
--effort | <level> | Reasoning effort for the run, validated against the model family's ladder. | ||
--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. | ||
--skill | <name> | Load a skill into context. Repeatable; installs when missing. | ||
--max-steps | <n> | Cap the number of agent steps. | ||
--loop | "<goal>" | Closed loop: coder⟷reviewer iterations until the goal passes (exit code = verdict). | ||
--max-iterations | <n> | 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 | <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. | ||
--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 <key>, ollama-cloud <key>, copilot, llmgateway; see Subscriptions. --login copilot octocorp.ghe.com signs in to a Copilot seat on an enterprise GitHub. | |
--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, and let AI SDK warnings through to stderr. |
Every Empryo variable accepts the legacy SOULFORGE_ prefix as a fallback, so older scripts keep working.