OpenCode CLI Skill

Use OpenCode CLI for headless LLM automation via subprocess invocation.

Table of Contents

• •Quick Start
• •Overview
• •Basic Usage
• •Model Format
• •Configuration
• •Reference Guides
• •Subprocess Invocation
• •Limitations vs Claude CLI
• •Environment Variables
• •Verify Setup
• •Best Practices

Quick Start

1. •Install OpenCode CLI (see OpenCode documentation)
2. •Set environment variables for the provider:
   bash

   export ANTHROPIC_API_KEY="sk-..."  # For Anthropic
   # OR
   export GOOGLE_CLOUD_PROJECT="project-id"  # For Vertex AI
   

3. •Verify installation:
   bash

   opencode --version
   

4. •Test with a simple prompt:
   bash

   opencode run --model google/gemini-2.5-pro "Hello, world"
   

Overview

OpenCode is a Go-based CLI that provides access to 75+ LLM providers through a unified interface. This skill focuses on the headless run command for automation and subprocess integration.

Basic Usage

Command Format

opencode run --model <provider/model> "<prompt>"

Key points:

• •Use run subcommand for headless (non-interactive) mode
• •Model format is always provider/model
• •Prompt is a positional argument at the end
• •No stdin support (unlike Claude CLI's -p flag)

Examples

# Using Anthropic Claude
opencode run --model anthropic/claude-sonnet-4-20250514 "Explain this code"

# Using Google Gemini
opencode run --model google/gemini-2.5-pro "Review this architecture"

# Using free Grok tier
opencode run --model opencode/grok-code "Generate tests for this function"

Model Format

Models use the pattern provider/model-name:

Configuration

Config File Locations

1. •Environment variable: OPENCODE_CONFIG path
2. •Project-level: opencode.json in project root
3. •Global: ~/.config/opencode/opencode.json

Configs are merged (project overrides global).

Basic Configuration

{
  "$schema": "https://opencode.ai/config.json",
  "model": "anthropic/claude-sonnet-4-5",
  "small_model": "anthropic/claude-haiku-4-5"
}

Authentication

Credentials stored in ~/.local/share/opencode/auth.json after running /connect in TUI mode, or configure via environment variables.

Reference Guides

Load the appropriate reference for detailed configuration:

Vertex AI Setup

See vertex-ai-setup.md for Vertex AI configuration including environment variables and service account setup.

Subprocess Invocation

Basic Pattern

import subprocess

result = subprocess.run(
    ["opencode", "run", "--model", "google/gemini-2.5-pro", prompt],
    capture_output=True,
    text=True,
    timeout=600
)
output = result.stdout

Key Considerations

1. •Stagger parallel calls - Add 5-10 second delays between parallel invocations to avoid cache race conditions
2. •Implement fallback - Consider Claude CLI as fallback if OpenCode fails
3. •Health check - Use opencode --version to verify availability
4. •Timeout handling - Set appropriate timeouts (default 600s for long generations)

See integration-patterns.md for complete patterns.

Limitations vs Claude CLI

Environment Variables

Verify Setup

Complete this checklist to verify a working installation:

1. •Check version - Confirm CLI is installed:
   bash

   opencode --version
   

2. •Test default model - Verify basic connectivity:
   bash

   opencode run --model google/gemini-2.5-pro "Say hello"
   

3. •Check configuration - Review active config:
   bash

   cat ~/.config/opencode/opencode.json
   

4. •Verify MCP servers (if configured) - Test MCP connectivity by running a command that uses MCP tools

Best Practices

1. •Use project-level config - Create opencode.json for project-specific settings
2. •Prefer environment variables - Use {env:VAR_NAME} syntax in config for secrets
3. •Implement retries - Network failures are common; implement retry logic
4. •Log output - Capture both stdout and stderr for debugging
5. •Stagger parallel calls - Prevent cache race conditions with delays