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.
Copy & share
On this page14 sections
The empryo command starts Empryo. Run it with no arguments inside a project to open the interactive terminal app. Add --headless and a prompt to run a task without the UI, for example in a script or a CI job. The short alias em works everywhere empryo does.
empryo [prompt] [flags]
empryo <subcommand> [args] # addon, presets, doctor, lspAny argument that does not start with -- becomes part of the prompt.
Common flagsLink to this section
| Flag | Value | What it does |
|---|---|---|
--headless | Run without the UI and print the result to stdout. See 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. |
--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 contextLink to this section
| 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. 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. | |
--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. | |
--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. |
LimitsLink to this section
| 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 outputLink to this section
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. 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 loopsLink to this section
| 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: 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 until you press Ctrl+C. | |
--replay | <path> | Write an HTML timeline of a run's computer use to this path. |
Accounts and keysLink to this section
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`, such as claude, codex, or copilot. For Copilot on an enterprise GitHub, add the host: --login copilot octocorp.ghe.com. See subscriptions. |
--no-browser | With --login, print the sign-in link instead of opening a browser. | |
--proxy-quota | Show the plan limits for each proxy account. | |
--capabilities | [model] | Show which 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 defined in the project's config.
SetupLink to this section
| Flag | Value | What it does |
|---|---|---|
--wizard | Run the first-time setup wizard. | |
--presets | Open the presets wizard, then exit. | |
--plugin | <spec> | Load a preset for this launch. Repeatable. |
--verbose-presets | Print one line per preset as it loads. |
Provider optionsLink to this section
These override 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. |
SubcommandsLink to this section
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: 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. 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, 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: see which are installed and running, start them, or install one. Run empryo lsp --help for details. | ||||
empryo hearth <…> | Deprecated. 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 codesLink to this section
| 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. |
empryo --headless "run the test suite and fix any failures" --json --timeout 600000
echo "exit: $?" # 0 success, 1 error, 2 timeout, 130 stoppedManaging keysLink to this section
Empryo stores keys in your system keychain when one is available, and in a protected file otherwise. See key storage for details per platform.
empryo --set-key anthropic sk-ant-... # save a key
empryo --list-providers # which providers have a key
empryo --list-models anthropic # models for one providerTo use a key for one session without saving it, set the provider's environment variable:
ANTHROPIC_API_KEY=sk-ant-... empryoPiped inputLink to this section
With --headless and no prompt, Empryo reads the prompt from stdin. With a prompt, piped text is added to it:
echo "summarize the architecture" | empryo --headless
git diff | empryo --headless "review this diff for bugs"Environment variablesLink to this section
The most useful ones. The full list is in configuration.
| 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. Defaults to OpenAI's Realtime transcription endpoint. Point it at a compatible gateway or a test server. |