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

CLI Reference

Complete reference for the oh-my-opencode command-line interface.

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
mcp oauth	MCP OAuth authentication management
auth	Google Antigravity OAuth authentication
get-local-version	Display local version information

---

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. Provider Selection: Choose your AI provider (Claude, ChatGPT, or Gemini)
2. API Key Input: Enter the API key for your selected provider
3. Configuration File Creation: Generates opencode.json or oh-my-opencode.json files
4. Plugin Registration: Automatically registers the oh-my-opencode plugin in OpenCode settings

Options

Option	Description
--no-tui	Run in non-interactive mode without TUI (for CI/CD environments)
--verbose	Display detailed logs

---

doctor

Diagnoses your environment to ensure Oh-My-OpenCode is functioning correctly. Performs 17+ health checks.

Usage

bunx oh-my-opencode doctor

Diagnostic Categories

Category	Check Items
Installation	OpenCode version (>= 1.0.150), plugin registration status
Configuration	Configuration file validity, JSONC parsing
Authentication	Anthropic, OpenAI, Google API key validity
Dependencies	Bun, Node.js, Git installation status
Tools	LSP server status, MCP server status
Updates	Latest version check

Options

Option	Description
--category <name>	Check specific category only (e.g., --category authentication)
--json	Output results in JSON format
--verbose	Include detailed information

Example Output

oh-my-opencode doctor

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

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

Configuration
  ✓ oh-my-opencode.json is valid
  ⚠ categories.visual-engineering: using default model

Authentication
  ✓ Anthropic API key configured
  ✓ OpenAI API key configured
  ✗ Google API key not found

Dependencies
  ✓ Bun 1.2.5 installed
  ✓ Node.js 22.0.0 installed
  ✓ Git 2.45.0 installed

Summary: 10 passed, 1 warning, 1 failed

---

run

Executes OpenCode sessions and monitors task completion.

Usage

bunx oh-my-opencode run [prompt]

Options

Option	Description
--enforce-completion	Keep session active until all TODOs are completed
--timeout <seconds>	Set maximum execution time
--agent <name>	Specify agent to use
--directory <path>	Set working directory
--port <number>	Set port for session
--attach	Attach to existing session
--json	Output in JSON format
--no-timestamp	Disable timestamped output
--session-id <id>	Resume existing session
--on-complete <action>	Action on completion
--verbose	Enable verbose logging

---

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}.

---

auth

Manages Google Antigravity OAuth authentication. Required for using Gemini models.

Usage

# Login
bunx oh-my-opencode auth login

# Logout
bunx oh-my-opencode auth logout

# Check current status
bunx oh-my-opencode auth status

---

Configuration Files

The CLI searches for configuration files in the following locations (in priority order):

1. Project Level: .opencode/oh-my-opencode.json
2. User Level: ~/.config/opencode/oh-my-opencode.json

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-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

# Check specific category only
bunx oh-my-opencode doctor --category authentication

---

Non-Interactive Mode

Use the --no-tui option for CI/CD environments.

# Run doctor in CI environment
bunx oh-my-opencode doctor --no-tui --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"