CLI reference

This page lists every command and option of the o4 command. Run o4 with no command to start an interactive session in the current directory. The subcommands manage sessions, MCP servers, plugins, workspace trust, the daemon, watch mode and evaluations without starting a session. Every command also accepts -h or --help. o4 help <command> prints the same help as o4 <command> --help.

o4 [OPTIONS] [COMMAND]

Command	What it does
`o4 resume`	Resume a saved session
`o4 sessions`	List and delete sessions
`o4 mcp`	Manage MCP servers
`o4 plugin`	Manage plugins and marketplaces
`o4 watch`	Watch the workspace and run its configured check
`o4 trust`	Trust the current workspace
`o4 untrust`	Revoke trust for the current workspace
`o4 update`	Update o4 to the latest release
`o4 daemon`	Manage the o4 daemon
`o4 eval`	Run and report coding-agent evaluations

Global options

These options go before the command, for example o4 -m anthropic:claude-sonnet-4-6 or o4 -C ~/code/api watch. Most of them affect how a session starts, so they matter for plain o4, for o4 resume, and for print mode.

Option	Description
`-m`, `--model <model>`	Model to use.
`-p`, `--prompt <prompt>`	Initial prompt. Runs print mode.
`-s`, `--system-prompt <system-prompt>`	Extra system prompt text.
`--prompt-profile <PROFILE>`	Override automatic prompt profile selection for this session. One of `modern-minimal`, `modern-guided`, `legacy-guided`, `local-defensive`.
`--reasoning <LEVEL>`	Reasoning effort: `default`, `low`, `medium`, `high`, or `max`.
`--print`	Print mode. Accepted for compatibility; `-p` is what starts print mode.
`--print-system-prompt`	Print the assembled system prompt and exit.
`-v`, `--verbose`	Stream the model’s reasoning output as it arrives.
`--list-models`	List registered models and exit.
`--accessibility`	Force screen reader accessible output.
`--no-onboarding`	Skip the first-run setup wizard.
`--permission-mode <MODE>`	Tool permission mode: `ask`, `accept-edits`, `plan`, `review`, `auto`, or `bypass`.
`--sandbox <SANDBOX_MODE>`	Sandbox policy for shell commands the model runs: `read-only`, `workspace-write`, or `danger-full-access`.
`--dangerously-bypass-hook-trust`	Run enabled hooks without persisted hook trust, for this run only.
`-C`, `--cd <DIR>`	Use this directory as the working root.
`--add-dir <DIR>`	Another directory the agent may write to, alongside the working root. Repeat for more.
`-h`, `--help`	Print help.
`-V`, `--version`	Print the version, for example `o4 0.2.74`.

Model and prompt

string

The model to start with. Accepts provider:model (anthropic:claude-sonnet-4-6), provider/model (anthropic/claude-sonnet-4-6), or a bare model ID or name (claude-sonnet-4-6). A model given here must exist: if o4 can’t find it, it exits with a not found error that suggests o4 --list-models. Without -m, o4 uses your saved model. See Choosing a model.

o4 -m anthropic:claude-sonnet-4-6

string

Runs the prompt once without the interface, prints the reply, and exits. See Print mode and scripting for permissions, exit codes and output.

o4 -p "Summarize what this repository does in three sentences"

Two prompts print a JSON report instead of calling the model: o4 -p "/context --json" and o4 -p "/stats --json". See Context and cost.

string

Text added to o4’s system prompt for this session. It doesn’t replace the built-in prompt.

o4 -s "Answer in British English."

string

o4 picks a prompt profile for each model automatically. This option forces one for the session: modern-minimal, modern-guided, legacy-guided or local-defensive. See Reasoning and prompt profiles.

o4 --prompt-profile local-defensive -m ollama:gemma4

string

The reasoning effort to start with. The help lists default, low, medium, high and max. o4 also accepts minimal, extra-high (or xhigh) and ultra where the model supports them. default leaves the choice to the provider. Without this option, o4 uses the reasoning value from your settings. An unknown value stops o4 with Unknown reasoning level. See Reasoning and prompt profiles.

o4 --reasoning high

boolean

Kept for compatibility. A prompt given with -p is what starts print mode, so o4 --print -p "..." behaves like o4 -p "...", and o4 --print alone starts the normal interface.

boolean

Prints the full system prompt o4 would send, followed by a --- Prompt diagnostics --- block with the prompt profile, how it was selected, a hash, and the size in bytes and estimated tokens. Then it exits. It doesn’t call the model. Combine it with -m, --prompt-profile or -s to see their effect.

o4 --print-system-prompt -m anthropic:claude-sonnet-4-6

boolean

Streams the model’s reasoning output as it arrives. It works in print mode, where the reasoning goes to stderr so stdout keeps only the reply. The full-screen interface ignores it.

o4 -v -p "Why does this test fail?"

boolean

Lists every registered model, grouped by provider, with its context window, maximum output tokens, input types and whether it supports reasoning. Then it exits. It doesn’t need an API key.

o4 --list-models

Provider: anthropic
  claude-sonnet-4-6 (context: 1000k, max_tokens: 64000, input: text,image, reasoning: yes)

Interface and setup

boolean

Turns on screen reader output for this session, the same as the screen reader setting. See Themes and display.

boolean

Skips the first-run setup wizard. If no model is configured and you don’t pass -m, o4 exits with No default model configured and tells you to run without --no-onboarding or to pass -m.

o4 --no-onboarding -m anthropic:claude-sonnet-4-6

Permissions and sandbox

string

Sets how tool calls are approved for this run: ask, accept-edits, plan, review, auto or bypass. See Permissions. Print mode starts in auto when you don’t set this.

o4 --permission-mode accept-edits

string

Fixes the sandbox for shell commands from the model for this run:

Value	Effect
`read-only`	Commands can’t write files or reach the network.
`workspace-write`	Commands can write to the working root and any `--add-dir` directories, and reach the same hosts as the `guarded` tier.
`danger-full-access`	No sandbox.

With read-only or workspace-write, o4’s file tools also refuse paths outside those directories. See Sandbox.

o4 --sandbox workspace-write

boolean

Runs enabled hooks even if you haven’t trusted them, for this run only. Use it only in automation that already checks where its hooks come from. See Hooks.

Directories

When you pass -C or --add-dir, o4’s file tools only read and write inside the working root and the added directories. Shell commands are limited to those directories only with --sandbox workspace-write. See Sandbox.

path

Runs o4 as if you started it in this directory. It applies to sessions and to commands such as o4 -C ~/code/api watch. The directory must exist. o4 refuses directories that overlap protected credential locations such as ~/.ssh. --cwd is a hidden spelling of the same option. When o4 restarts itself to resume a session, it passes the directory you chose with --cwd, so it doesn’t ask again.

o4 -C ~/code/api

path

Adds a directory the agent may write to, next to the working root. Repeat it for several directories. A relative path is resolved against the working root. Directories that overlap protected credential locations are refused with overlaps a protected credential location.

o4 --add-dir ../shared-lib --add-dir ~/notes

Removed flags

Older approval flags now stop o4 with a message that names the replacement:

Removed flag	Use instead
`--dangerously-bypass-permissions`	`--permission-mode bypass`
`--allow-dangerously-skip-permissions`	`--permission-mode bypass`
`-a`, `--ask-for-approval`	`--permission-mode ask`
`--approve-for-me`	`--permission-mode review` (add `--sandbox workspace-write` to sandbox commands)
`--dangerously-bypass-approvals-and-sandbox`	`--permission-mode bypass --sandbox danger-full-access`

o4 resume

Resume a saved session.

o4 resume [id]

Argument	Description
`[id]`	Session ID to resume.

Without an ID, o4 resume opens the session picker. When no terminal is attached, it prints the list of sessions from every directory instead. With an ID, it resumes that session directly. If the session started in a different directory, o4 asks which directory to use, unless you chose an “always” answer before or pass -C. See Resuming in a different directory. Global options such as -m still apply. The resumed session runs on the model you pass with -m, or on your default model, not on the model it last used; see Sessions.

o4 resume
o4 resume 3f2b9c1e-8a4d-4c2e-9f1a-7b6d5e4c3a21

o4 sessions

Manage sessions. A subcommand is required.

o4 sessions <COMMAND>

o4 sessions list

List recent sessions from the current checkout, with ID, model, title, directory and last update.

Option	Description
`--all`	Show sessions from every directory, not just this checkout.

o4 sessions list --all

If sessions exist only in other directories, the list says so and suggests o4 sessions list --all.

o4 sessions delete

Delete a session.

o4 sessions delete <id>

Argument	Description
`<id>`	Session ID to delete.

o4 sessions delete 3f2b9c1e-8a4d-4c2e-9f1a-7b6d5e4c3a21

The command prints Deleted session <id> even when no session has that ID. See Sessions for what deleting removes.

o4 mcp

Manage MCP servers. With no subcommand, o4 mcp runs o4 mcp list. See MCP servers.

o4 mcp [COMMAND]

In o4 0.2.74, registry lookups fail: the MCP registry no longer serves the address o4 queries. o4 mcp search exits with Registry search failed with status 404 Not Found, and o4 mcp add <name> reports that the server wasn’t found in the registry. Until this is fixed, add servers with Add server in /mcp or by editing .mcp.json. See MCP servers.

o4 mcp add

Add an MCP server from the MCP registry.

o4 mcp add [OPTIONS] <name>

Argument or option	Description
`<name>`	Server name, as it appears in the registry.
`--global`	Install globally instead of project-local.

Without --global, o4 adds the server to the project’s .o4/.mcp.json, which needs a trusted workspace. In an untrusted workspace the command stops and asks you to run o4 trust or pass --global. With --global, the server goes into ~/.o4/.mcp.json. If the server needs environment variables, o4 lists them after adding it.

o4 mcp add some-server --global

o4 mcp remove

Remove an MCP server.

o4 mcp remove <name>

Argument	Description
`<name>`	Server name.

o4 removes the server from the project config if it’s there, otherwise from the global config.

o4 mcp remove some-server

o4 mcp list

List configured MCP servers with their transport. It only reads the config files and doesn’t start the servers, so the Status column always shows stopped and Tools shows ?.

o4 mcp list

o4 mcp search

Search the MCP registry at registry.modelcontextprotocol.io. Shows up to 20 results, each with its name, a short description and its transport.

o4 mcp search <query>

Argument	Description
`<query>`	Search query.

o4 mcp search postgres

o4 mcp restart

Restart MCP servers.

o4 mcp restart [name]

Argument	Description
`[name]`	Server name. Restarts all servers if omitted.

Servers only run inside a session, so this command fails from the shell with Server restart is only available within an interactive session. Use /mcp restart [name] in a session instead.

o4 plugin

Manage plugins and marketplaces. o4 plugins works too. With no subcommand, o4 plugin runs o4 plugin list. See Plugins and marketplaces.

o4 plugin [COMMAND]

o4 plugin install

Install a plugin.

o4 plugin install [OPTIONS] <source>

Argument or option	Description
`<source>`	Marketplace plugin name (optionally `name@marketplace`), `owner/repo` shorthand, git URL, or local path.
`--project`	Install project-local instead of globally.

Global plugins go into ~/.o4/plugins, and project plugins into the project’s .o4/plugins. Installing a project plugin needs a trusted workspace.

o4 plugin install owner/repo
o4 plugin install ./my-plugin --project

o4 plugin remove

Remove an installed plugin.

o4 plugin remove <name>

Argument	Description
`<name>`	Plugin name.

o4 plugin remove my-plugin

o4 plugin list

List installed plugins with their version, scope (global or project) and description. It warns about project plugins it ignored because the workspace isn’t trusted.

o4 plugin list

o4 plugin marketplace

Manage plugin marketplaces. With no subcommand, it runs o4 plugin marketplace list. Marketplaces are stored under ~/.o4/marketplaces.

o4 plugin marketplace [COMMAND]

Subcommand	Description
`add <source>`	Register a marketplace. `<source>` is `owner/repo` shorthand, a git URL, or a local path containing `marketplace.json`.
`remove <name>`	Unregister a marketplace.
`list`	List registered marketplaces.
`refresh [name]`	Refresh marketplace catalogs. Refreshes all if you omit the name.

o4 plugin marketplace add owner/marketplace-repo
o4 plugin marketplace refresh

o4 watch

Watch the workspace and run its configured check after each change. When the check fails, o4 offers to fix it. See Watch mode.

o4 watch [OPTIONS]

Option	Description
`-c`, `--command <COMMAND>`	Check command to run after changes.

Without -c, o4 uses command from the [watch] section of the project’s .o4/config.toml (only in a trusted workspace). If that isn’t set, it picks a command from the project files:

Project file	Check command
`Cargo.toml`	`cargo check --workspace`
`package.json`	`npm test`
`pyproject.toml` or `pytest.ini`	`pytest`
`go.mod`	`go test ./...`
none of these	`true`

o4 watch -c "npm run lint"

o4 trust

Trust the current workspace. This enables its project hooks and MCP servers, and the rest of the project configuration covered in Workspace trust. Trust also covers the directories inside it.

o4 trust

cd ~/code/api
o4 trust

Trusted workspace: /Users/you/code/api
Project hooks and MCP servers from this directory will now run.

o4 untrust

Revoke trust for the current workspace.

o4 untrust

o4 untrust

Revoked trust for workspace: /Users/you/code/api
Project hooks and MCP servers from this directory will be ignored.

o4 update

Update o4 to the latest release. o4 downloads the release archive for your platform, checks it against the published checksum, and replaces the binary you ran. See Update o4.

o4 update [OPTIONS]

Option	Description
`--check`	Only report whether a newer release is available.
`--version <VERSION>`	Install this release, for example `0.2.67`, even if it’s older.

Without --version, o4 never replaces a build that is newer than the latest release. If the binary is in a Homebrew Cellar, o4 doesn’t replace it and tells you to run brew upgrade open4rena/tap/o4. Open sessions keep using the old binary until you restart them.

o4 daemon

Manage the o4 daemon, a long-running background process that hosts sessions for clients connecting over a Unix socket. A subcommand is required. The daemon is available on macOS and Linux. See The o4 daemon.

o4 daemon <COMMAND>

Subcommand	Description
`start`	Start the daemon if it is not running.
`stop`	Stop the running daemon.
`restart`	Restart the daemon.
`status`	Report daemon status.

status exits with 0 when the daemon is running and 3 when it isn’t, so scripts can check it without parsing the output. stop also exits with 3 if the daemon wasn’t running. start waits up to 5 seconds for the daemon to answer; if it doesn’t, the error points to the daemon log at ~/.o4/daemon/daemon.log. A hidden serve subcommand runs the daemon in the foreground; see Run in the foreground.

o4 daemon start
o4 daemon status

running
  pid: 48213
  version: 0.2.74
  protocol: v1
  socket: /Users/you/.o4/daemon/o4.sock

o4 eval

Run and report coding-agent evaluations. A subcommand is required. o4 reads the task corpus from the evals directory in the current directory and records runs in .o4/evals.db, so run these commands from the repository that holds the corpus. See Evaluations.

o4 eval <COMMAND>

o4 eval run

Run selected corpus tasks against one or more models.

o4 eval run [OPTIONS] --model <PROVIDER/MODEL>

Option	Description
`--model <PROVIDER/MODEL>`	Model reference. Required. Repeat for a model matrix.
`--tag <TAG>`	Select tasks carrying any supplied tag. Repeatable.
`--task <ID>`	Select a task ID. Repeat to select several.
`--difficulty <LEVEL>`	Select one difficulty band: `easy`, `medium`, or `hard`.
`--budget <USD>`	Abort after the cumulative run cost reaches this amount.
`--enable-mcp`	Opt in to configured MCP tools during evals.
`--prompt-profile <PROFILE>`	Override automatic prompt profile selection for this run: `modern-minimal`, `modern-guided`, `legacy-guided`, or `local-defensive`.

o4 skips a model reference it can’t resolve, with a warning, and runs the rest. If nothing matches your selection, it stops with no tasks matched the requested eval selection.

o4 eval run --model anthropic/claude-sonnet-4-6 --tag rust --budget 5

o4 eval paired

Run an automatic control arm and a modern-minimal candidate arm, to compare the automatic prompt profile with modern-minimal.

o4 eval paired [OPTIONS] --model <PROVIDER/MODEL>

Option	Description
`--model <PROVIDER/MODEL>`	Model reference. Required. Repeat for a model matrix.
`--tag <TAG>`	Select tasks carrying any supplied tag.
`--task <ID>`	Select a task ID. Repeat to select several.
`--difficulty <LEVEL>`	Select one difficulty band: `easy`, `medium`, or `hard`.
`--budget <USD>`	Per-arm run cost limit in USD.
`--enable-mcp`	Opt in to configured MCP tools during evals.
`--repeats <COUNT>`	Number of complete control/candidate repeats. Default `3`; three are required for promotion evidence.
`--json`	Render machine-readable JSON.

o4 eval paired --model anthropic/claude-sonnet-4-6 --difficulty easy

o4 eval report

Render a recorded eval run.

Option	Description
`--run <ID>`	Run ID. Defaults to the latest run.
`--baseline <ID>`	Compare the selected run with this baseline run.
`--json`	Render machine-readable JSON.

o4 eval report --run 12 --baseline 9

o4 eval summary

Summarize autonomy results by o4 version: tasks attempted and completed, how many finished without intervention, and the rates.

Option	Description
`--json`	Render machine-readable JSON.

o4 eval summary --json

o4 eval list

List eval corpus tasks.

Option	Description
`--tag <TAG>`	List only tasks carrying this tag.
`--json`	Render machine-readable JSON.

o4 eval list --tag rust

Exit codes

Commands exit with 0 on success and 1 on an error, printing Error: ... to standard error. An unknown flag, an invalid value or a missing subcommand exits with 2. o4 daemon status and o4 daemon stop use 3 for “not running”. See Print mode and scripting for print mode.

​Global options

​Model and prompt

​Interface and setup

​Permissions and sandbox

​Directories

​Removed flags

​o4 resume

​o4 sessions

​o4 sessions list

​o4 sessions delete

​o4 mcp

​o4 mcp add

​o4 mcp remove

​o4 mcp list

​o4 mcp search

​o4 mcp restart

​o4 plugin

​o4 plugin install

​o4 plugin remove

​o4 plugin list

​o4 plugin marketplace

​o4 watch

​o4 trust

​o4 untrust

​o4 update

​o4 daemon

​o4 eval

​o4 eval run

​o4 eval paired

​o4 eval report

​o4 eval summary

​o4 eval list

​Exit codes

Global options

Model and prompt

Interface and setup

Permissions and sandbox

Directories

Removed flags

o4 resume

o4 sessions

o4 sessions list

o4 sessions delete

o4 mcp

o4 mcp add

o4 mcp remove

o4 mcp list

o4 mcp search

o4 mcp restart

o4 plugin

o4 plugin install

o4 plugin remove

o4 plugin list

o4 plugin marketplace

o4 watch

o4 trust

o4 untrust

o4 update

o4 daemon

o4 eval

o4 eval run

o4 eval paired

o4 eval report

o4 eval summary

o4 eval list

Exit codes