Documentation · Reference
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.
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. |