docs: restructure and rewrite all documentation from scratch
Consolidate 12 docs into 8, eliminating ~70% duplicate content. Fix all broken doc links across 4 README translations. New structure: - docs/guide/: overview, installation (with agent-model setup), orchestration - docs/reference/: features, configuration, cli - docs/manifesto.md, docs/troubleshooting/ollama.md Deleted: agent-model-matching, understanding-orchestration-system, orchestration-guide, category-skill-guide, task-system, cli-guide, configurations, ultrawork-manifesto, features, ollama-streaming-issue
This commit is contained in:
YeonGyu-Kim
@@ -0,0 +1,315 @@
|
||||
# CLI Reference
|
||||
|
||||
Complete reference for the `oh-my-opencode` command-line interface.
|
||||
|
||||
## Basic Usage
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```bash
|
||||
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
|
||||
|
||||
```bash
|
||||
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
|
||||
|
||||
```bash
|
||||
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
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```bash
|
||||
# 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.
|
||||
|
||||
```jsonc
|
||||
{
|
||||
// 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
|
||||
|
||||
```bash
|
||||
# Update OpenCode
|
||||
npm install -g opencode@latest
|
||||
# or
|
||||
bun install -g opencode@latest
|
||||
```
|
||||
|
||||
### "Plugin not registered" Error
|
||||
|
||||
```bash
|
||||
# Reinstall plugin
|
||||
bunx oh-my-opencode install
|
||||
```
|
||||
|
||||
### Doctor Check Failures
|
||||
|
||||
```bash
|
||||
# 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.
|
||||
|
||||
```bash
|
||||
# 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`:
|
||||
|
||||
```typescript
|
||||
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`:
|
||||
|
||||
```typescript
|
||||
export { myCheck } from "./my-check"
|
||||
```
|
||||
Reference in New Issue
Block a user