CLI Reference

Command Quick Reference

Command	Purpose
`opencode tui`	Start the terminal user interface
`opencode run`	Execute a prompt programmatically
`opencode serve`	Start a headless backend server
`opencode web`	Start a backend server with web interface
`opencode attach`	Attach to a running backend server
`opencode auth`	Manage AI provider credentials
`opencode models`	List available AI models
`opencode session`	Manage conversation sessions
`opencode github`	Manage GitHub agent
`opencode pr`	Fetch and checkout a GitHub PR
`opencode export`	Export conversation data
`opencode import`	Import data
`opencode stats`	Display usage statistics
`opencode init`	Initialize project and create AGENTS.md

Core Interaction Commands

opencode tui

Start the OpenCode Terminal User Interface (TUI). This is the default behavior when running opencode without any arguments.

Syntax

opencode tui [options]

Examples

# Start TUI in current directory
opencode tui

# Start TUI (default behavior)
opencode

Use Cases

Interactive development: Daily coding tasks with AI assistance
Project exploration: Navigate and understand unfamiliar codebases
Real-time collaboration: Work with AI on complex problems

opencode run

Execute a prompt programmatically without entering the TUI. Ideal for scripting and automation.

Syntax

opencode run "<prompt>" [options]

Examples

# Execute a single prompt
opencode run "Explain how closures work in JavaScript"

# Use with a specific model
opencode run "Refactor this function" --model anthropic/claude-3.5-sonnet

# Continue from previous session
opencode run "Continue the refactoring" --continue

Use Cases

CI/CD integration: Automated code reviews and suggestions
Batch processing: Process multiple prompts in scripts
Quick queries: Get instant answers without opening TUI

opencode serve

Start a headless OpenCode backend server that provides API access without a terminal interface.

Syntax

opencode serve [options]

Examples

# Start backend server
opencode serve

# Start server on custom port
opencode serve --port 4096

Use Cases

Remote access: Run OpenCode on a server, connect from clients
Team collaboration: Share a single OpenCode instance
Integration: Build custom frontends or tools

opencode web

Start a backend server with a web interface, allowing browser-based access to OpenCode.

Syntax

opencode web [options]

Options

Option	Description
`--port`	Port to listen on (default: varies)
`--hostname`	Hostname to bind to

Examples

# Start web server
opencode web

# Start on specific port and hostname
opencode web --port 4096 --hostname 0.0.0.0

# Allow external access
opencode web --hostname 0.0.0.0

Use Cases

Mobile access: Use OpenCode from tablets or phones
Browser preference: Work in a web UI instead of terminal
Screen sharing: Easier to share during pair programming

opencode attach

Attach a terminal to an already running OpenCode backend server (started via serve or web).

Syntax

opencode attach [url] [options]

Options

Option	Description
`--dir`	Working directory to start TUI in
`--session`, `-s`	Session ID to continue

Examples

# Attach to remote server
opencode attach http://10.20.30.40:4096

# Attach and specify working directory
opencode attach http://server:4096 --dir /path/to/project

# Attach and continue specific session
opencode attach http://server:4096 --session abc123

Use Cases

Remote development: Connect to OpenCode running on powerful servers
Session sharing: Multiple users attach to same backend
Reconnection: Resume work after network interruption

Authentication Management

opencode auth

Manage credentials and authentication for AI providers.

Syntax

opencode auth [command]

Subcommands

Configure API keys for AI providers supported by Models.dev. Credentials are stored in ~/.local/share/opencode/auth.json.

Examples

# Start interactive authentication
opencode auth login

# Authenticate with a specific provider
opencode auth login --provider anthropic

Use Cases

Initial setup: Configure OpenCode for first-time use
Provider switching: Add new AI provider credentials
Key rotation: Update API keys for security

Model Management

opencode models

List all available models from configured providers. Models are displayed in provider/model format.

Syntax

opencode models [provider]

Examples

# List all available models
opencode models

# List models from specific provider
opencode models anthropic

# Use with grep to filter
opencode models | grep claude

Use Cases

Model discovery: Find available models for your use case
Provider comparison: See what each provider offers
Configuration: Get exact model names for config files

Session Management

opencode session

Manage conversation sessions.

Syntax

opencode session [command]

Use Cases

Session history: Review past conversations
Context switching: Jump between different projects
Session cleanup: Archive or delete old sessions

GitHub Integration

opencode github

Manage the GitHub agent for OpenCode, which enables AI-powered GitHub workflow automation.

Syntax

opencode github [command]

Subcommands

opencode github install

Install and configure the GitHub agent for your repository or organization.

Examples

# Install GitHub agent
opencode github install

Use Cases

Repository automation: Set up AI assistance for GitHub workflows
Team onboarding: Enable AI code reviews for your team
CI/CD integration: Integrate OpenCode into GitHub Actions

opencode github run

Run the GitHub agent to process events and automation tasks.

Examples

# Run GitHub agent
opencode github run

Use Cases

Automated reviews: Process pull requests with AI assistance
Issue triage: Automatically analyze and categorize issues
Continuous assistance: Keep the agent running for ongoing tasks

opencode pr

Fetch and checkout a GitHub pull request branch, then start OpenCode in that context. This streamlines the code review workflow.

Syntax

opencode pr <number> [options]

Examples

# Checkout PR #42 and start OpenCode
opencode pr 42

# Review a PR with a specific model
opencode pr 123 --model anthropic/claude-3.5-sonnet

Use Cases

Code reviews: Quickly jump into PR context for review
PR assistance: Get AI help understanding changes
Collaboration: Discuss PR changes with AI before commenting

Project Initialization

opencode init

Initialize a project by creating or updating an AGENTS.md file that helps OpenCode understand your project structure.

Syntax

opencode init

Examples

# Initialize current project
opencode init

# Run from within TUI
/init

Use Cases

New projects: Set up OpenCode for a new codebase
Project updates: Update AGENTS.md when structure changes
Context optimization: Help AI understand your project better

Data Operations

opencode export

Export conversation data.

Syntax

opencode export [options]

Use Cases

Documentation: Save conversations for reference
Backup: Archive important interactions
Sharing: Export conversations to share with colleagues

opencode import

Import data into OpenCode.

Syntax

opencode import [options]

Use Cases

Migration: Move data between OpenCode instances
Restoration: Restore from backups
Team sync: Import shared conversation history

opencode stats

Display usage statistics.

Syntax

opencode stats

Use Cases

Cost tracking: Monitor API usage and costs
Usage analysis: Understand your interaction patterns
Budget management: Stay within spending limits

Global Flags

These flags can be used with most OpenCode commands to modify their behavior.

Flag	Short	Description
`--continue`	`-c`	Continue from the last session
`--session`	`-s`	Specify a session ID to continue
`--prompt`	-	Define the prompt to use
`--model`	`-m`	Specify the model (format: `provider/model`)
`--agent`	-	Specify the agent to use
`--port`	-	Define the port to listen on
`--hostname`	-	Define the hostname to listen on

Examples

# Continue last session
opencode --continue

# Use specific model
opencode run "Explain this code" --model anthropic/claude-3.5-sonnet

# Start on custom port
opencode web --port 8080