CLI Commands & Diagnostics
Relevant source files
The following files were used as context for generating this wiki page:
The OhMyOpenCode CLI serves as the primary entry point for users to interact with the autonomous agent system. It provides a suite of 107 utilities powered by Commander.js and a Terminal User Interface (TUI) built with @clack/prompts. The system is designed to handle everything from initial setup and health diagnostics to complex session orchestration and deep repository analysis.
Sources: src/cli/AGENTS.md:3-5
CLI Architecture & Command Structure
The CLI is structured into several functional modules, each responsible for a specific aspect of the user experience. The entry point at src/cli/index.ts manages high-level command routing, while subdirectories handle specific logic like installation, health checks, and session running.
Core CLI Commands
| Command | Purpose | Implementation Detail |
|---|---|---|
install | Interactive setup | Supports provider selection via @clack/prompts |
doctor | Health diagnostics | Executes 14 categories of health checks |
run | Session launcher | Orchestrates AI sessions with todo enforcement |
get-local-version | Versioning | Detects local version and checks for updates |
mcp-oauth | Authentication | Manages MCP OAuth authentication flows |
Sources: src/cli/AGENTS.md:28-34, src/cli/AGENTS.md:7-25
Command Invocation Flow
The following diagram illustrates how a user request is routed through the CLI entry point to specific specialized modules:
This diagram shows the routing logic from the Commander.js entry point to specialized installers, diagnostic runners, and execution orchestrators.
Sources: src/cli/AGENTS.md:7-25
Diagnostic System (Doctor)
The doctor command is a comprehensive diagnostic utility that performs 14 health checks across multiple categories to ensure the environment is correctly configured for the agent to operate.
Diagnostic Categories
| Category | Description of Checks |
|---|---|
| Installation | Verifies opencode and plugin installations |
| Configuration | Validates config files using Zod and checks model-resolution |
| Authentication | Validates API keys for Anthropic, OpenAI, and Google |
| Dependencies | Checks for required tools: ast-grep, gh-cli, etc. |
| Tools | Validates Language Server Protocol (LSP) and MCP availability |
Sources: src/cli/AGENTS.md:36-43
Execution Logic
The diagnostic runner orchestrates checks exported from src/cli/doctor/checks/index.ts. Developers can extend this system by creating new check definitions and adding them to the central registry.
Diagnostics utilize picocolors for terminal output and symbols like checkmarks (pass), crosses (fail), and warnings to provide clear feedback.
Sources: src/cli/AGENTS.md:45-56
Intelligent Analysis & Templates
The CLI supports advanced analysis commands that leverage background agents to process codebase information. These are often driven by specialized templates that define complex workflows.
/init-deep Workflow
This command generates hierarchical AGENTS.md files. It follows a multi-phase concurrent discovery process:
- Discovery: Fires background "explore" agents to find entry points, conventions, and anti-patterns.
- Scoring: Applies a scoring matrix (weights for file counts, symbol density, etc.) to decide where
AGENTS.mdfiles are needed. - Generation: Writes root and subdirectory documentation in parallel.
Sources: src/features/builtin-commands/templates/init-deep.ts:12-42
/refactor Workflow
The refactor command orchestrates a safe, deterministic transformation of code:
- Codemap Generation: Maps dependencies and "impact zones" before any edits occur.
- Test Assessment: Analyzes test coverage to determine the verification strategy (Safe vs. Aggressive).
- Step-by-Step Execution: Executes changes one atomic unit at a time, running
lsp_diagnosticsand tests after every modification.
Sources: src/features/builtin-commands/templates/refactor.ts:12-40, src/features/builtin-commands/templates/refactor.ts:167-190
Implementation Guidelines & Anti-Patterns
When contributing to the CLI or diagnostic modules, the following standards must be adhered to:
- TTY Awareness: Always check
process.stdout.isTTYbefore blocking in non-TTY environments. - Configuration Access: Use
getOpenCodeConfigPaths()from theconfig-managerrather than hardcoding paths. - Error Handling: In the doctor system, return
warnorfailstatuses instead of throwing unhandled exceptions. - JSON Parsing: Use the shared
parseJsonc()utility instead ofJSON.parseto support JSON with comments.
Sources: src/cli/AGENTS.md:58-62
Summary
The CLI and Diagnostics system provides the foundational infrastructure for OhMyOpenCode. It ensures environmental readiness through the doctor command and provides the high-level orchestration required for complex agentic workflows like deep repository initialization and safe code refactoring. By combining TUI elements with robust background agent coordination, it enables a senior-level engineering experience within a terminal environment.