OpenCode Cheat Sheet: CLI Commands, Shortcuts & Config

OpenCode is an open-source AI coding agent with a terminal interface, desktop app, and editor extensions.

This cheat sheet covers the CLI commands, TUI slash commands, keyboard shortcuts, configuration options, agents, permissions, MCP servers, Skills, and automation workflows you’ll most likely look up while using OpenCode.

Last updated: September 14, 2026.

OpenCode quick reference

Input syntax

Common tasks

OpenCode CLI commands

Start the TUI

opencode --continue
opencode --session ses_123 --fork
opencode --model anthropic/claude-sonnet-4-5 --agent plan
opencode --auto

Authentication

Models

Model IDs use the provider/model-id format.

Run a prompt from the shell

opencode run executes a prompt without opening the TUI.

opencode run "Explain the authentication flow"
opencode run -f src/auth.ts "Review this file for security issues"
opencode run --format json "List the failing tests"
opencode run --agent plan "Review the changed files"

Sessions

MCP

Agents

opencode agent create opens the agent wizard. opencode agent list shows the available agents.

opencode agent create
opencode agent list

Other useful CLI commands

TUI slash commands

Type / in the prompt to open command autocomplete.

Essential keyboard shortcuts

The default leader key is ctrl+x. Press the leader first, then the second key.

Install and update

opencode --version
opencode upgrade
opencode upgrade --method npm

Sessions, files, and context

Session lifecycle

Files and attachments

Use @ to fuzzy-search project files from the TUI.

Explain the error handling in @src/api/index.ts
Compare @package.json with @docs/architecture.md

Attach files to a shell run with repeated --file flags:

opencode run --file src/api/index.ts --file tests/api.test.ts "Review this change"

Undo and redo

/undo removes the latest user message, responses, and associated file changes. /redo restores an undone turn. File rollback uses Git-backed snapshots, so the project must be a Git repository.

Configuration

OpenCode accepts JSON and JSONC. Project configuration normally lives in opencode.json. User-wide configuration lives at ~/.config/opencode/opencode.json. TUI appearance and keybind settings use tui.json.

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

Common config locations

Common config keys

Environment and file substitutions

Use {env:NAME} to load an environment variable and {file:path} to load file contents into config.

{
  "$schema": "https://opencode.ai/config.json",
  "model": "{env:OPENCODE_MODEL}",
  "instructions": ["{file:./instructions.md}"],
  "provider": {
    "openai": {
      "options": {
        "apiKey": "{env:OPENAI_API_KEY}"
      }
    }
  }
}

Models and providers

Use /models in the TUI or opencode models in the shell. Model names use the provider/model-id format.

opencode models
opencode models anthropic
opencode models --refresh
opencode --model openai/gpt-5
opencode run --model openai/gpt-5 "Review the error boundary"

Agents

OpenCode has primary agents for the main conversation and subagents for delegated work.

Cycle primary agents with Tab and Shift+Tab. Invoke a subagent with @name.

@explore Find every route that writes to the users table
@general Review the migration plan and list unresolved risks

Create a custom agent

Run the wizard:

opencode agent create

Project agents can also live in .opencode/agents/ as Markdown files:

---
description: Review code without edits
mode: subagent
model: anthropic/claude-sonnet-4-5
permission:
  edit: deny
  bash: ask
---
Inspect the code and report defects, edge cases, and missing tests.

Permissions

Permission rules use three values:

Common permission keys include read, edit, bash, task, external_directory, webfetch, websearch, and skill.

{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "bash": {
      "*": "ask",
      "git status *": "allow",
      "git push *": "deny"
    },
    "edit": {
      "*": "deny",
      "src/**": "allow"
    }
  }
}

Rules are evaluated in order, and the last matching rule wins. --auto approves actions that would otherwise ask for permission. Explicit deny rules continue to block the action.

Project instructions, custom commands, and Skills

Project instructions

AGENTS.md stores project instructions. Run /init to create or update it.

The instructions config can load additional files:

{
  "$schema": "https://opencode.ai/config.json",
  "instructions": [
    "CONTRIBUTING.md",
    "docs/guidelines.md",
    ".cursor/rules/*.md"
  ]
}

Custom commands

Store project commands in .opencode/commands/ and global commands in ~/.config/opencode/commands/. The filename becomes the slash command name.

---
description: Run tests and explain failures
agent: build
---
Run the test suite. Report each failure with its file, root cause, and a focused fix.

Run this file as /test.

Useful substitutions:

Agent Skills

Project Skills live in .opencode/skills/<name>/SKILL.md. Global Skills live in ~/.config/opencode/skills/<name>/SKILL.md. OpenCode can also discover compatible Skills under .claude/skills/ and .agents/skills/.

---
name: git-release
description: Create consistent releases and changelogs
---
Draft release notes from merged pull requests and propose a version bump.

MCP servers

OpenCode can connect to local process MCP servers and remote HTTP MCP servers.

Manage MCP servers

opencode mcp add
opencode mcp list
opencode mcp auth my-server
opencode mcp logout my-server
opencode mcp debug my-server

Local MCP server

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "local-tools": {
      "type": "local",
      "command": ["npx", "-y", "my-mcp-command"],
      "environment": {
        "MY_API_KEY": "{env:MY_API_KEY}"
      },
      "enabled": true
    }
  }
}

Remote MCP server

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "remote-tools": {
      "type": "remote",
      "url": "https://mcp.example.com/mcp",
      "enabled": true,
      "headers": {
        "Authorization": "Bearer {env:MY_API_KEY}"
      }
    }
  }
}

Automation and remote use

One-off and CI runs

opencode run "Explain this repository"
opencode run --agent plan --format json "Review the changed files"
opencode run --file src/api.ts "Review this API change"

Persistent backend

Start a backend:

opencode serve --port 4096 --hostname 127.0.0.1

Send a run to it:

opencode run --attach http://127.0.0.1:4096 "Run the focused test suite"

Attach a TUI:

opencode attach http://127.0.0.1:4096

Set OPENCODE_SERVER_PASSWORD when the backend needs HTTP basic authentication.

Common environment variables

Troubleshooting

opencode is not recognized

Open a new shell and run opencode --version. Check that the installation directory is on PATH.

Provider or model is missing

Run:

opencode auth list
opencode models --refresh

Check the exact provider/model-id spelling and review enabled_providers or disabled_providers if the provider is absent.

A TUI command fails in a shell

Slash commands run inside the TUI. Use their CLI equivalents from the shell. For example, use opencode models in place of /models and opencode session list in place of /sessions.

A permission prompt blocks a tool

Run:

opencode debug config

Check the global permission rule, agent-specific rules, and later matching patterns. The last matching rule wins.

Undo does not restore files

Confirm that the project is a Git repository and snapshots are enabled.

An MCP server is disconnected

Run:

opencode mcp list
opencode mcp debug <name>

Check the command or URL, environment variables, timeout, and authentication status.

The context becomes too large

Use /compact or ctrl+x c. Disable MCP servers that are not needed for the current task and avoid attaching large unrelated files.

FAQs

What is the difference between Build and Plan?

Build is the primary development agent. Plan focuses on analysis and planning, with file edits and shell commands requiring approval by default.

Does --auto override denied permissions?

No. --auto approves permission requests that would normally ask. Explicit deny rules continue to block the action.

What is the difference between a custom command and an Agent Skill?

A custom command creates a slash command for a repeatable prompt. An Agent Skill stores reusable instructions that an agent can load through the native Skill system.

What does /thinking do?

It shows or hides thinking blocks from models that provide them. It does not change the model’s reasoning capability. Use ctrl+t to cycle provider-specific model variants.

Official OpenCode resources

• OpenCode official website
• OpenCode documentation
• OpenCode CLI documentation
• OpenCode GitHub repository

Related resources

• Claude Code Commands Cheat Sheet
• OpenAI Codex Commands Cheat Sheet
• Most Popular Agent Skills on GitHub for Coding Agents