# CLI & JSON-RPC Reference

Every `oh-router` subcommand supports `--json` for structured output and communicates with `ohd` over `~/.local/state/oh/ohd/ohd.sock` using newline-delimited JSON-RPC.

Canonical URL: https://ohrouter.com/docs/cli

## Global flags and environment variables

| Flag / Variable | Default | Description |
| --- | --- | --- |
| `--json` | `false` | Emit pretty-printed JSON on `stdout` (errors emit `{"ok":false,"error":...}`). |
| `--state-dir <DIR>` / `OH_STATE_DIR` | `~/.local/state/oh/ohd` | Directory holding `ohd.sock`, `events.sock`, `bridge.token`, and `holders/`. |
| `--socket <PATH>` / `OH_CONTROL_SOCKET` | `<state-dir>/ohd.sock` | Control Unix domain socket (`0600`). |
| `--event-socket <PATH>` / `OH_EVENT_SOCKET` | `<state-dir>/events.sock` | Hook and statusLine event Unix domain socket (`0600`). |
| `--config-dir <DIR>` / `OH_ROUTER_CONFIG_DIR` | `~/.config/oh-router` | Configuration directory containing `config.json` and `plugins/`. |

## `oh-router` subcommands

| Command | Key Flags & Arguments | Summary |
| --- | --- | --- |
| `oh-router version` | `--json`, `-V`, `--version` | Print CLI and daemon protocol version. |
| `oh-router daemon <subcmd>` | `start [--http-port <PORT>]`, `stop`, `status`, `setup-hooks [--claude-dir <DIR>] [--passthrough <CMD>] [--write]` | Start, stop, or inspect `ohd` and configure Claude Code hooks. |
| `oh-router spawn [PROMPT...]` | `--kind <claude\|codex\|shell>`, `--tier <opus\|sol\|fable\|astra>`, `--class <standard\|frontier>`, `--effort <low\|medium\|high\|max>`, `--plugin-builder`, `--headless`, `--review`, `--require <CAP>`, `--profile <ID>`, `--device <ID>`, `--project <NAME>`, `--workspace <NAME>`, `--cwd <DIR>`, `--title <TEXT>`, `--request-key <KEY>` | Spawn a routed coding-agent or shell session. |
| `oh-router claude [PROMPT...]` | Same routing flags as `spawn` with `kind` fixed to `claude` | Spawn a Claude Code session (`Opus` or `Fable`). |
| `oh-router codex [PROMPT...]` | Same routing flags as `spawn` with `kind` fixed to `codex` | Spawn a Codex session (`Sol` or `Astra`). |
| `oh-router ps` | `--project <NAME>`, `--json` | List active and recent local plus paired remote sessions. |
| `oh-router inspect <ID>` | `--json` | Inspect session state, turn history, dialog details, and VT screen lines. |
| `oh-router steer <ID> <PROMPT...>` | `--mode <auto\|now\|queue\|interrupt>` | Send or queue a prompt through the 2D VT screen guard. |
| `oh-router switch <ID>` | `--tier <opus\|sol\|fable\|astra>`, `--class <standard\|frontier>`, `--effort <low\|medium\|high\|max>`, `--profile <ID>`, `--prompt <NOTE>` | Stage recent context and continue the session on another tier or provider. |
| `oh-router action <ID> <ACT>` | `approve`, `deny`, `trust_folder`, `ctrl_c`, `stop` | Apply a dialog action or stop a session. |
| `oh-router queue <subcmd> <ID>` | `list`, `add <PROMPT...>`, `remove <PROMPT_ID>`, `move <PROMPT_ID> <INDEX>`, `clear`, `flush` | Manage per-session queued prompts. |
| `oh-router profiles <subcmd>` | `list`, `add --provider <claude\|codex> --id <ID> [--label <LBL>]`, `login [--no-open]`, `probe`, `redeem-reset` | Manage workspace directories and isolated Chrome OAuth sign-in. |
| `oh-router policy <subcmd>` | `get`, `set [--interactive-provider <P>] [--headless-provider <P>] [--cross-family-review <BOOL>] [--model-fallback <BOOL>] [--cross-provider-fallback <BOOL>] [--auto-folder-trust <BOOL>] [--codex-earned-resets <BOOL>] [--pin <proj=tier>]`, `plugin-spec` | Inspect or update routing policy and view plugin spec. |
| `oh-router devices <subcmd>` | `list`, `pair-command`, `recipe [--name <N>] [--role <R>] [--quick] [--tunnel <T>] [--hostname <H>]`, `ssh-config --host <A> --hostname <H> --user <U> [--write]`, `add-remote --name <N> --tunnel-url <URL> --bearer-token <TOK>`, `toggle-stream <ID> <BOOL>`, `tunnel-start [--scope <stream_steer\|admin>] [--rotate-token] [--port <P>] [--quick] [--tunnel <T>] [--hostname <H>] [--publish]`, `tunnel-stop` | Manage Cloudflare Tunnel pairing, loopback HTTP bridge, and SSH config. |
| `oh-router board <subcmd>` | `status`, `connect [--mode <local\|vercel>] [--url <URL>] [--token <TOK>] [--channel <CH>]`, `sync`, `subscribe <CH> [--auto-claim]`, `tasks [--channel <CH>] [--state <S>]`, `create-task [--channel <CH>] [--label k=v] [--need <ID>] <TEXT...>`, `claim [<ID_OR_CH>] [--ready]`, `block <ID> <REASON...>`, `complete <ID> [--result <TEXT>]`, `thread <ID>`, `reply <ID> <TEXT...>` | Coordinate `@vercel/board` channels, tasks, claims, and threads. |
| `oh-router worker` | `--once` or `--loop`, `--channel <CH>`, `--project <NAME>`, `--interval-ms <MS>` | Claim ready board tasks, spawn routed sessions, and renew leases. |
| `oh-router hook [<Event>]` | `--session <ID>` (reads hook JSON from `stdin`) | Forward Claude Code or Codex hook events to `events.sock`. |
| `oh-router statusline-bridge` | `--passthrough <CMD>`, `--session <ID>`, `--profile <ID>` | Parse Claude Code 2.1.327+ statusLine limits and forward to `ohd`. |

## `ohd.sock` & `/v1/rpc` JSON-RPC methods

Each request is a JSON object `{"id":"req-1","method":"<name>","params":{...}}` terminated by `\n` on `ohd.sock` or sent via `POST /v1/rpc` with `Authorization: Bearer <token>`. Responses return `{"id":"req-1","ok":true,"result":{...}}` or `{"id":"req-1","ok":false,"error":{"code":"...","message":"..."}}`.

| Method Group | Methods | `stream_steer` Allowed |
| --- | --- | --- |
| Daemon & State | `daemon.ping`, `state.snapshot` | Yes (`daemon.shutdown` requires `admin`). |
| Sessions | `session.list`, `session.inspect`, `session.spawn`, `session.steer`, `session.action`, `session.switch`, `session.input`, `session.resize`, `session.stop`, `session.pair_handoff`, `session.meta.update` | Yes for `claude` and `codex` sessions (`kind: "shell"` and custom `argv` require `admin`). |
| Prompt Queue | `queue.list`, `queue.add`, `queue.remove`, `queue.move`, `queue.clear`, `queue.flush` | Yes (non-shell sessions). |
| Profiles & Policy | `router.profiles.list`, `router.profiles.add`, `router.profiles.login`, `router.profiles.probe`, `router.profiles.redeem_reset`, `router.policy.get`, `router.policy.update`, `router.policy.plugin_spec` | Read-only `router.policy.get` and `router.policy.plugin_spec`; mutations require `admin`. |
| Devices & Tunnels | `devices.list`, `devices.pair_command`, `devices.recipe`, `devices.ssh_config`, `devices.add_remote`, `devices.toggle_stream`, `devices.tunnel_start`, `devices.tunnel_stop` | `devices.list` allowed; pairing and tunnel mutations require `admin`. |
| Board & Worker | `board.status`, `board.connect`, `board.sync_now`, `board.channels.subscribe`, `board.tasks.list`, `board.tasks.create`, `board.tasks.claim_and_route`, `board.tasks.block`, `board.tasks.complete`, `board.threads.read`, `board.threads.reply`, `board.worker.tick` | Read/task coordination methods per scope policy; `board.connect` requires `admin`. |
