oh-my-opencode/docs/reference/cli.md

CLI Reference

Complete reference for the published CLI package. During the rename transition, both package names work:

• oh-my-openagent (preferred package name)
• oh-my-opencode (compatibility package name)

Plugin registration inside opencode.json prefers oh-my-openagent.

Basic Usage

# Display help (preferred package)
bunx oh-my-openagent

# Compatibility package
bunx oh-my-opencode

Commands

Command	Description
install	Interactive setup wizard
doctor	Installation health diagnostics
run <message>	Non-interactive OpenCode session runner with completion enforcement
get-local-version	Show current installed version and check for updates
refresh-model-capabilities	Refresh cached model capabilities snapshot from models.dev
boulder	Inspect Sisyphus boulder work-state (active plan, per-task timers, session lineage)
version	Show CLI version
mcp oauth	OAuth token management for MCP servers

---

install

Interactive installation tool for initial setup.

Usage

bunx oh-my-openagent install

Options

Option	Description
--no-tui	Run in non-interactive mode (requires all needed options)
--claude <value>	Claude subscription: no, yes, max20
--openai <value>	OpenAI/ChatGPT subscription: no, yes
--gemini <value>	Gemini integration: no, yes
--copilot <value>	GitHub Copilot subscription: no, yes
--opencode-zen <value>	OpenCode Zen access: no, yes
--zai-coding-plan <value>	Z.ai Coding Plan subscription: no, yes
--kimi-for-coding <value>	Kimi For Coding subscription: no, yes
--opencode-go <value>	OpenCode Go subscription: no, yes
--vercel-ai-gateway <value>	Vercel AI Gateway: no, yes
--skip-auth	Skip authentication setup hints

Anonymous telemetry uses PostHog with a hashed installation identifier. Disable with OMO_SEND_ANONYMOUS_TELEMETRY=0 or OMO_DISABLE_POSTHOG=1.

---

doctor

Diagnoses your environment and configuration. Checks are grouped into four categories: System, Config, Tools, and Models.

Usage

bunx oh-my-openagent doctor

Options

Option	Description
--status	Show compact system dashboard
--verbose	Show detailed diagnostic information
--json	Output results in JSON format

Notes

• The current minimum OpenCode version check is >= 1.4.0.
• The doctor command warns when legacy plugin registration (oh-my-opencode) is still present in opencode.json.

---

run

Runs a non-interactive session and exits only when both conditions are true:

• all todos are completed or cancelled
• all background child sessions are idle

Usage

bunx oh-my-openagent run <message>

Options

Option	Description
-a, --agent <name>	Agent to use (default resolution chain applies)
-m, --model <provider/model>	Model override (example: anthropic/claude-sonnet-4)
-d, --directory <path>	Working directory
-p, --port <port>	Server port (attaches if already in use)
--attach <url>	Attach to an existing OpenCode server URL
--on-complete <command>	Run shell command after completion
--json	Output structured JSON result
--no-timestamp	Disable timestamp prefix in output
--verbose	Show full event stream (default: messages/tools only)
--session-id <id>	Resume an existing session

Agent Resolution Order

1. --agent
2. OPENCODE_DEFAULT_AGENT
3. default_run_agent in plugin config
4. Sisyphus

---

get-local-version

Shows local plugin version state and update status.

Usage

bunx oh-my-openagent get-local-version

Options

Option	Description
-d, --directory <path>	Working directory used for plugin/config detection
--json	Output JSON for scripting

---

refresh-model-capabilities

Refreshes the cached model capabilities snapshot from models.dev.

Usage

bunx oh-my-openagent refresh-model-capabilities

Options

Option	Description
-d, --directory <path>	Working directory used to read plugin config
--source-url <url>	Override models.dev source URL
--json	Output refresh summary as JSON

Configuration

{
  "model_capabilities": {
    "enabled": true,
    "auto_refresh_on_start": true,
    "refresh_timeout_ms": 5000,
    "source_url": "https://models.dev/api.json"
  }
}

---

version

Shows CLI package version.

Usage

bunx oh-my-openagent version

---

mcp oauth

OAuth token management for MCP servers (Tier-3 MCP OAuth flow, including PKCE and dynamic client registration when supported by the server).

Usage

# Authenticate
bunx oh-my-openagent mcp oauth login <server-name> --server-url https://api.example.com

# Authenticate with explicit client ID and scopes
bunx oh-my-openagent mcp oauth login <server-name> --server-url https://api.example.com --client-id my-client --scopes read write

# Remove stored tokens
bunx oh-my-openagent mcp oauth logout <server-name> --server-url https://api.example.com

# Show token status
bunx oh-my-openagent mcp oauth status [server-name]

Options

Option	Description
--server-url <url>	OAuth server URL (required by login, and required by logout)
--client-id <id>	OAuth client ID (optional if server supports DCR)
--scopes <scopes...>	OAuth scopes as variadic values

---

Exit Codes

• 0 on success
• 1 on failure

run, install, doctor, get-local-version, refresh-model-capabilities, and mcp oauth subcommands return explicit numeric exit codes.