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

CLI Reference

Complete reference for the published oh-my-opencode CLI. During the rename transition, OpenCode plugin registration now prefers oh-my-openagent inside opencode.json.

Basic Usage

# Display help
bunx oh-my-opencode

# Or with npx
npx oh-my-opencode

Commands

Command	Description
install	Interactive setup wizard
doctor	Environment diagnostics and health checks
run	OpenCode session runner with task completion enforcement
get-local-version	Display local version information and update check
refresh-model-capabilities	Refresh the cached models.dev-based model capabilities
version	Show version information
mcp oauth	MCP OAuth authentication management

---

install

Interactive installation tool for initial Oh My OpenCode setup. Provides a TUI based on @clack/prompts.

Usage

bunx oh-my-opencode install

Installation Process

1. Subscription Selection: Choose which providers and subscriptions you actually have
2. Plugin Registration: Registers oh-my-openagent in OpenCode settings, or upgrades a legacy oh-my-opencode entry during the compatibility window
3. Configuration File Creation: Writes the generated OmO config to oh-my-opencode.json in the active OpenCode config directory
4. Authentication Hints: Shows the opencode auth login steps for the providers you selected, unless --skip-auth is set

Options

Option	Description
--no-tui	Run in non-interactive mode without TUI
--claude <no|yes|max20>	Claude subscription mode
--openai <no|yes>	OpenAI / ChatGPT subscription
--gemini <no|yes>	Gemini integration
--copilot <no|yes>	GitHub Copilot subscription
--opencode-zen <no|yes>	OpenCode Zen access
--zai-coding-plan <no|yes>	Z.ai Coding Plan subscription
--kimi-for-coding <no|yes>	Kimi for Coding subscription
--opencode-go <no|yes>	OpenCode Go subscription
--skip-auth	Skip authentication setup hints

---

doctor

Diagnoses your environment to ensure Oh My OpenCode is functioning correctly. The current checks are grouped into system, config, tools, and models.

The doctor command detects common issues including:

• Legacy plugin entry references in opencode.json (warns when oh-my-opencode is still used instead of oh-my-openagent)
• Configuration file validity and JSONC parsing errors
• Model resolution and fallback chain verification
• Missing or misconfigured MCP servers

Usage

bunx oh-my-opencode doctor

Diagnostic Categories

Category	Check Items
System	OpenCode binary, version (>= 1.0.150), plugin registration, legacy package name warning
Config	Configuration file validity, JSONC parsing, Zod schema validation
Tools	AST-Grep, LSP servers, GitHub CLI, MCP servers
Models	Model capabilities cache, model resolution, agent/category overrides, availability

Options

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

Example Output

oh-my-opencode doctor

┌──────────────────────────────────────────────────┐
│  Oh-My-OpenAgent Doctor                           │
└──────────────────────────────────────────────────┘

System
  ✓ OpenCode version: 1.0.155 (>= 1.0.150)
  ✓ Plugin registered in opencode.json

Config
  ✓ oh-my-opencode.jsonc is valid
  ✓ Model resolution: all agents have valid fallback chains
  ⚠ categories.visual-engineering: using default model

Tools
  ✓ AST-Grep available
  ✓ LSP servers configured

Models
  ✓ 11 agents, 8 categories, 0 overrides
  ⚠ Some configured models rely on compatibility fallback

Summary: 10 passed, 1 warning, 0 failed

---

run

Run opencode with todo/background task completion enforcement. Unlike 'opencode run', this command waits until all todos are completed or cancelled, and all child sessions (background tasks) are idle.

Usage

bunx oh-my-opencode run <message>

Options

Option	Description
-a, --agent <name>	Agent to use (default: from CLI/env/config, fallback: Sisyphus)
-m, --model <provider/model>	Model override (e.g., anthropic/claude-sonnet-4)
-d, --directory <path>	Working directory
-p, --port <port>	Server port (attaches if port already in use)
--attach <url>	Attach to existing opencode server URL
--on-complete <command>	Shell command to run after completion
--json	Output structured JSON result to stdout
--no-timestamp	Disable timestamp prefix in run output
--verbose	Show full event stream (default: messages/tools only)
--session-id <id>	Resume existing session instead of creating new one

---

get-local-version

Show current installed version and check for updates.

Usage

bunx oh-my-opencode get-local-version

Options

Option	Description
-d, --directory	Working directory to check config from
--json	Output in JSON format for scripting

Output

Shows:

• Current installed version
• Latest available version on npm
• Whether you're up to date
• Special modes (local dev, pinned version)

---

version

Show version information.

Usage

bunx oh-my-opencode version

--on-complete runs through your current shell when possible: sh on Unix shells, pwsh for PowerShell on non-Windows, powershell.exe for PowerShell on Windows, and cmd.exe as the Windows fallback.

---

mcp oauth

Manages OAuth 2.1 authentication for remote MCP servers.

Usage

# Login to an OAuth-protected MCP server
bunx oh-my-opencode mcp oauth login <server-name> --server-url https://api.example.com

# Login with explicit client ID and scopes
bunx oh-my-opencode mcp oauth login my-api --server-url https://api.example.com --client-id my-client --scopes "read,write"

# Remove stored OAuth tokens
bunx oh-my-opencode mcp oauth logout <server-name>

# Check OAuth token status
bunx oh-my-opencode mcp oauth status [server-name]

Options

Option	Description
--server-url <url>	MCP server URL (required for login)
--client-id <id>	OAuth client ID (optional if server supports Dynamic Client Registration)
--scopes <scopes>	Comma-separated OAuth scopes

Token Storage

Tokens are stored in ~/.config/opencode/mcp-oauth.json with 0600 permissions (owner read/write only). Key format: {serverHost}/{resource}.

---

Configuration Files

The runtime loads user config as the base config, then merges project config on top:

1. Project Level: .opencode/oh-my-openagent.jsonc, .opencode/oh-my-openagent.json, .opencode/oh-my-opencode.jsonc, or .opencode/oh-my-opencode.json
2. User Level: ~/.config/opencode/oh-my-openagent.jsonc, ~/.config/opencode/oh-my-openagent.json, ~/.config/opencode/oh-my-opencode.jsonc, or ~/.config/opencode/oh-my-opencode.json

Naming Note: The published package and binary are still oh-my-opencode. Inside opencode.json, the compatibility layer now prefers the plugin entry oh-my-openagent. Plugin config loading recognizes both oh-my-openagent.* and legacy oh-my-opencode.* basenames. If both basenames exist in the same directory, the legacy oh-my-opencode.* file currently wins.

Filename Compatibility

Both .jsonc and .json extensions are supported. JSONC (JSON with Comments) is preferred as it allows:

• Comments (both // and /* */ styles)
• Trailing commas in arrays and objects

If both .jsonc and .json exist in the same directory, the .jsonc file takes precedence.

JSONC Support

Configuration files support JSONC (JSON with Comments) format. You can use comments and trailing commas.

{
  // Agent configuration
  "sisyphus_agent": {
    "disabled": false,
    "planner_enabled": true,
  },

  /* Category customization */
  "categories": {
    "visual-engineering": {
      "model": "google/gemini-3.1-pro",
    },
  },
}

---

Troubleshooting

"OpenCode version too old" Error

# Update OpenCode
npm install -g opencode@latest
# or
bun install -g opencode@latest

"Plugin not registered" Error

# Reinstall plugin
bunx oh-my-opencode install

Doctor Check Failures

# Diagnose with detailed information
bunx oh-my-opencode doctor --verbose

# Show compact system dashboard
bunx oh-my-opencode doctor --status

# JSON output for scripting
bunx oh-my-opencode doctor --json

"Using legacy package name" Warning

The doctor warns if it finds the legacy plugin entry oh-my-opencode in opencode.json. Update the plugin array to the canonical oh-my-openagent entry:

# Replace the legacy plugin entry in user config
jq '.plugin = (.plugin // [] | map(if . == "oh-my-opencode" then "oh-my-openagent" else . end))' \
  ~/.config/opencode/opencode.json > /tmp/opencode.json && mv /tmp/opencode.json ~/.config/opencode/opencode.json

---

refresh-model-capabilities

Refreshes the cached model capabilities snapshot from models.dev. This updates the local cache used by capability resolution and compatibility diagnostics.

Usage

bunx oh-my-opencode refresh-model-capabilities

Options

Option	Description
-d, --directory	Working directory to read oh-my-opencode config from
--source-url <url>	Override the models.dev source URL
--json	Output refresh summary as JSON

Configuration

Configure automatic refresh behavior in your plugin config:

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

---

Non-Interactive Mode

Use JSON output for CI or scripted diagnostics.

# Run doctor in CI environment
bunx oh-my-opencode doctor --json

# Save results to file
bunx oh-my-opencode doctor --json > doctor-report.json

---

Developer Information

CLI Structure

src/cli/
├── cli-program.ts        # Commander.js-based main entry
├── install.ts            # @clack/prompts-based TUI installer
├── config-manager/       # JSONC parsing, multi-source config management
│   └── *.ts
├── doctor/               # Health check system
│   ├── index.ts          # Doctor command entry
│   └── checks/           # 17+ individual check modules
├── run/                  # Session runner
│   └── *.ts
└── mcp-oauth/            # OAuth management commands
    └── *.ts

Adding New Doctor Checks

Create src/cli/doctor/checks/my-check.ts:

import type { DoctorCheck } from "../types";

export const myCheck: DoctorCheck = {
  name: "my-check",
  category: "environment",
  check: async () => {
    // Check logic
    const isOk = await someValidation();

    return {
      status: isOk ? "pass" : "fail",
      message: isOk ? "Everything looks good" : "Something is wrong",
    };
  },
};

Register in src/cli/doctor/checks/index.ts:

export { myCheck } from "./my-check";