OpenCode CLI & TUI Usage

OpenCode CLI & TUI Complete Usage Guide

A comprehensive guide covering keyboard shortcuts, interface modes, configuration, and best practices for the OpenCode interactive CLI/TUI agent.

1. Core UI Navigation & Keybinds

OpenCode uses a Leader Key system to avoid conflicts with terminal or shell shortcuts.

Default Leader Key: Ctrl+X
Leader Timeout: 2000 ms (press <leader> then the command key within 2 seconds).

Interface & Display Controls

Action	Default Shortcut	Config Key	Description
Toggle Sidebar	`<leader> b` (`Ctrl+X` then `b`)	`sidebar_toggle`	Hides/shows the right info sidebar box.
Open Command Palette	`Ctrl+P`	`command_list`	Opens prompt command list for quick actions.
Toggle Tips	`<leader> h`	`tips_toggle`	Toggle onscreen contextual tips.
Exit OpenCode	`Ctrl+C`, `Ctrl+D`, or `<leader> q`	`app_exit`	Quit the application session.
Suspend Terminal	`Ctrl+Z`	`terminal_suspend`	Suspend process to background (POSIX shells).
Which-Key Popup	`Ctrl+Alt+K`	`which_key_toggle`	Display interactive keybind map.

Session Management

Action	Shortcut	Config Key	Description
New Session	`<leader> n`	`session_new`	Start a fresh agent chat session.
List Sessions	`<leader> l`	`session_list`	Open interactive session picker.
Session Timeline	`<leader> g`	`session_timeline`	View session branching and event history.
Export Session	`<leader> x`	`session_export`	Export session history as JSON.
Compact Session	`<leader> c`	`session_compact`	Summarize and compact long chat context.
Rename Session	`Ctrl+R`	`session_rename`	Change current session title.
Delete Session	`Ctrl+D` (in list)	`session_delete`	Permanently remove a session.
Interrupt Generation	`Esc`	`session_interrupt`	Stop model generation or tool execution.

Messages & Scroll Navigation

Action	Shortcut	Config Key	Description
Page Up / Down	`PageUp` / `PageDown`	`messages_page_up` / `_down`	Scroll chat history by page.
Half Page Scroll	`Ctrl+Alt+U` / `Ctrl+Alt+D`	`messages_half_page_up` / `_down`	Scroll half page up/down.
Jump to Top	`Ctrl+G` or `Home`	`messages_first`	Jump to start of chat transcript.
Jump to Bottom	`Ctrl+Alt+G` or `End`	`messages_last`	Jump to latest response.
Copy Last Message	`<leader> y`	`messages_copy`	Copy entire last response directly to system clipboard.
Undo / Redo	`<leader> u` / `<leader> r`	`messages_undo` / `_redo`	Undo or redo chat message edits.
Conceal Code	`<leader> h`	`messages_toggle_conceal`	Fold or unfold code blocks in chat.

Models, Agents & Themes

Action	Shortcut	Config Key	Description
Switch Agent	`Tab` / `Shift+Tab`	`agent_cycle` / `_reverse`	Cycle between primary/subagent modes.
List Agents	`<leader> a`	`agent_list`	Open agent selector modal.
List Models	`<leader> m`	`model_list`	Open model selection dialog.
Cycle Recent Model	`F2` / `Shift+F2`	`model_cycle_recent`	Switch to previous model.
Favorite Model	`Ctrl+F`	`model_favorite_toggle`	Toggle favorite status for selected model.
Switch Theme	`<leader> t`	`theme_list`	Select UI color theme.
Cycle Variants	`Ctrl+T`	`variant_cycle`	Toggle model reasoning effort (low/med/high).

Prompt Input Editing (Readline / Emacs)

Shortcut	Action
`Enter`	Submit prompt
`Shift+Enter` / `Ctrl+J`	Insert newline
`Ctrl+A` / `Ctrl+E`	Move cursor to start / end of line
`Ctrl+B` / `Ctrl+F`	Move cursor back / forward one char
`Alt+B` / `Alt+F`	Move cursor back / forward one word
`Ctrl+K`	Kill text from cursor to end of line
`Ctrl+U`	Kill text from cursor to start of line
`Ctrl+W`	Delete word backward
`Alt+D`	Delete word forward

2. Modes & Execution Options

OpenCode offers several execution modes depending on your interface and automation needs.

1. Standard Interactive TUI (`opencode`)

Starts the full terminal user interface with chat transcript, sidebar info pane, and status indicators.

opencode

2. Minimal Single-Column TUI (`--mini`)

Removes sidebars, borders, and multi-column widgets.

# Start new minimal session
opencode --mini

# Resume last session in minimal mode
opencode --mini -c

3. Non-Interactive CLI / Scripting (`opencode run`)

Executes a single prompt or command non-interactively without launching the TUI. Prints raw Markdown or JSON output directly to stdout.

# Single prompt execution
opencode run "Explain closures in Rust"

# Pass file context
opencode run -f src/main.rs "Review this code for safety"

# Output as raw JSON events
opencode run --format json "List open TODO items"

4. Headless Server & Attach (`opencode serve` / `opencode attach`)

Runs an OpenCode backend server process (avoiding cold boots for MCP plugins) that remote terminals or web clients can attach to.

# Terminal 1: Start headless backend
opencode serve --port 4096

# Terminal 2: Attach TUI from another terminal/session
opencode attach http://localhost:4096

3. Customizing Shortcuts (`~/.config/opencode/tui.json`)

Keybinds can be overridden globally by creating or editing ~/.config/opencode/tui.json.

Example `tui.json` Configuration:

{
  "$schema": "https://opencode.ai/tui.json",
  "leader_timeout": 2000,
  "keybinds": {
    "leader": "ctrl+x",
    "sidebar_toggle": "f3",
    "messages_copy": ["<leader>y", "ctrl+shift+c"],
    "session_compact": "none"
  }
}

4. Copying Text Cleanly

Important Note on Mouse Selection: In TUI terminals, OpenCode renders chat messages inside a fixed width box container. Even with the sidebar hidden via <leader> b, terminal mouse dragging selects the entire terminal row width, picking up all trailing pad spaces up to the terminal window border.

Best Ways to Copy Code Snippets:

Use Message Copy Shortcut (<leader> y): Press Ctrl+X then y to yank the entire model's latest message directly into your system clipboard without any formatting or padding issues.
Use Tmux Copy Mode (Ctrl+B [): Use native tmux copy mode (v to select, y to copy via OSC 52).
Use CLI Run Mode (opencode run ...): Run single queries via opencode run to print raw, un-padded Markdown straight to standard output.