OpenCode CLI reference

Adds a provider to OpenCode by selecting from available providers and adding their API keys.

Compacts the current session.

Alias: /summarize. Keybind: ctrl+x c

Toggles tool execution details.

Opens an external editor (from EDITOR) for composing messages.

Keybind: ctrl+x e

Exits OpenCode.

Aliases: /quit, /q. Keybind: ctrl+x q

Exports the current conversation to Markdown and opens it in the editor set in EDITOR.

Keybind: ctrl+x x

Shows the help dialog.

Guided setup for creating or updating AGENTS.md; scans the repo and may ask targeted questions.

Lists available models.

Keybind: ctrl+x m

Starts a new session.

Alias: /clear. Keybind: ctrl+x n

Redoes a previously undone message, restoring file changes; only available after /undo and requires a Git repository.

Keybind: ctrl+x r

Lists and switches between sessions.

Aliases: /resume, /continue. Keybind: ctrl+x l

Lists available themes.

Keybind: ctrl+x t

Toggles visibility of thinking/reasoning blocks; does not change the model's reasoning (use ctrl+t to cycle variants).

Undoes the last message, removing the latest user message, subsequent responses and file changes; requires a Git repository.

Keybind: ctrl+x u

Continue the last session (opencode tui).

Short: -c.

Session ID to continue (opencode tui).

Short: -s.

Fork the session when continuing (use with --continue or --session) (opencode tui).

Prompt to use (opencode tui).

Model to use in the form of provider/model (opencode tui).

Short: -m.

Agent to use (opencode tui).

Auto-approve permissions that are not explicitly denied (opencode tui).

Port to listen on (opencode tui).

Hostname to listen on (opencode tui).

Enable mDNS discovery (opencode tui).

Custom mDNS domain name (opencode tui).

Additional browser origin(s) to allow CORS (opencode tui).

Directory to write the agent file to (opencode agent create).

Defaults to global or .opencode/agent based on the prompt.

What the agent should do (opencode agent create).

Agent mode (opencode agent create).

all, primary, or subagent

Comma-separated list of tool permissions to allow; anything omitted is denied (opencode agent create).

Default: all. Includes bash, read, edit, glob, grep, task, lsp, skill and others. Alias: --tools

Model to use, in provider/model format (opencode agent create).

Short: -m.

Working directory to start TUI in (opencode attach).

Continue the last session (opencode attach).

Short: -c.

Session ID to continue (opencode attach).

Short: -s.

Fork the session when continuing (use with --continue or --session) (opencode attach).

Basic auth password (opencode attach).

Short: -p. Defaults to OPENCODE_SERVER_PASSWORD

Basic auth username (opencode attach).

Short: -u. Defaults to OPENCODE_SERVER_USERNAME or opencode

Provider ID or name to log in to (opencode auth login).

Short: -p.

Login method label to use, skipping method selection (opencode auth login).

Short: -m.

GitHub mock event to run the agent for (opencode github run).

GitHub personal access token (opencode github run).

Refresh the models cache from models.dev (opencode models).

Use more verbose model output (includes metadata like costs) (opencode models).

The command to run, use message for args (opencode run).

Continue the last session (opencode run).

Short: -c.

Session ID to continue (opencode run).

Short: -s.

Fork the session when continuing (use with --continue or --session) (opencode run).

Model to use in the form of provider/model (opencode run).

Short: -m.

Agent to use (opencode run).

File(s) to attach to message (opencode run).

Short: -f.

Output format (opencode run).

default (formatted) or json (raw JSON events)

Title for the session (opencode run).

Uses truncated prompt if no value provided

Attach to a running opencode server (e.g., http://localhost:4096) (opencode run).

Basic auth password (opencode run).

Short: -p. Defaults to OPENCODE_SERVER_PASSWORD

Basic auth username (opencode run).

Short: -u. Defaults to OPENCODE_SERVER_USERNAME or opencode

Directory to run in, or path on the remote server when attaching (opencode run).

Port for the local server (opencode run).

Defaults to random port

Model variant (provider-specific reasoning effort) (opencode run).

Show thinking blocks (opencode run).

Auto-approve permissions that are not explicitly denied (opencode run).

Port to listen on (opencode serve).

Default: 4096 (server docs)

Hostname to listen on (opencode serve).

Default: 127.0.0.1 (server docs)

Enable mDNS discovery (opencode serve).

Default: false (server docs)

Custom mDNS domain name (opencode serve).

Default: opencode.local (server docs)

Additional browser origin(s) to allow CORS (opencode serve).

Default: [] ; can be passed multiple times (server docs)

Port to listen on (opencode web).

Hostname to listen on (opencode web).

Enable mDNS discovery (opencode web).

Custom mDNS domain name (opencode web).

Additional browser origin(s) to allow CORS (opencode web).

Working directory (opencode acp).

Port to listen on (opencode acp).

Hostname to listen on (opencode acp).

Enable mDNS discovery (opencode acp).

Custom mDNS domain name (opencode acp).

Additional browser origin(s) to allow CORS (opencode acp).

Limit to N most recent sessions (opencode session list).

Short: -n.

Output format (opencode session list).

table or json (default table)

Show stats for the last N days (opencode stats).

Default: all time

Number of tools to show (opencode stats).

Default: all

Show model usage breakdown (hidden by default); pass a number to show top N (opencode stats).

Filter by project (opencode stats).

Default: all projects; empty string: current project

Redact sensitive transcript/file data (opencode export).

Install in global config (opencode plugin).

Short: -g.

Replace existing plugin version (opencode plugin).

Short: -f.

Output format (opencode db).

json or tsv

Keep configuration files (opencode uninstall).

Short: -c.

Keep session data and snapshots (opencode uninstall).

Short: -d.

Show what would be removed without removing (opencode uninstall).

Skip confirmation prompts (opencode uninstall).

Short: -f.

The installation method that was used (opencode upgrade).

Short: -m. curl, npm, pnpm, bun, brew

Global flag: Display help.

Short: -h.

Global flag: Print version number.

Short: -v.

Global flag: Print logs to stderr.

Global flag: Log level.

DEBUG, INFO, WARN, ERROR

Global flag: Run without external plugins.

Starts the OpenCode terminal user interface (TUI), optionally for a given project directory; this is the default when run with no arguments.

Manage agents for OpenCode.

Creates a new agent with a custom system prompt and permission configuration; anything not allowed is denied in the generated agent frontmatter. Passing all of --path, --description, --mode and --permissions runs it non-interactively.

Lists all available agents.

Attaches a terminal TUI to an already running OpenCode backend server started via serve or web.

Manages credentials and login for providers.

Configures API keys for any provider from Models.dev; credentials are stored in ~/.local/share/opencode/auth.json.

Lists all authenticated providers stored in the credentials file. Alias: auth ls.

Logs out of a provider by clearing it from the credentials file.

Manages the GitHub agent for repository automation.

Installs the GitHub agent in a repository, setting up the GitHub Actions workflow and guiding configuration.

Runs the GitHub agent; typically used in GitHub Actions.

Manages Model Context Protocol servers.

Interactively adds a local or remote MCP server to the configuration.

Lists configured MCP servers and their connection status. Alias: mcp ls.

Authenticates with an OAuth-enabled MCP server; prompts for a server if no name is given. mcp auth list (or ls) lists OAuth-capable servers and their auth status.

Removes OAuth credentials for an MCP server.

Debugs OAuth connection issues for an MCP server: shows auth status, tests HTTP connectivity and attempts OAuth discovery.

Lists all models available from configured providers in provider/model format, optionally filtered by provider ID.

Runs OpenCode non-interactively by passing a prompt directly; useful for scripting and automation, and can attach to a running serve instance.

Starts a headless OpenCode HTTP server for API access without the TUI. Set OPENCODE_SERVER_PASSWORD to enable HTTP basic auth.

Manages OpenCode sessions.

Lists all OpenCode sessions.

Deletes an OpenCode session.

Shows token usage and cost statistics for OpenCode sessions.

Exports session data as JSON; prompts for a session if no ID is given.

Imports session data from a JSON file.

Starts a headless OpenCode server with a web interface and opens a browser. Set OPENCODE_SERVER_PASSWORD to enable HTTP basic auth.

Starts an ACP (Agent Client Protocol) server that communicates via stdin/stdout using nd-JSON.

Installs a plugin and updates your config. Alias: plug.

Fetches and checks out a GitHub PR branch, then runs OpenCode.

Database tools; optionally runs a query.

Prints the database path.

Debugging and troubleshooting tools. opencode debug config shows the resolved config, including managed preference keys.

Uninstalls OpenCode and removes all related files.

Updates opencode to the latest version or a specific version.

Leader key used by many keybinds (press it, then the shortcut).

Default: ctrl+x

Exit the application.

Default: ctrl+c,ctrl+d,<leader>q

List available commands.

Default: ctrl+p

Open external editor.

Default: <leader>e

List available themes.

Default: <leader>t

Toggle sidebar.

Default: <leader>b

View status.

Default: <leader>s

Export session to editor.

Default: <leader>x

Create a new session.

Default: <leader>n

List all sessions.

Default: <leader>l

Show session timeline.

Default: <leader>g

Rename session.

Default: ctrl+r

Delete session.

Default: ctrl+d

Interrupt current session.

Default: escape

Compact the session.

Default: <leader>c

Enter the first child session from the parent when subagents create child sessions.

Default: <leader>down

Cycle to the next child session.

Default: right

Cycle to the previous child session.

Default: left

Return to the parent session.

Default: up

Delete stash entry.

Default: ctrl+d

Open provider list from model dialog.

Default: ctrl+a

Toggle model favorite status.

Default: ctrl+f

List available models.

Default: <leader>m

Next recently used model.

Default: f2

Previous recently used model.

Default: shift+f2

List agents.

Default: <leader>a

Next agent.

Default: tab

Previous agent.

Default: shift+tab

Cycle model variants.

Default: ctrl+t

Scroll messages up by one page.

Default: pageup,ctrl+alt+b

Scroll messages down by one page.

Default: pagedown,ctrl+alt+f

Scroll messages up by one line.

Default: ctrl+alt+y

Scroll messages down by one line.

Default: ctrl+alt+e

Scroll messages up by half page.

Default: ctrl+alt+u

Scroll messages down by half page.

Default: ctrl+alt+d

Navigate to first message.

Default: ctrl+g,home

Navigate to last message.

Default: ctrl+alt+g,end

Copy message.

Default: <leader>y

Undo message.

Default: <leader>u

Redo message.

Default: <leader>r

Keybind for: messages toggle conceal.

Default: <leader>h

Clear input field.

Default: ctrl+c

Paste from clipboard.

Default: ctrl+v (preventDefault: false)

Submit input.

Default: return

Insert newline in input.

Default: shift+return,ctrl+return,alt+return,ctrl+j

Move cursor left in input.

Default: left,ctrl+b

Move cursor right in input.

Default: right,ctrl+f

Move cursor up in input.

Default: up

Move cursor down in input.

Default: down

Select left in input.

Default: shift+left

Select right in input.

Default: shift+right

Select up in input.

Default: shift+up

Select down in input.

Default: shift+down

Move to start of line in input.

Default: ctrl+a

Move to end of line in input.

Default: ctrl+e

Select to start of line in input.

Default: ctrl+shift+a

Select to end of line in input.

Default: ctrl+shift+e

Move to start of visual line in input.

Default: alt+a

Move to end of visual line in input.

Default: alt+e

Select to start of visual line in input.

Default: alt+shift+a

Select to end of visual line in input.

Default: alt+shift+e

Move to start of buffer in input.

Default: home

Move to end of buffer in input.

Default: end

Select to start of buffer in input.

Default: shift+home

Select to end of buffer in input.

Default: shift+end

Delete line in input.

Default: ctrl+shift+d

Delete to end of line in input.

Default: ctrl+k

Delete to start of line in input.

Default: ctrl+u

Backspace in input.

Default: backspace,shift+backspace

Delete character in input.

Default: ctrl+d,delete,shift+delete

Undo in input.

Default: ctrl+-,super+z; on Windows defaults to ctrl+z,ctrl+-,super+z

Redo in input.

Default: ctrl+.,super+shift+z

Move word forward in input.

Default: alt+f,alt+right,ctrl+right

Move word backward in input.

Default: alt+b,alt+left,ctrl+left

Select word forward in input.

Default: alt+shift+f,alt+shift+right

Select word backward in input.

Default: alt+shift+b,alt+shift+left

Delete word forward in input.

Default: alt+d,alt+delete,ctrl+delete

Delete word backward in input.

Default: ctrl+w,ctrl+backspace,alt+backspace

Select all in input.

Default: super+a

Previous history item.

Default: up

Next history item.

Default: down

Move to previous dialog item.

Default: up,ctrl+p

Move to next dialog item.

Default: down,ctrl+n

Move up one page in dialog.

Default: pageup

Move down one page in dialog.

Default: pagedown

Move to first dialog item.

Default: home

Move to last dialog item.

Default: end

Submit selected dialog item.

Default: return

Submit dialog prompt.

Default: return

Toggle MCP server.

Default: space

Move to previous autocomplete item.

Default: up,ctrl+p

Move to next autocomplete item.

Default: down,ctrl+n

Hide autocomplete.

Default: escape

Select autocomplete item.

Default: return

Complete autocomplete item.

Default: tab

Toggle permission prompt fullscreen.

Default: ctrl+f

Toggle plugin.

Default: space

Keybind for: dialog plugins install.

Default: shift+i

Suspend terminal.

Default: ctrl+z; forced to none on Windows

Toggle which-key panel.

Default: ctrl+alt+k

Switch which-key layout.

Default: ctrl+alt+shift+k

Toggle which-key pending preview.

Default: ctrl+alt+shift+p

Previous which-key group.

Default: ctrl+alt+left,ctrl+alt+[

Next which-key group.

Default: ctrl+alt+right,ctrl+alt+]

Scroll which-key up.

Default: ctrl+alt+up,ctrl+alt+p

Scroll which-key down.

Default: ctrl+alt+down,ctrl+alt+n

Page which-key up.

Default: ctrl+alt+pageup

Page which-key down.

Default: ctrl+alt+pagedown

Jump to first which-key binding.

Default: ctrl+alt+home

Jump to last which-key binding.

Default: ctrl+alt+end

Cycles through primary agents during a session (agent_cycle).

Default for agent_cycle

Cycles through model variants (actual reasoning effort), unlike /thinking which only toggles display.

Default for variant_cycle

References files in a message via fuzzy file search; configured references also appear (@alias, @alias/).

Starting a message with ! runs a shell command; output is added to the conversation as a tool result.

Opens the command palette, used for TUI customizations like username display and auto-approve permissions.

Default for command_list

IDE extension quick launch: opens OpenCode in a split terminal view or focuses an existing session (Mac / Windows-Linux).

IDE extension: starts a new OpenCode terminal session even if one is open.

IDE extension: inserts file references such as @File#L37-42.

Schema URL for editor validation/autocomplete.

https://opencode.ai/config.json

Default model in provider/model format.

string

Separate model for lightweight tasks like title generation; defaults to a cheaper provider model or falls back to the main model.

string

Provider configuration, including options and models.

object

Request timeout in ms; set false to disable.

number or false; default 300000

Timeout in ms to wait for response headers; set false to disable.

number or false; default 300000

Timeout in ms between streamed response chunks; request aborts if exceeded. Set false to disable.

number or false; default 900000

Ensures a cache key is always set for the designated provider.

boolean

Custom base URL for a provider, useful for proxies or custom endpoints.

string

Optional API key for a provider if not using auth; supports {env:...} and {file:...}.

string

Custom headers sent with each request.

object

Amazon Bedrock AWS region.

string; defaults to AWS_REGION or us-east-1

Amazon Bedrock named AWS profile.

string; defaults to AWS_PROFILE

Amazon Bedrock custom endpoint URL for VPC endpoints; alias for baseURL and takes precedence.

string

Hides the listed model IDs from the /models picker.

array of model IDs

Keeps only the listed model IDs in the /models picker.

array of model IDs

AI SDK package to use, e.g. @ai-sdk/openai-compatible for /v1/chat/completions or @ai-sdk/openai for /v1/responses.

string

Display name for a custom provider in the UI.

string

Available models for a provider, keyed by model ID.

object

Maximum input tokens the model accepts.

number

Maximum tokens the model can generate.

number

Global model options passed to the provider (e.g. reasoningEffort, thinking).

object

Custom or overridden model variants; a variant can be disabled with disabled: true.

object

Shell used for the interactive terminal and compatible agent tool calls; absolute path or short name.

string; auto-detected by OS

Enables or disables tools the LLM can use (legacy, deprecated in favor of permission); supports wildcards.

object of tool -> boolean

Server settings for opencode serve and opencode web.

object

Port to listen on.

number

Hostname to listen on; defaults to 0.0.0.0 when mdns is enabled and no hostname is set.

string

Enables mDNS service discovery.

boolean

Custom mDNS domain name.

string; default opencode.local

Additional full origins allowed for CORS.

array of origins

Options under active development; not stable.

object

Ordered policy statements allowing or denying actions on resources (currently provider.use).

array

Policy effect.

allow or deny

Operation controlled by the policy.

provider.use

Resource ID or wildcard pattern (* and ?) the statement applies to.

string

Resizes images exceeding limits before provider requests; false rejects oversized images.

boolean; default true

Maximum image width in pixels before resizing or rejection.

number; default 2000

Maximum image height in pixels before resizing or rejection.

number; default 2000

Maximum base64-encoded image payload size.

number; default 5242880

Configures built-in or custom agents by name.

object

Default primary agent when none is specified; falls back to build with a warning if missing or a subagent.

string; e.g. build or plan

How deeply subagents can invoke other subagents; 0 prevents all subagent launches.

number; default 1

Custom commands for repetitive tasks.

object

Enables snapshots used to undo/revert agent file changes; disabling avoids slow indexing in large repos.

boolean; default true

Automatic update downloads at startup; notify only shows when a new version is available (not for package-manager installs).

true, false, or "notify"

Enables and configures code formatters; omit to keep formatters disabled.

true, false, or object

Enables and configures LSP servers; omit to keep LSP disabled.

true, false, or object

Controls whether actions run automatically, prompt, or are blocked; can be a single action or per-tool rules.

allow, ask, deny, or object

Automatically compacts the session when context is full.

boolean; default true

Removes old tool outputs to save tokens.

boolean; default false

Token buffer for compaction to avoid overflow during compaction.

number

Glob patterns ignored by the file watcher; common dependency, VCS, build and cache dirs are ignored automatically.

array of globs

MCP server definitions keyed by name.

object

npm plugins to load.

array of package names

Paths, glob patterns or remote URLs of instruction files combined with AGENTS.md; remote URLs use a 5 second timeout.

array of strings

Provider IDs that won't be loaded even if credentials exist; takes priority over enabled_providers.

array of provider IDs

Allowlist of provider IDs; all others are ignored.

array of provider IDs

Local directories or Git repositories made available as project references by alias.

object

Local reference directory (relative to config, absolute, or ~).

string

Git URL, host/path, or GitHub owner/repo reference, materialized in the local repository cache.

string

Optional Git branch or ref; defaults to the repository's default branch.

string

Guidance describing when agents should use the reference; references with descriptions are included in agent context.

string

Hides the reference from TUI @ autocomplete only.

boolean

Brief description of what the agent does and when to use it; required.

string

Randomness of responses; defaults are model-specific (typically 0, 0.55 for Qwen).

number, typically 0.0-1.0

Maximum agentic iterations before the agent must respond with text only (legacy maxSteps is deprecated).

number

Set true to disable the agent.

boolean

Custom system prompt file, relative to the config file.

string, e.g. {file:./prompts/build.txt}

Overrides the model for this agent in provider/model-id format.

string

Deprecated per-agent tool toggles; true equals {"*": "allow"} and false equals {"*": "deny"}.

object

Per-agent permission overrides merged with global config.

object

How the agent can be used.

primary, subagent, or all; default all

Hides a subagent from @ autocomplete; it can still be invoked via the Task tool.

boolean

Glob rules controlling which subagents an agent can invoke via the Task tool; last matching rule wins.

object of glob -> allow/ask/deny

Agent color in the UI.

hex color or primary, secondary, accent, success, warning, error, info

Response diversity, alternative to temperature.

number 0.0-1.0

Prompt sent to the LLM when the command runs; supports $ARGUMENTS, $1..$n, !cmd and @file; required.

string

Description shown in the TUI.

string

Agent that executes the command; a subagent triggers a subagent invocation by default.

string; defaults to current agent

Forces the command to run as a subagent invocation.

boolean

Overrides the default model for this command.

string

Catch-all permission rule.

allow, ask, deny

Reading a file (matches the file path); .env files denied by default.

allow, ask, deny or object; default allow

All file modifications (edit, write, patch, apply_patch).

allow, ask, deny or object

File globbing (matches the glob pattern).

allow, ask, deny or object

Content search (matches the regex pattern).

allow, ask, deny or object

Listing files.

allow, ask, deny or object

Running shell commands (matches parsed commands).

allow, ask, deny or object

Launching subagents (matches the subagent type).

allow, ask, deny or object

Loading a skill (matches the skill name).

allow, ask, deny or object

Running LSP queries (currently non-granular).

allow, ask, deny or object

Asking the user questions during execution.

allow, ask, deny

Fetching a URL (matches the URL).

allow, ask, deny

Triggered when a tool touches paths outside the project working directory.

allow, ask, deny or object; default ask

Triggered when the same tool call repeats 3 times with identical input.

allow, ask, deny; default ask

Disables the LSP server.

boolean

Command to start the LSP server; required unless only disabling.

string[]

File extensions the LSP server handles.

string[]

Environment variables set when starting the server.

object

Initialization options sent in the LSP initialize request.

object

Disables the formatter.

boolean

Formatting command; $FILE is replaced with the file path. Required for custom formatters.

string[]

Environment variables set when running the formatter.

object

File extensions the formatter handles.

string[]

MCP connection type.

"local" or "remote"; required

Command and arguments to run a local MCP server.

array; required for local

Working directory for a local MCP server process; relative paths resolve from the workspace.

string

Environment variables for a local MCP server.

object

Enables or disables the MCP server on startup.

boolean

Timeout in ms for fetching tools from the MCP server.

number; default 5000

URL of a remote MCP server.

string; required for remote

Headers sent to a remote MCP server.

object

OAuth config for a remote server, or false to disable OAuth auto-detection.

object or false

OAuth client ID; dynamic client registration is attempted if omitted.

string

OAuth client secret, if required.

string

OAuth scopes to request.

string

tui.json: Sets the UI theme.

string; default opencode

tui.json: Customizes keyboard shortcuts; merged with built-in defaults.

object

tui.json: How long OpenCode waits after the leader key, in ms.

number; default 2000

tui.json: macOS-style scroll acceleration; overrides scroll_speed when enabled.

boolean

tui.json: TUI scroll speed; ignored when scroll_acceleration is enabled.

number, minimum 0.001; default 3

tui.json: Diff rendering.

"auto" or "stacked"

tui.json: Terminal cursor style in input fields; default restores the terminal cursor.

block, underline, line, default; default block

tui.json: Cursor blinking; no effect when style is default.

boolean; default true

tui.json: Mouse capture in the TUI.

boolean; default true

tui.json: Enables all attention notifications and sounds.

boolean; default false

tui.json: Allows terminal-mediated desktop notifications.

boolean; default true

tui.json: Allows attention sounds.

boolean; default true

tui.json: Default sound volume.

number 0-1; default 0.4

tui.json: Sound pack ID.

string; default opencode.default

tui.json: Overrides sound files for default, question, permission, error, done, or subagent_done.

object of paths

SKILL.md frontmatter: Skill name; 1-64 lowercase alphanumeric chars with single hyphens, matching the directory name. Required.

^[a-z0-9]+(-[a-z0-9]+)*$

SKILL.md frontmatter: Skill description; required.

1-1024 characters

SKILL.md frontmatter: Optional license field.

string

SKILL.md frontmatter: Optional compatibility field.

string

SKILL.md frontmatter: Optional string-to-string map for tool-specific behavior.

map

SKILL.md frontmatter: Exposes the skill as a /name command in the TUI.

"true"

SKILL.md frontmatter: Set false to keep the skill out of model-facing auto-selection guidance.

"false"

GitHub Action input: model in provider/model format; required.

string

GitHub Action input: primary agent to use; falls back to default_agent or build.

string

GitHub Action input: custom prompt overriding default behavior; required for issues, schedule and workflow_dispatch events.

string

GitHub Action input: comma-separated case-insensitive trigger phrases.

default /opencode,/oc

GitHub Action input: model variant for provider-specific reasoning effort.

e.g. high, max, minimal

GitHub Action input: base URL for the OIDC token exchange API, for custom GitHub App installs.

default https://api.opencode.ai

GitHub Action input: use a caller-provided GITHUB_TOKEN instead of an OIDC-exchanged app token.

boolean; default false

Advanced keybind value: an object with key, event, preventDefault, or fallthrough; strings may hold comma-separated shortcuts and arrays hold alternatives.

string, array, or object

Path to Git Bash executable on Windows.

string

Path to config file; loaded between global and project configs.

string

Path to TUI config file.

string

Path to a config directory searched for agents, commands, modes and plugins like a .opencode directory.

string

Inline JSON config content, applied as runtime overrides.

string

Disable automatic update checks.

boolean

Disable pruning of old data.

boolean

Disable automatic terminal title updates.

boolean

Inlined JSON permissions config.

string

Disable default plugins.

boolean

Disable automatic LSP server downloads.

boolean

Enable experimental models.

boolean

Disable automatic context compaction.

boolean

Disable reading from .claude (prompt + skills).

boolean

Disable reading ~/.claude/CLAUDE.md.

boolean

Disable loading .claude/skills.

boolean

Disable fetching models from remote sources.

boolean

Disable mouse capture in the TUI.

boolean

Fake VCS provider for testing purposes.

string

Client identifier.

string. Default: cli

Enable HTTP basic auth for serve/web.

string

Override basic auth username.

string. Default: opencode

Custom URL for fetching models configuration.

string

Experimental (may change or be removed): Enable the experimental umbrella flag.

boolean

Experimental (may change or be removed): Enable icon discovery.

boolean

Experimental (may change or be removed): Disable copy on select in TUI.

boolean

Experimental (may change or be removed): Default timeout for bash commands in ms.

number

Experimental (may change or be removed): Max output tokens for LLM responses.

number

Experimental (may change or be removed): Enable file watcher for entire dir.

boolean

Experimental (may change or be removed): Enable oxfmt formatter.

boolean

Experimental (may change or be removed): Enable experimental LSP tool.

boolean

Experimental (may change or be removed): Disable file watcher.

boolean

Experimental (may change or be removed): Enable TY LSP for python files.

boolean

Experimental (may change or be removed): Enable plan mode.

boolean

Experimental (may change or be removed): Enable experimental event system.

boolean

Experimental (may change or be removed): Enable native LLM request path.

boolean

Experimental (may change or be removed): Enable Scout subagent.

boolean

Experimental (may change or be removed): Enable workspace support.

boolean

Editor used by the /editor and /export TUI commands; GUI editors such as VS Code need --wait.

string

Standard HTTPS proxy variable respected by OpenCode (recommended); basic auth credentials can be included in the URL.

URL

Standard HTTP proxy variable respected by OpenCode, used if HTTPS is not available.

URL

Bypass list for the proxy; required for localhost because the TUI talks to a local HTTP server.

comma-separated hosts

Path to a custom CA certificate for enterprise HTTPS; works for proxy connections and direct API access.

path to PEM

If set, OpenCode Desktop tries to use this port for its local server; unset it or pick a free port to fix connection issues.

number

Launch OpenCode Desktop with this set to 1 to work around blank windows or crashes on some Linux Wayland setups.

1

Set to truecolor to enable 24-bit color so themes display their full palette.

truecolor or 24bit

When set, user themes are also read from $XDG_CONFIG_HOME/opencode/themes/*.json.

path

Anthropic API key; can be referenced in config via {env:ANTHROPIC_API_KEY} or set in the GitHub Action env.

string

Project config file in the project root (JSON or JSONC); OpenCode looks in the current directory then traverses up to the nearest Git directory.

JSONC (JSON with Comments) form of the OpenCode config file.

Global config for user-wide server/runtime preferences like providers, models and permissions.

Global TUI-specific settings file (also tui.jsonc); project tui.json can sit alongside opencode.json.

TUI config file (or tui.jsonc) for theme, keybinds, scrolling, cursor, mouse and attention settings, separate from opencode.json.

Remote organizational config endpoint fetched when authenticating with a supporting provider; loaded first as the base layer.

macOS managed config directory for an admin-controlled opencode.json or opencode.jsonc at highest priority.

Linux managed config directory for admin-controlled opencode.json or opencode.jsonc.

Windows managed config directory for admin-controlled opencode.json or opencode.jsonc.

macOS per-user managed preferences (ai.opencode.managed domain via MDM .mobileconfig); plist keys map to opencode.json fields.

macOS machine-wide managed preferences for the ai.opencode.managed domain.

Project directory for agents/, commands/, modes/, plugins/, skills/, tools/ and themes/ (plural names; singular also supported).

Credentials file for provider API keys and OAuth tokens added via /connect or opencode auth login.

Where OAuth tokens for MCP servers are stored after opencode mcp auth.

Application data directory (sessions, auth.json, log/, project/). Windows: %USERPROFILE%\.local\share\opencode.

Log directory; files are timestamped and the most recent 10 are kept.

Cache directory including provider packages and npm plugins (node_modules); can be deleted to force reinstall.

Project rules file with custom instructions included in the LLM context; created or updated by /init.

Global rules applied across all opencode sessions.

Claude Code compatible project rules fallback, used if no AGENTS.md exists.

Claude Code compatible global rules fallback, used if no ~/.config/opencode/AGENTS.md exists.

Per-project markdown agent definitions; file name becomes the agent name. Global: ~/.config/opencode/agents/.

Per-project markdown custom commands; file name becomes the command name. Global: ~/.config/opencode/commands/.

Project skill location; also ~/.config/opencode/skills, .claude/skills, ~/.claude/skills, .agents/skills and ~/.agents/skills.

Project-level plugin directory; global plugins live in ~/.config/opencode/plugins/.

Declares npm dependencies for local plugins and custom tools; OpenCode runs bun install at startup.

Project custom tool definitions; global custom tools go in ~/.config/opencode/tools/.

User custom theme directory; project themes go in .opencode/themes/*.json.

File in the project root that re-includes paths ignored by .gitignore for ripgrep-based tools like grep and glob.

GitHub Actions workflow file for the OpenCode GitHub agent.

File containing only a PHP Intelephense license key for premium features (Windows: %USERPROFILE%/intelephense/license.txt).