# CLI KNOWLEDGE BASE

## OVERVIEW

CLI entry: `bunx oh-my-opencode`. 107+ files with Commander.js + @clack/prompts TUI.

**Commands**: install, run, doctor, get-local-version, mcp-oauth

## STRUCTURE
```
cli/
├── index.ts                 # Entry point (5 lines)
├── cli-program.ts           # Commander.js program (150+ lines, 5 commands)
├── install.ts               # TTY routing (TUI or CLI installer)
├── cli-installer.ts         # Non-interactive installer (164 lines)
├── tui-installer.ts         # Interactive TUI with @clack/prompts (140 lines)
├── config-manager/          # 17 config utilities
│   ├── add-plugin-to-opencode-config.ts  # Plugin registration
│   ├── add-provider-config.ts            # Provider setup
│   ├── detect-current-config.ts          # Project vs user config
│   ├── write-omo-config.ts               # JSONC writing
│   └── ...
├── doctor/                  # 14 health checks
│   ├── runner.ts            # Check orchestration
│   ├── formatter.ts         # Colored output
│   └── checks/              # 29 files: auth, config, dependencies, gh, lsp, mcp, opencode, plugin, version, model-resolution (6 sub-checks)
├── run/                     # Session launcher (24 files)
│   ├── runner.ts            # Run orchestration (126 lines)
│   ├── agent-resolver.ts    # Agent selection: flag → env → config → fallback
│   ├── session-resolver.ts  # Session creation or resume
│   ├── event-handlers.ts    # Event processing (125 lines)
│   ├── completion.ts        # Completion detection
│   └── poll-for-completion.ts # Polling with timeout
├── mcp-oauth/               # OAuth token management (login, logout, status)
├── get-local-version/       # Version detection + update check
├── model-fallback.ts        # Model fallback configuration
└── provider-availability.ts # Provider availability checks
```

## COMMANDS

| Command | Purpose | Key Logic |
|---------|---------|-----------|
| `install` | Interactive setup | Provider selection → config generation → plugin registration |
| `run` | Session launcher | Agent: flag → env → config → Sisyphus. Enforces todo completion. |
| `doctor` | 14 health checks | installation, config, auth, deps, tools, updates |
| `get-local-version` | Version check | Detects installed, compares with npm latest |
| `mcp-oauth` | OAuth tokens | login (PKCE flow), logout, status |

## DOCTOR CHECK CATEGORIES

| Category | Checks |
|----------|--------|
| installation | opencode, plugin |
| configuration | config validity, Zod, model-resolution (6 sub-checks) |
| authentication | anthropic, openai, google |
| dependencies | ast-grep, comment-checker, gh-cli |
| tools | LSP, MCP, MCP-OAuth |
| updates | version comparison |

## HOW TO ADD CHECK

1. Create `src/cli/doctor/checks/my-check.ts`
2. Export `getXXXCheckDefinition()` returning `CheckDefinition`
3. Add to `getAllCheckDefinitions()` in `checks/index.ts`

## ANTI-PATTERNS

- **Blocking in non-TTY**: Check `process.stdout.isTTY`
- **Direct JSON.parse**: Use `parseJsonc()` from shared
- **Silent failures**: Return `warn` or `fail` in doctor, don't throw
- **Hardcoded paths**: Use `getOpenCodeConfigPaths()` from config-manager