Skip to main content

OpenCode CLI & TUI Usage

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 pane. Expands chat to full screen for clean code selection. 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 message to 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. Chat output occupies 100% of terminal width, making line-by-line mouse selection completely clean without trailing spaces.

    # 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. Tips for Mouse Copying in Headless / Tmux

      Hide Sidebar: Press Ctrl+X then b to toggle off the right sidebar. Text will wrap cleanly at terminal edge with no pad spaces. Use Mini Mode: Run opencode --mini for a pure single-column experience. Copy Message Directly: Use <leader> y (Ctrl+X then y) to copy the model's full response directly into your system clipboard.