> ## Documentation Index
> Fetch the complete documentation index at: https://docs.open4rena.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI reference

> Every o4 command-line command and option.

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`.

```text theme={null}
o4 [OPTIONS] [COMMAND]
```

| Command | What it does |
| - | - |
| [`o4 resume`](#o4-resume) | Resume a saved session |
| [`o4 sessions`](#o4-sessions) | List and delete sessions |
| [`o4 mcp`](#o4-mcp) | Manage MCP servers |
| [`o4 plugin`](#o4-plugin) | Manage plugins and marketplaces |
| [`o4 watch`](#o4-watch) | Watch the workspace and run its configured check |
| [`o4 trust`](#o4-trust) | Trust the current workspace |
| [`o4 untrust`](#o4-untrust) | Revoke trust for the current workspace |
| [`o4 update`](#o4-update) | Update o4 to the latest release |
| [`o4 daemon`](#o4-daemon) | Manage the o4 daemon |
| [`o4 eval`](#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](/guides/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

<ParamField path="-m, --model" type="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](/models/overview).

  ```bash theme={null}
  o4 -m anthropic:claude-sonnet-4-6
  ```
</ParamField>

<ParamField path="-p, --prompt" type="string">
  Runs the prompt once without the interface, prints the reply, and exits. See [Print mode and scripting](/guides/print-mode) for permissions, exit codes and output.

  ```bash theme={null}
  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](/guides/context-and-cost).
</ParamField>

<ParamField path="-s, --system-prompt" type="string">
  Text added to o4's system prompt for this session. It doesn't replace the built-in prompt.

  ```bash theme={null}
  o4 -s "Answer in British English."
  ```
</ParamField>

<ParamField path="--prompt-profile" type="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](/models/reasoning).

  ```bash theme={null}
  o4 --prompt-profile local-defensive -m ollama:gemma4
  ```
</ParamField>

<ParamField path="--reasoning" type="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](/models/reasoning).

  ```bash theme={null}
  o4 --reasoning high
  ```
</ParamField>

<ParamField path="--print" type="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.
</ParamField>

<ParamField path="--print-system-prompt" type="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.

  ```bash theme={null}
  o4 --print-system-prompt -m anthropic:claude-sonnet-4-6
  ```
</ParamField>

<ParamField path="-v, --verbose" type="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.

  ```bash theme={null}
  o4 -v -p "Why does this test fail?"
  ```
</ParamField>

<ParamField path="--list-models" type="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.

  ```bash theme={null}
  o4 --list-models
  ```

  ```text theme={null}
  Provider: anthropic
    claude-sonnet-4-6 (context: 1000k, max_tokens: 64000, input: text,image, reasoning: yes)
  ```
</ParamField>

### Interface and setup

<ParamField path="--accessibility" type="boolean">
  Turns on screen reader output for this session, the same as the screen reader setting. See [Themes and display](/configuration/appearance).
</ParamField>

<ParamField path="--no-onboarding" type="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`.

  ```bash theme={null}
  o4 --no-onboarding -m anthropic:claude-sonnet-4-6
  ```
</ParamField>

### Permissions and sandbox

<ParamField path="--permission-mode" type="string">
  Sets how tool calls are approved for this run: `ask`, `accept-edits`, `plan`, `review`, `auto` or `bypass`. See [Permissions](/safety/permissions). Print mode starts in `auto` when you don't set this.

  ```bash theme={null}
  o4 --permission-mode accept-edits
  ```
</ParamField>

<ParamField path="--sandbox" type="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](/safety/sandbox).

  ```bash theme={null}
  o4 --sandbox workspace-write
  ```
</ParamField>

<ParamField path="--dangerously-bypass-hook-trust" type="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](/extend/hooks).
</ParamField>

### 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](/safety/sandbox).

<ParamField path="-C, --cd" type="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.

  ```bash theme={null}
  o4 -C ~/code/api
  ```
</ParamField>

<ParamField path="--add-dir" type="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`.

  ```bash theme={null}
  o4 --add-dir ../shared-lib --add-dir ~/notes
  ```
</ParamField>

### 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.

```text theme={null}
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](/guides/sessions#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](/guides/sessions).

```bash theme={null}
o4 resume
o4 resume 3f2b9c1e-8a4d-4c2e-9f1a-7b6d5e4c3a21
```

## o4 sessions

Manage sessions. A subcommand is required.

```text theme={null}
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. |

```bash theme={null}
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.

```text theme={null}
o4 sessions delete <id>
```

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

```bash theme={null}
o4 sessions delete 3f2b9c1e-8a4d-4c2e-9f1a-7b6d5e4c3a21
```

The command prints `Deleted session <id>` even when no session has that ID. See [Sessions](/guides/sessions#list-and-delete-sessions-from-the-shell) for what deleting removes.

## o4 mcp

Manage MCP servers. With no subcommand, `o4 mcp` runs `o4 mcp list`. See [MCP servers](/extend/mcp).

```text theme={null}
o4 mcp [COMMAND]
```

<Warning>
  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](/extend/mcp).
</Warning>

### o4 mcp add

Add an MCP server from the MCP registry.

```text theme={null}
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](/safety/workspace-trust). 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.

```bash theme={null}
o4 mcp add some-server --global
```

### o4 mcp remove

Remove an MCP server.

```text theme={null}
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.

```bash theme={null}
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 `?`.

```bash theme={null}
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.

```text theme={null}
o4 mcp search <query>
```

| Argument | Description |
| - | - |
| `<query>` | Search query. |

```bash theme={null}
o4 mcp search postgres
```

### o4 mcp restart

Restart MCP servers.

```text theme={null}
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](/extend/plugins).

```text theme={null}
o4 plugin [COMMAND]
```

### o4 plugin install

Install a plugin.

```text theme={null}
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](/safety/workspace-trust).

```bash theme={null}
o4 plugin install owner/repo
o4 plugin install ./my-plugin --project
```

### o4 plugin remove

Remove an installed plugin.

```text theme={null}
o4 plugin remove <name>
```

| Argument | Description |
| - | - |
| `<name>` | Plugin name. |

```bash theme={null}
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.

```bash theme={null}
o4 plugin list
```

### o4 plugin marketplace

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

```text theme={null}
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. |

```bash theme={null}
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](/guides/watch).

```text theme={null}
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` |

```bash theme={null}
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](/safety/workspace-trust). Trust also covers the directories inside it.

```text theme={null}
o4 trust
```

```bash theme={null}
cd ~/code/api
o4 trust
```

```text theme={null}
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.

```text theme={null}
o4 untrust
```

```bash theme={null}
o4 untrust
```

```text theme={null}
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](/installation#update-o4).

```text theme={null}
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](/extend/daemon).

```text theme={null}
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](/extend/daemon#run-in-the-foreground).

```bash theme={null}
o4 daemon start
o4 daemon status
```

```text theme={null}
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](/extend/evals).

```text theme={null}
o4 eval <COMMAND>
```

### o4 eval run

Run selected corpus tasks against one or more models.

```text theme={null}
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`.

```bash theme={null}
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`.

```text theme={null}
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. |

```bash theme={null}
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. |

```bash theme={null}
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. |

```bash theme={null}
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. |

```bash theme={null}
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](/guides/print-mode#exit-codes) for print mode.