#Config & CLI Reference

This chapter summarizes opencode.json, environment variables, and common CLI commands.

#Config Files

Environment variables:

#opencode.json Overview

{
  "$schema": "https://opencode.ai/config.json",
  "model": "anthropic/claude-sonnet-4-6",
  "provider": {},
  "agent": {},
  "permission": {},
  "mcp": {},
  "lsp": {},
  "instructions": []
}

#model and provider

• model: default provider/model-id string
• provider: per-vendor endpoint, apiKey references, etc.
• TUI /connect avoids committing secrets to the repo

#instructions

String array appended to system prompt (like global rules):

{
  "instructions": [
    "Always reply in English",
    "Run relevant tests before editing"
  ]
}

#Common CLI

#Install and update

# Official install script (see opencode.ai)
curl -fsSL https://opencode.ai/install | bash

# Or package managers
npm i -g opencode-ai
# brew install opencode, etc.

#Interactive TUI

cd your-project
opencode

#Non-interactive run

opencode run "Add an installation section to README"

Good for scripts and CI helpers—mind permissions and API cost.

#Headless

opencode serve          # API
opencode web            # Web UI
opencode acp            # Agent Client Protocol

#Agent management

opencode agent create
opencode agent list

#Other

opencode --help
opencode version

Subcommands evolve quickly—trust local opencode --help.

#TUI Slash Commands (common)

Custom commands live in .opencode/commands/*.md.

#Custom Slash Commands

.opencode/commands/test-and-fix.md:

---
description: Run tests and fix failures
---

Run the project test command (see AGENTS.md). Fix failures one by one and re-run until green.

Type /test-and-fix in TUI to inject that prompt template.

#OpenCode Zen

Zen is OpenCode’s curated model list (optimized routing). See the site or TUI /connect for current models and pricing.

#75+ Providers

OpenCode supports Anthropic, OpenAI, Google, local Ollama, OpenRouter, and more:

• API key env vars
• Custom baseURL (OpenAI-compatible gateways)
• Local models without cloud

Team tip: Pin model in opencode.json so members do not accidentally use expensive models.

#Git Workflow

• Commit opencode.json (no secrets) and AGENTS.md
• Do not commit API keys—use env vars or global config
• Optionally .gitignore .opencode/cache and local caches

#Next Steps

• Practical Examples
• Resources