From b642c1d9ea5e5100d40405705371b77d7464cbad Mon Sep 17 00:00:00 2001 From: Dax Raad Date: Wed, 16 Sep 2026 21:16:52 -0400 Subject: [PATCH] docs: add CLI settings reference --- packages/core/src/plugin/skill/opencode.md | 13 +- services/www/src/docs/content/cli/config.mdx | 451 +++++++++++++------ services/www/src/docs/content/cli/theme.mdx | 2 +- services/www/src/docs/content/index.mdx | 2 +- services/www/src/docs/content/migrate-v1.mdx | 2 +- services/www/src/docs/content/themes.mdx | 2 +- services/www/src/docs/lib/navigation.ts | 2 +- 7 files changed, 333 insertions(+), 141 deletions(-) diff --git a/packages/core/src/plugin/skill/opencode.md b/packages/core/src/plugin/skill/opencode.md index ac2da369b51..6ff909142b6 100644 --- a/packages/core/src/plugin/skill/opencode.md +++ b/packages/core/src/plugin/skill/opencode.md @@ -46,10 +46,13 @@ project-local CLI configuration. Set `OPENCODE_CLI_CONFIG_CONTENT` to merge inline JSON over the global settings. Most preferences can also be changed from the TUI by pressing `Ctrl+P` and selecting **Open settings**. -Fetch the full [CLI configuration guide](https://opencode.ai/v2/docs/cli/config) -before editing `cli.json`. It covers terminal-only settings such as themes, -keybindings, terminal plugins, scrolling, attention alerts, diff presentation, -and terminal integration. Do not put these settings in `opencode.json(c)`. +### [Settings](https://opencode.ai/v2/docs/cli/config) + +Fetch the full [CLI settings reference](https://opencode.ai/v2/docs/cli/config) +before editing `cli.json`. It documents every terminal-only setting, accepted +values, and examples, including themes, input, sessions, tabs, diffs, alerts, +Mini, keybindings, terminal plugins, and debugging. Do not put these settings +in `opencode.json(c)`. ### [Keybinds](https://opencode.ai/v2/docs/cli/keybinds) @@ -93,7 +96,7 @@ Common configuration fields include `model`, `default_agent`, `permissions`, `references`, `formatter`, and `lsp`. This configuration is distinct from `cli.json`. Use the -[CLI configuration guide](https://opencode.ai/v2/docs/cli/config) for terminal +[CLI settings reference](https://opencode.ai/v2/docs/cli/config) for terminal preferences, especially themes and keybindings. Do not guess field names or shapes. Fetch the V2 configuration guide and its diff --git a/services/www/src/docs/content/cli/config.mdx b/services/www/src/docs/content/cli/config.mdx index c0bd237c083..63c65dde522 100644 --- a/services/www/src/docs/content/cli/config.mdx +++ b/services/www/src/docs/content/cli/config.mdx @@ -1,24 +1,30 @@ --- -title: "Config" +title: "Settings" +description: "Configure every OpenCode CLI and TUI setting." --- -Most settings can also be changed from the OpenCode TUI. Press `Ctrl+P`, then select **Open settings**. +CLI settings control the terminal clients only. They are separate from the server and project settings in +`opencode.json(c)`. + +Press `Ctrl+P`, then select **Open settings** to change common settings from the TUI. OpenCode TUI settings dialog -The default CLI config location is: +## Configuration file + +OpenCode stores CLI settings in one global file: ```text ~/.config/opencode/cli.json ``` -Set `$XDG_CONFIG_HOME` to use a different config directory: +When `$XDG_CONFIG_HOME` is set, OpenCode uses: ```text $XDG_CONFIG_HOME/opencode/cli.json ``` -Add the published JSON Schema for editor validation and autocomplete: +There is no project-local CLI settings file. Add the published JSON Schema for validation and autocomplete: ```json title="cli.json" { @@ -26,7 +32,8 @@ Add the published JSON Schema for editor validation and autocomplete: } ``` -OpenCode includes this automatically when it creates or migrates your CLI config. +OpenCode adds `$schema` when it creates or migrates this file. Unknown settings are rejected, and valid edits reload +while the TUI is running. ## Inline config @@ -39,87 +46,172 @@ OPENCODE_CLI_CONFIG_CONTENT='{"tabs":{"enabled":false}}' opencode OpenCode merges the inline settings over the global `cli.json`. Nested objects are merged, while arrays and scalar values from the environment replace global values. Inline settings remain authoritative while the variable is set. -## Theme +## Appearance -Set the theme and color mode: +Choose a theme, control interface motion, and override the terminal cursor: ```json title="cli.json" { "theme": { "name": "tokyonight", "mode": "system" - } -} -``` - -| Field | Values | Description | -| ------ | ---------------------------- | ----------------------------------------------------------------- | -| `name` | string | Selects the theme. | -| `mode` | `system`, `dark`, or `light` | Selects the color mode. `system` follows the terminal appearance. | - -See [Theme](/cli/theme) for theme configuration. - -## Keybinds - -Override bindings with the top-level `keybinds` object: - -```json title="cli.json" -{ - "keybinds": { - "leader": "ctrl+x", - "app.exit": "ctrl+c,ctrl+d,q", - "app.debug": "none", - "help.show": false }, - "leader": { - "timeout": 2000 + "animations": true, + "cursor": { + "style": "block", + "blinking": true } } ``` -See [Keybinds](/cli/keybinds) for every available binding. +
-## Plugins +| Setting | Values | Description | +| ----------------- | --------------------------------------- | ------------------------------------------------------------------------ | +| `theme.name` | string | Selects a built-in, custom, or terminal-derived theme. | +| `theme.mode` | `system`, `dark`, or `light` | Follows the terminal appearance or locks the theme to one color mode. | +| `animations` | boolean | Enables interface animations. | +| `cursor.style` | `block`, `underline`, `line`, `default` | Sets the cursor shape. `default` preserves the terminal's cursor shape. | +| `cursor.blinking` | boolean | Controls cursor blinking. It has no effect when the style is `default`. | -Load terminal plugins in order: - -```json title="cli.json" -{ - "plugins": [ - "-opencode.notifications", - { - "package": "./plugins/status", - "options": { - "compact": true - } - } - ] -} -``` - -See [Plugins](/cli/plugins) for packages, local plugins, options, and enablement directives. - -## Scroll - -Set scroll speed and acceleration: +
+ +See [Theme](/cli/theme) for selecting and creating themes. + +## Input + +Configure mouse capture, scrolling, editor context, pastes, and prompt image previews: ```json title="cli.json" { + "mouse": true, "scroll": { - "speed": 2, - "acceleration": true + "speed": 3, + "acceleration": false + }, + "prompt": { + "editor": true, + "paste": "compact", + "image_preview": false } } ``` -| Field | Values | Description | -| -------------- | ------------------------ | --------------------------------- | -| `speed` | number, at least `0.001` | Sets the distance per input tick. | -| `acceleration` | boolean | Speeds up repeated scrolling. | +
-## Attention +| Setting | Values | Description | +| -------------------------- | ------------------------------- | --------------------------------------------------------------------------- | +| `mouse` | boolean | Enables terminal mouse capture. | +| `scroll.speed` | number, at least `0.001` | Sets the fixed distance per scroll input tick. | +| `scroll.acceleration` | boolean | Accelerates repeated scrolling. When enabled, it takes precedence over speed. | +| `prompt.editor` | boolean | Includes the active editor file or selection as prompt context. | +| `prompt.paste` | `compact` or `full` | Shows large pastes as compact placeholders or as full text. | +| `prompt.image_preview` | boolean | Shows image attachment previews above the prompt input. | -Configure notifications and sounds. Both are off by default and can be enabled independently: +
+ +## Sessions + +Configure how full-screen TUI sessions are presented and where new sessions start: + +```json title="cli.json" +{ + "session": { + "sidebar": "auto", + "scrollbar": false, + "thinking": "hide", + "grouping": "auto", + "image_preview": false, + "tps": true, + "markdown": "rendered", + "new_location": "launch", + "permissions": "prompt" + } +} +``` + +
+ +| Setting | Values | Description | +| ----------------------- | --------------------------- | ---------------------------------------------------------------------------- | +| `session.sidebar` | `auto` or `hide` | Shows the sidebar when space permits or always hides it. | +| `session.scrollbar` | boolean | Shows the transcript scrollbar. | +| `session.thinking` | `show` or `hide` | Shows or hides model reasoning by default. | +| `session.grouping` | `auto` or `none` | Groups related transcript items or renders each item separately. | +| `session.image_preview` | boolean | Shows user attachment and tool-result images in the transcript. | +| `session.tps` | boolean | Shows output tokens per second in assistant footers. | +| `session.markdown` | `source` or `rendered` | Shows Markdown syntax markers or conceals them in rendered content. | +| `session.new_location` | `launch` or `inherit` | Starts in the TUI launch directory or inherits the active session location. | +| `session.permissions` | `prompt` or `autoaccept` | Prompts for permission requests or accepts every request automatically. | + +
+ +## Tabs + +Configure the persistent session tab strip: + +```json title="cli.json" +{ + "tabs": { + "enabled": true, + "scope": "cwd", + "layout": "horizontal", + "indicators": "status" + } +} +``` + +
+ +| Setting | Values | Description | +| ----------------- | --------------------------- | ----------------------------------------------------------------------------- | +| `tabs.enabled` | boolean | Uses a persistent tab strip instead of pinned quick-switch sessions. | +| `tabs.scope` | `cwd` or `global` | Keeps separate tabs per working directory or shares them globally. | +| `tabs.layout` | `horizontal` or `vertical` | Places tabs in a horizontal strip or a vertical sidebar. | +| `tabs.indicators` | `status` or `numbers` | Shows status icons or always shows tab numbers. | + +
+ +Number indicators retain status colors and background animations. Ctrl+number shortcuts switch tabs in either indicator +mode. + +## Diffs + +Configure the initial diff scope and presentation: + +```json title="cli.json" +{ + "diffs": { + "source": "branch", + "wrap": "word", + "tree": true, + "single": false, + "view": "auto" + } +} +``` + +
+ +| Setting | Values | Description | +| -------------- | ----------------------------------- | ------------------------------------------------------------- | +| `diffs.source` | `branch`, `committed`, or `working` | Sets the initial review scope. | +| `diffs.wrap` | `word` or `none` | Wraps long lines at words or leaves them unwrapped. | +| `diffs.tree` | boolean | Shows the diff file tree. | +| `diffs.single` | boolean | Shows only the selected file patch. | +| `diffs.view` | `auto`, `split`, or `unified` | Sets the layout. `auto` chooses from the available width. | + +
+ +`branch` shows **All** branch and local changes, `committed` shows branch commits only, and `working` shows staged, +unstaged, and untracked changes. + +In `/diff`, press `d` to change the scope or choose a comparison branch from **Base**. These in-view choices last until +the TUI exits and do not change `cli.json`. + +## Alerts + +Enable system notifications and attention sounds independently: ```json title="cli.json" { @@ -135,73 +227,19 @@ Configure notifications and sounds. Both are off by default and can be enabled i } ``` -| Field | Values | Description | -| --------------- | ---------------------- | ---------------------------------------------------------------------------------------------------- | -| `notifications` | boolean | Shows system notifications when the terminal is not focused. | -| `sound` | boolean | Plays attention sounds. | -| `volume` | number from `0` to `1` | Sets sound volume. | -| `sound_pack` | string | Selects the active sound pack. | -| `sounds` | object | Overrides files for `default`, `question`, `permission`, `error`, `done`, or `subagent_done` events. | +
-## Session +| Setting | Values | Description | +| ------------------------ | ---------------------- | -------------------------------------------------------------------------------------------------------- | +| `attention.notifications` | boolean | Shows system notifications, normally when the terminal is not focused. | +| `attention.sound` | boolean | Plays attention sounds. | +| `attention.volume` | number from `0` to `1` | Sets sound volume. | +| `attention.sound_pack` | string | Selects the active sound pack ID. | +| `attention.sounds` | object | Overrides sound files for `default`, `question`, `permission`, `error`, `done`, or `subagent_done`. | -Choose whether the TUI prompts before granting permission requests: +
-```json title="cli.json" -{ - "session": { - "permissions": "prompt" - } -} -``` - -| Field | Values | Description | -| ------------- | ------------------------ | ----------------------------------------------------------------------- | -| `permissions` | `prompt` or `autoaccept` | Prompts for permission requests or accepts every request automatically. | - -## Diffs - -Configure diff presentation: - -```json title="cli.json" -{ - "diffs": { - "source": "branch", - "wrap": "word", - "tree": true, - "single": false, - "view": "auto" - } -} -``` - -| Field | Values | Description | -| -------- | ----------------------------------- | ------------------------------------------------------------- | -| `source` | `branch`, `committed`, or `working` | Sets the initial review scope. Defaults to `branch`. | -| `wrap` | `word` or `none` | Sets line wrapping. | -| `tree` | boolean | Shows the diff file tree. | -| `single` | boolean | Shows only the selected file patch. | -| `view` | `auto`, `split`, or `unified` | Sets the layout. `auto` chooses based on the available width. | - -`branch` shows **All** (branch and local changes), `committed` shows **Committed** (branch commits only), and `working` shows **Uncommitted** (staged, unstaged, and untracked changes). - -In `/diff`, press `d` to change the scope or choose a comparison branch from **Base**. OpenCode infers the base from local Git history when possible; otherwise it asks you to choose before loading a branch diff. - -Your base choice for each branch and last selected scope survive closing and reopening the viewer, but reset when the TUI exits. These selections do not change `cli.json`. - -## Tabs - -Choose **Tabs > Indicators** in settings, or set `tabs.indicators` in `cli.json`: - -```json title="cli.json" -{ - "tabs": { - "indicators": "numbers" - } -} -``` - -`status` (the default) shows status icons. `numbers` always shows tab numbers, retaining their status colors and background animations. Both modes work with horizontal and vertical tabs. Ctrl+number shortcuts switch tabs in either mode. +An invalid or unreadable override falls back to the built-in sound for that event. ## Terminal @@ -216,7 +254,158 @@ Configure terminal integration: } ``` -| Field | Values | Description | -| ------- | -------------------- | -------------------------------------------------------------------------------------------------------- | -| `title` | boolean | Updates the terminal window title. | -| `copy` | `manual` or `select` | Sets manual copy or copy on selection. Defaults to `select` on macOS and Linux, and `manual` on Windows. | +
+ +| Setting | Values | Description | +| ---------------- | -------------------- | -------------------------------------------------------------------------------------------------------- | +| `terminal.title` | boolean | Updates the terminal window title. | +| `terminal.copy` | `manual` or `select` | Copies manually or immediately after selection. The platform default is `manual` on Windows and `select` elsewhere. | + +
+ +## Mini + +The `mini` group controls [`opencode mini`](/cli#mini), the minimal interactive interface: + +```json title="cli.json" +{ + "mini": { + "thinking": "show", + "tools": "hide", + "shell_output": "hide", + "turn_summary": "show", + "footer": "show", + "splash": "show", + "work_spinner": "block-soft-slide", + "mono": false, + "replay": true, + "replay_limit": 200 + } +} +``` + +
+ +| Setting | Values | Description | +| ------------------- | ------------------------------ | ---------------------------------------------------------------------------------- | +| `mini.thinking` | `show` or `hide` | Shows or hides model reasoning. | +| `mini.tools` | `show` or `hide` | Shows or hides tool calls and the assistant text that precedes them. | +| `mini.shell_output` | `show` or `hide` | Shows or hides raw shell tool output. | +| `mini.turn_summary` | `show` or `hide` | Shows or hides the agent, model, and duration summary in scrollback. | +| `mini.footer` | `show` or `hide` | Shows or hides persistent activity, model, usage, and context details. | +| `mini.splash` | `show` or `hide` | Shows or hides entry and exit splash banners. | +| `mini.work_spinner` | spinner ID | Selects the work animation in the footer. | +| `mini.mono` | boolean | Uses monochrome ASCII output. | +| `mini.replay` | boolean | Restores session history on resume and terminal resize. | +| `mini.replay_limit` | positive integer | Limits replay to the newest messages. The default limit is `200`. | + +
+ +Available spinner IDs are: + +```text +block-soft-slide block-soft-sweep block-low-comet block-low-duet +block-shuttle block-bridge block-squeeze small-toggle +square-toggle grow-shrink quadrant-orbit crosshatch +density-wave seed +``` + +Command-line `mini` replay flags override these settings for that invocation. + +## Keybinds + +Override a command binding and the leader-key timeout: + +```json title="cli.json" +{ + "keybinds": { + "leader": "ctrl+x", + "app.exit": ["ctrl+c", "ctrl+d", "q"], + "prompt.paste": { + "key": "ctrl+v", + "event": "press", + "preventDefault": false, + "fallthrough": false + }, + "help.show": false + }, + "leader": { + "timeout": 2000 + } +} +``` + +
+ +| Setting | Values | Description | +| ----------------------- | ------------------------------------------------ | -------------------------------------------------------------------- | +| `keybinds.leader` | binding value | Sets the key referenced by `` in other bindings. | +| `keybinds.` | binding value | Overrides the binding for one command ID. | +| `keybinds.*.key` | key string or descriptor | Selects the key for an object binding. | +| `keybinds.*.event` | `press` or `release` | Limits an object binding to one key event. | +| `keybinds.*.preventDefault` | boolean | Controls whether the terminal's default key behavior is prevented. | +| `keybinds.*.fallthrough` | boolean | Allows lower-priority handlers to receive the same event. | +| `leader.timeout` | positive integer | Sets how many milliseconds to wait after the leader key. | + +
+ +A binding value can be a string, an array of alternatives, or an object. Use `"none"` or `false` to disable a binding. +See [Keybinds](/cli/keybinds) for accepted key syntax, every command ID, and every default binding. + +## Plugins + +Load terminal-only plugins in order: + +```json title="cli.json" +{ + "plugins": [ + "-opencode.notifications", + { + "package": "./plugins/status", + "options": { + "compact": true + } + } + ] +} +``` + +
+ +| Setting | Values | Description | +| -------------------- | --------------- | --------------------------------------------------------------- | +| `plugins` | array | Declares ordered enablement directives and external plugins. | +| `plugins[].package` | string | Sets a package name, local path, or file URL. | +| `plugins[].options` | object | Passes plugin-specific options to that plugin. | + +
+ +See [Plugins](/cli/plugins) for package forms, local discovery, wildcards, and disable directives. + +## Debug and experimental + +Enable diagnostics or opt in to a currently available experiment: + +```json title="cli.json" +{ + "debug": { + "devtools": false, + "timing": false, + "turn_tokens": "verbose" + }, + "experimental": {} +} +``` + +
+ +| Setting | Values | Description | +| ------------------- | ------------------------------- | ----------------------------------------------------------------------------------- | +| `debug.devtools` | boolean | Shows the DevTools debug bar. | +| `debug.timing` | boolean | Shows time-to-first-draw diagnostics in the debug bar. | +| `debug.turn_tokens` | boolean or `verbose` | Shows per-turn token usage; `verbose` also includes tool call inputs. | +| `experimental` | object of feature IDs to booleans | Enables or disables experiments that may change or be removed without notice. | + +
+ +Only use feature IDs currently listed by the TUI's **Experiments** dialog. Unknown IDs have no effect. diff --git a/services/www/src/docs/content/cli/theme.mdx b/services/www/src/docs/content/cli/theme.mdx index f43fccefeef..f8096c589f1 100644 --- a/services/www/src/docs/content/cli/theme.mdx +++ b/services/www/src/docs/content/cli/theme.mdx @@ -8,7 +8,7 @@ OpenCode includes built-in light and dark themes. Choose a color scheme in setti Press `Ctrl+P`, then select **Open settings** to change the theme and color mode. -You can also set them in your global [CLI config](/cli/config): +You can also set them in your global [CLI settings](/cli/config): ```json title="~/.config/opencode/cli.json" { diff --git a/services/www/src/docs/content/index.mdx b/services/www/src/docs/content/index.mdx index c0115fb51d2..3985459f896 100644 --- a/services/www/src/docs/content/index.mdx +++ b/services/www/src/docs/content/index.mdx @@ -46,4 +46,4 @@ plan that grants you access to the best open source models. Make OpenCode your own by editing the [OpenCode config](/config), [loading plugins](/plugins), [connecting MCP servers](/mcp-servers), or [creating commands](/commands). For terminal interface themes and keybindings, see [CLI -configuration](/cli/config). +settings](/cli/config). diff --git a/services/www/src/docs/content/migrate-v1.mdx b/services/www/src/docs/content/migrate-v1.mdx index 511cd0e0877..a20a9fb717f 100644 --- a/services/www/src/docs/content/migrate-v1.mdx +++ b/services/www/src/docs/content/migrate-v1.mdx @@ -524,7 +524,7 @@ V2 replaces layered V1 `tui.json(c)` files with one global terminal client confi The terminal client owns this file; the background service does not load it. When `cli.json` is absent, the first V2 terminal client startup migrates supported global `tui.json` settings and persisted preferences while leaving V1 files unchanged. Project-local client configuration is not migrated because V2 client configuration is global. See -[CLI config](/cli/config) for current client settings. +[CLI settings](/cli/config) for the current client settings reference. ## Plugins diff --git a/services/www/src/docs/content/themes.mdx b/services/www/src/docs/content/themes.mdx index 1491013b761..6720980dc53 100644 --- a/services/www/src/docs/content/themes.mdx +++ b/services/www/src/docs/content/themes.mdx @@ -15,7 +15,7 @@ set it directly in your global CLI config: ``` Themes belong to the terminal client. Put theme selection in `cli.json`, not `opencode.json`. See -[CLI config](/cli/config) for the config location and other terminal settings. +[CLI settings](/cli/config) for the config location and other terminal settings. ## Modes diff --git a/services/www/src/docs/lib/navigation.ts b/services/www/src/docs/lib/navigation.ts index a4e8bc9451f..bfb14b9a8fd 100644 --- a/services/www/src/docs/lib/navigation.ts +++ b/services/www/src/docs/lib/navigation.ts @@ -69,7 +69,7 @@ export const docsSections: DocsSection[] = [ items: [ { title: "Intro", slug: "cli" }, { title: "TUI", slug: "cli/tui" }, - { title: "Config", slug: "cli/config" }, + { title: "Settings", slug: "cli/config" }, { title: "Web", slug: "cli/web" }, { title: "Providers", slug: "cli/providers" }, { title: "Commands", slug: "cli/commands" },