slug: cli

CLI Reference

The oar CLI is a single binary that controls the backend service. With one exception (oar start), every command is a short-lived HTTP forwarder to the running service's admin API on 127.0.0.1:26969 — they do not start a second backend.

The global --json flag switches any command's output from human-readable to JSON, which is useful for scripting.

Service

Control the long-lived backend process. oar start is the only command that runs the service itself — everything else assumes it is already running.

Command	Description
`oar start`	Run the service (long-lived, listens on `:26969`)
`oar stop`	Stop the running service
`oar restart`	Kill the old process and spawn a new one
`oar status`	Show version, port, mode, autoStart, PID
`oar service uninstall`	Disable auto-start (removes the launchd entry on macOS)
`oar service status`	Report whether auto-start is installed

service — bash

$ oar status

# version: 1.3.0 port: 26969 mode: cli

# autoStart: yes pid: 41203 uptime: 2m 14s

Update

Check for and apply updates from the R2 CDN (with GitHub/Gitee fallback). Downloads are verified by MD5 hash and the binary is replaced atomically.

Command	Description
`oar update`	Check and apply, interactive, with progress bar
`oar update check`	Check only, do not apply
`oar update --json`	Non-interactive JSON output for scripts

update — bash

$ oar update check

# current: 1.3.0

# latest: 1.4.2

# run 'oar update' to apply

Account

Accounts are platform instances — a base URL plus one or more API keys. Each account can sync its live model list from upstream /v1/models.

Command	Description
`oar account list`	List all accounts
`oar account get <id>`	Show one account
`oar account create --name <n> --platform <p> --base-url <url> [--key <k>] [--protocol <proto>]`	Create an account
`oar account update <id> [--name --platform --base-url --key --protocol --active]`	Update an account
`oar account delete <id>`	Delete an account
`oar account sync <id>`	Sync models from upstream `/v1/models`

account — bash

$ oar account create --name DeepSeek --platform deepseek \

--base-url https://api.deepseek.com --key sk-xxxx

# created account deepseek (id: acct_01)

oar account sync acct_01

# synced 8 models from upstream

Group

A group is a pool of models with a routing strategy, retry policy and cooldown. Groups are the unit of failover — when one model rate-limits, the next model in the group takes over.

Command	Description
`oar group list`	List all groups
`oar group get <name\|id>`	Show group + models with status
`oar group create --name <n>`	Create an empty group
`oar group update <name\|id> [--name --strategy --max-retries --cooldown --retry-on-failure --cross-model-retry --aliases]`	Update group settings
`oar group delete <name\|id>`	Delete a group
`oar group recover <name\|id>`	Reset all model error states in the group
`oar group add-model <name\|id> --model-id <id> [--priority <n>] [--account-id <id>]`	Add a model to the group
`oar group remove-model <name\|id> --gm-id <id>`	Remove a model from the group

group — bash

$ oar group create --name coding

# created group coding (id: grp_01)

oar group add-model coding --model-id mdl_claude --priority 1

# added model to group

oar group recover coding

# reset 2 models from cooldown

Group arguments accept name or id

Every group command accepts either the human-readable name or the internal id. The id is shown by oar group list.

Model

Models live under accounts. A model can be in a healthy state or in cooldown after repeated upstream failures.

Command	Description
`oar model list <accountId>`	List models under an account
`oar model recover <id>`	Recover a single model from cooldown

model — bash

$ oar model list acct_01

# mdl_claude claude-sonnet-4 healthy

# mdl_glm glm-5.2 cooldown (retry in 47s)

oar model recover mdl_glm

# recovered mdl_glm

Agent

Agents are the downstream clients OAR serves (Claude Code, Codex, Hermes, …). Each agent has a config file and a default group.

Command	Description
`oar agent list`	List all agents
`oar agent check <slug>`	Check an agent's config status
`oar agent regenerate <slug>`	Regenerate the agent's config file
`oar agent set-group <slug> --group-id <id>`	Set the agent's default group

agent — bash

$ oar agent check claude

# config: ~/.claude.json

# base_url: http://127.0.0.1:26969/project/gz-project

# group: coding (healthy)

oar agent set-group claude --group-id grp_02

# switched default group to grp_02

Project

A project binds an agent to a group, giving you a stable base_url (/project/<name>/v1/*) that survives group and model swaps.

Command	Description
`oar project list`	List all projects
`oar project get <name\|id>`	Show one project
`oar project create --name <n> [--path <dir>]`	Create a project
`oar project delete <name\|id>`	Delete a project
`oar project add-agent <name\|id> --slug <slug> [--group-id <id>]`	Bind an agent to the project
`oar project remove-agent <name\|id> --slug <slug>`	Unbind an agent
`oar project gen-config <name\|id> [--slug <slug>]`	Generate the agent config file for the project

project — bash

$ oar project create --name gz-project --path ~/code/gz

# created project gz-project (id: prj_01)

oar project add-agent gz-project --slug claude --group-id grp_01

# bound agent claude to project with group grp_01

oar project gen-config gz-project --slug claude

# wrote config to ~/.claude.json

Open

oar open is a convenience launcher. It resolves the project directory, changes into it, and spawns the agent's own CLI with any trailing args. This matches the workflow of running an agent from inside its project folder.

oar open [--agent <slug>] [--project <name|id>] [-- ...agent args]

--project empty → resolve the project from the current working directory.
--agent empty → auto-pick if the project has exactly one agent binding.

open — bash

$ oar open --project gz-project -- claude --resume

# cd ~/code/gz

# spawn: claude --resume

Settings

Read and write OAR settings. Use oar settings list to discover available keys.

Command	Description
`oar settings list`	List all settings
`oar settings set <key> <value>`	Update a setting

settings — bash

$ oar settings list

# keepDock true

# autoStart true

# proxyPort 26969

oar settings set keepDock false

# keepDock = false

Usage

Inspect traffic through the proxy. oar usage aggregates token spend by account/group/model over a time window; oar activity lists recent individual requests.

Command	Description
`oar usage [--start-time <t>] [--end-time <t>]`	Usage summary over a window
`oar activity [--limit <n>]`	Recent requests (default limit 50)

usage — bash

$ oar usage --start-time 2026-07-01 --end-time 2026-07-17

# account requests tokens_in tokens_out

# deepseek 312 482k 1.2M

# anthropic 87 120k 640k

oar activity --limit 5

# 2026-07-17 14:21 /project/gz/v1/chat/completions 200 1.4s

Vendor

Manage the built-in vendor presets (DeepSeek, OpenAI, Anthropic, Volcano Engine, SiliconFlow, MiniMax, …). Vendor presets are used by the account creation form to prefill base URL and protocol.

Command	Description
`oar vendor list`	List vendor presets
`oar vendor sync`	Refresh vendor presets from upstream

Capture

Capture records raw inbound and outbound traffic for debugging protocol adapters and routing decisions. A capture runs for a fixed duration (default 300s) and stores files under ~/.open-agent-router/captures/.

Command	Description
`oar capture start [--duration <sec>]`	Start a capture (default 300s)
`oar capture stop`	Stop the active capture early
`oar capture status`	Report whether a capture is running
`oar capture get <filename>`	Read a capture record

capture — bash

$ oar capture start --duration 60

# capture started, runs for 60s

oar capture status

# running: yes started: 14:21:03 remaining: 47s

oar capture get 2026-07-17-1421.json

# { in: {...}, out: {...}, model: claude-sonnet-4, route: project/gz }

Other

Command	Description
`oar version` / `oar -v` / `oar --version`	Print the version
`oar help` / `oar -h` / `oar --help`	Show help

Global flags

--json is accepted by every command and switches the output to JSON. Useful for piping into jq or other scripts.

For the desktop app (tray, auto-start, auto-update), see the Desktop App page. For a hands-on walkthrough, start at the Quickstart.

Desktop App

Configuration