Reference: the ori command

Neutral, exhaustive description of the ori server binary and its flags.

Synopsis

ori [--addr ADDR] [--cwd DIR] [--agent-cmd COMMAND]

At startup, ori spawns the agent command, performs the ACP handshake (initialize, then session/new), then serves the web application and its WebSocket endpoint. If the agent cannot be started or the handshake fails, ori exits with a non-zero status and an error on stderr.

Flags

Flag	Type	Default	Description
`--addr`	string	`:8888`	TCP address the HTTP server listens on. The empty host binds all interfaces.
`--cwd`	string	current directory	Working directory handed to the agent session. Must exist and be a directory; resolved to an absolute path.
`--agent-cmd`	string	`npx -y @agentclientprotocol/claude-agent-acp`	Command spawning the ACP agent, split on whitespace (first field: executable; the rest: arguments).

HTTP endpoints

Route	Description
`GET /healthz`	Returns `{"status":"ok"}` with status 200.
`GET /ws`	WebSocket endpoint of the panel; see the WebSocket protocol reference.
`GET /*`	The embedded single-page application; unknown paths fall back to `index.html`. Returns 503 if the binary was built without a UI build.

Example

./bin/ori --addr :9000 --cwd /work/my-project --agent-cmd "bin/ori-mock-agent"

Errors

Error	Cause
`--agent-cmd must not be empty`	The flag was set to blanks.
`--cwd: … no such file or directory`	The working directory does not exist.
`--cwd: … is not a directory`	The path exists but is a plain file.
`start agent "…": …`	The agent executable could not be started.
`initialize: …` / `new session: …`	The ACP handshake with the agent failed.

Companion binary: ori-mock-agent

ori-mock-agent [--delay DURATION]

Flag	Type	Default	Description
`--delay`	duration	`300ms`	Pause between streamed updates. `0s` disables pacing.

ori-mock-agent speaks ACP on stdio and plays one deterministic scenario per prompt: a thought, a two-entry plan, a read tool call, one permission request, and — if granted — an edit tool call with a diff and a final message.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55


# Reference: the ori command

> Neutral, exhaustive description of the `ori` server binary and its flags.

## Synopsis

```bash
ori [--addr ADDR] [--cwd DIR] [--agent-cmd COMMAND]
```

At startup, `ori` spawns the agent command, performs the ACP handshake (`initialize`, then `session/new`), then serves the web application and its WebSocket endpoint. If the agent cannot be started or the handshake fails, `ori` exits with a non-zero status and an error on stderr.

## Flags

| Flag | Type | Default | Description |
| --- | --- | --- | --- |
| `--addr` | string | `:8888` | TCP address the HTTP server listens on. The empty host binds all interfaces. |
| `--cwd` | string | current directory | Working directory handed to the agent session. Must exist and be a directory; resolved to an absolute path. |
| `--agent-cmd` | string | `npx -y @agentclientprotocol/claude-agent-acp` | Command spawning the ACP agent, split on whitespace (first field: executable; the rest: arguments). |

## HTTP endpoints

| Route | Description |
| --- | --- |
| `GET /healthz` | Returns `{"status":"ok"}` with status 200. |
| `GET /ws` | WebSocket endpoint of the panel; see the [WebSocket protocol reference](websocket-protocol.md). |
| `GET /*` | The embedded single-page application; unknown paths fall back to `index.html`. Returns 503 if the binary was built without a UI build. |

## Example

```bash
./bin/ori --addr :9000 --cwd /work/my-project --agent-cmd "bin/ori-mock-agent"
```

## Errors

| Error | Cause |
| --- | --- |
| `--agent-cmd must not be empty` | The flag was set to blanks. |
| `--cwd: … no such file or directory` | The working directory does not exist. |
| `--cwd: … is not a directory` | The path exists but is a plain file. |
| `start agent "…": …` | The agent executable could not be started. |
| `initialize: …` / `new session: …` | The ACP handshake with the agent failed. |

## Companion binary: ori-mock-agent

```bash
ori-mock-agent [--delay DURATION]
```

| Flag | Type | Default | Description |
| --- | --- | --- | --- |
| `--delay` | duration | `300ms` | Pause between streamed updates. `0s` disables pacing. |

`ori-mock-agent` speaks ACP on stdio and plays one deterministic scenario per prompt: a thought, a two-entry plan, a read tool call, one permission request, and — if granted — an edit tool call with a diff and a final message.