From 4fa468c691a349351105b85a6f55e2b226584a1c Mon Sep 17 00:00:00 2001 From: Hong Yi Chen Date: Tue, 28 Jul 2026 14:34:05 -0700 Subject: [PATCH 01/12] docs(cli): draft input and editing page Replace the cli/input-and-editing.mdx stub with full content covering editing basics, the slash command menu with argument hints, up-arrow prompt history, shell tab completions, mouse support, selection and clipboard behavior (incl. OSC 52 over SSH), image attachments, voice input, and the contextual keyboard hints plus the ? shortcuts menu. Dropped from the outline after verifying against warp master: Vim mode (not merged), inline-menu mouse clicks (not shipped), and configurable keybinding claims (the CLI does not load keybinding overrides yet). Co-Authored-By: Oz --- src/content/docs/cli/input-and-editing.mdx | 90 ++++++++++++++++++---- 1 file changed, 76 insertions(+), 14 deletions(-) diff --git a/src/content/docs/cli/input-and-editing.mdx b/src/content/docs/cli/input-and-editing.mdx index 0269b281..570ea155 100644 --- a/src/content/docs/cli/input-and-editing.mdx +++ b/src/content/docs/cli/input-and-editing.mdx @@ -1,47 +1,109 @@ --- title: "Input and editing in the {{WARP_CLI}}" description: >- - The {{WARP_CLI}} input editor: slash commands, history, completions, mouse - support, images, voice input, and Vim mode. + Compose prompts and commands in the {{WARP_CLI}} input editor with slash + commands, history, completions, mouse support, images, and voice input. --- import { VARS } from '@data/vars'; -{/* TODO(cli-input): draft per drafts/warp-cli-launch-plan.md — "cli/input-and-editing.mdx" section. Feature-doc content type. */} +The {VARS.WARP_CLI} input is a multiline editor for prompts and shell commands. It combines readline-style editing with inline menus for slash commands, history, and completions, plus mouse support, image attachments, and voice input. This page covers how to compose and edit input. For the complete list of flags, slash commands, and keyboard shortcuts, see the [{VARS.WARP_CLI} reference](/cli/reference/). -The {VARS.WARP_CLI} documentation for this page is in progress. +## Editing basics + +The input accepts multiple lines and soft-wraps long lines to your terminal width. It grows up to six rows tall, then scrolls. + +* **Submit** - Press `Enter` to send a prompt to the agent or run a shell command. +* **Insert a newline** - Press `Ctrl+J`, or `Shift+Enter` in terminals that support distinguishing it. `Alt+Enter` also works. +* **Edit with readline-style keys** - The editor supports familiar bindings such as `Ctrl+A` and `Ctrl+E` (start and end of line), `Ctrl+W` (delete the previous word), `Ctrl+K` and `Ctrl+U` (delete to the end or start of the line), `Ctrl+Y` (reinsert the last deleted text), and `Ctrl+Z` (undo). + +The full editing and selection table is in the [keyboard shortcuts reference](/cli/reference/#keyboard-shortcuts). ## Slash commands -{/* TODO(cli-input): slash command menu, filtering, argument hints; link to reference page for the full table. */} +Type `/` at the start of an empty input to open the slash command menu. The menu filters as you type, and entries for toggles and pickers show their current state, for example `/theme (currently auto: Dark)` or `/auto-approve (currently off)`. + +1. Type `/` followed by part of a command name. +2. Press `↑` or `↓` to change the selection. +3. Press `Enter` to run the selected command, or `Esc` to close the menu. + +When a command takes an argument, the input shows a ghost-text argument hint after the full command name, for example `/theme `. Type the argument after the command name, then press `Enter`. + +Your [skills](/cli/context/) also appear in the slash command menu, so you can invoke a skill by typing `/` followed by its name. + +The full command table is in the [slash commands reference](/cli/reference/#slash-commands). ## Prompt history -{/* TODO(cli-input): up-arrow history for prompts and shell commands. */} +Press `↑` with the cursor on the first row of the input to open your input history. + +* **What's listed** - In agent mode, the menu lists your previous prompts and shell commands together. Shell command entries carry a `!` prefix. In [shell mode](/cli/shell-commands/), the menu lists commands only. +* **Filter** - Keep typing to filter the list. +* **Preview and accept** - The highlighted entry previews directly in the input. Press `Enter` to keep it, then edit or submit it as usual. +* **Dismiss** - Press `Esc` to close the menu and restore what you were typing. Pressing `↓` past the newest entry does the same. ## Tab completions -{/* TODO(cli-input): completions for shell commands — confirm shipped before merge. */} +In [shell mode](/cli/shell-commands/), press `Tab` to complete the command you're typing, including file and directory paths. + +* If exactly one completion matches, the {VARS.WARP_CLI} applies it immediately. +* If several completions match, the {VARS.WARP_CLI} inserts the longest shared prefix and opens a completion menu. Press `Tab` or `↓` to move through the suggestions, `Enter` to accept the selected one, or `Esc` to dismiss the menu. ## Mouse support -{/* TODO(cli-input): text selection in the input, clicking inline menu rows, selection persistence. */} +The {VARS.WARP_CLI} runs in your terminal, but the input is fully mouse-aware: + +* **Position the cursor** - Click anywhere in the input to move the cursor there. +* **Select text** - Drag to select. Double-click selects a word, and triple-click selects a line. +* **Scroll** - Use the scroll wheel to scroll the input viewport or the conversation transcript. +* **Click controls** - Interactive elements such as the **Voice** footer entry and the attachment bar controls respond to clicks. ## Selection and clipboard -{/* TODO(cli-input): copying, opt-in auto-copy of highlighted input text. */} +* **Highlight to copy** - Finishing a mouse selection in the input or the [conversation transcript](/cli/agent-conversations/) automatically copies it, and the footer briefly shows "copied to clipboard". +* **Keyboard selection** - Extend the selection with `Shift` plus the arrow keys, or select everything with `Ctrl+Shift+A`. Copy with `Ctrl+Shift+C` and cut with `Ctrl+X`. +* **Paste** - Press `Ctrl+V` or `Ctrl+Shift+V` (also `Alt+V` on Windows). Your terminal's own paste shortcut works as well. + +:::note +Copying works over SSH: on remote sessions the {VARS.WARP_CLI} writes the clipboard through the OSC 52 escape sequence (including tmux passthrough), so your local clipboard receives the text when your terminal supports OSC 52. +::: ## Attach images -{/* TODO(cli-input): attaching images as context. */} +Attach images to a prompt so the agent can analyze them: + +* **Paste an image** - Copy an image to your clipboard and press `Ctrl+V`. +* **Paste or drop a file path** - Paste the path to an image file, or drag the file onto your terminal window so its path lands in the input. Absolute paths, paths relative to the working directory, and `~` paths all resolve. + +Supported formats are PNG, JPEG, GIF, and WebP. Attaching an image locks the input to agent mode, since images are sent to the agent rather than the shell. + +Attached images appear in an attachment bar above the input: + +1. Press `Tab` to focus the attachment bar. +2. Press `←` and `→` (or `Tab` and `Shift+Tab`) to move between attachments. +3. Press `Backspace` to remove the selected attachment. +4. Press `Esc` or `Enter` to return focus to the input. ## Voice input -{/* TODO(cli-input): /voice, `Ctrl+S`, configurable keybinding; cross-link voice docs. */} +Dictate prompts instead of typing them: -## Vim mode +1. Start listening with `Ctrl+S`, the `/voice` slash command, or by clicking **Voice** in the footer. The footer shows **Listening** while recording. +2. Speak your prompt. +3. Press `Enter`, or click the footer entry again, to stop recording. The footer shows **Transcribing**, and the transcribed text lands in the input so you can review and edit it before submitting. -{/* TODO(cli-input): vim input mode — confirm shipped before merge. */} +Press `Esc` while transcription is in progress to cancel it. `/voice` clears the input before recording; `Ctrl+S` keeps what you've already typed. + +Voice input in the {VARS.WARP_CLI} uses the same transcription service as the Warp app. See [voice input for agents](/agent-platform/local-agents/interacting-with-agents/voice/) for microphone setup, privacy, and usage limits. ## Keyboard hints and the shortcuts menu -{/* TODO(cli-input): ghost-text hints in the input, shortcuts menu. */} +The {VARS.WARP_CLI} surfaces its shortcuts contextually, so you rarely need to memorize them: + +* **Placeholder hints** - An empty input shows ghost-text hints for the current state, for example "Ask the agent anything • ? for shortcuts • ! for shell mode • / for commands" in agent mode, or "Run a shell command • ? for shortcuts • esc for agent mode" in shell mode. While a long-running command owns the input, the hint row shows "ctrl-c to interrupt". +* **Shortcuts menu** - Type `?` in an empty input to open a shortcuts overview. Its contents adapt to what you're doing: agent mode lists the menu triggers and input history, shell mode shows how to return to agent mode, and extra sections appear during multi-agent sessions or agent-controlled terminal use. Press `Esc`, or just start typing, to close it. + +## Related pages + +* [{VARS.WARP_CLI} reference](/cli/reference/) - Flags, environment variables, slash commands, and keyboard shortcuts. +* [Shell commands in the {VARS.WARP_CLI}](/cli/shell-commands/) - Shell mode, natural language detection, and long-running commands. +* [Agent conversations in the {VARS.WARP_CLI}](/cli/agent-conversations/) - The transcript, tool calls, and diffs. From b41deb92b1fd2e53fc5a9bc464ce689aedb21f44 Mon Sep 17 00:00:00 2001 From: Hong Yi Chen Date: Tue, 28 Jul 2026 14:45:20 -0700 Subject: [PATCH 02/12] docs(cli): use literal Warp CLI in frontmatter {{WARP_CLI}} tokens are not substituted in MDX frontmatter (Astro's content layer parses frontmatter outside Vite), so the built title and description showed the raw token. Body-prose {VARS.WARP_CLI} is unchanged. Verified the built dist/cli/input-and-editing now reads "Input and editing in the Warp CLI". Co-Authored-By: Oz <oz-agent@warp.dev> --- src/content/docs/cli/input-and-editing.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/content/docs/cli/input-and-editing.mdx b/src/content/docs/cli/input-and-editing.mdx index 570ea155..52bc9851 100644 --- a/src/content/docs/cli/input-and-editing.mdx +++ b/src/content/docs/cli/input-and-editing.mdx @@ -1,7 +1,7 @@ --- -title: "Input and editing in the {{WARP_CLI}}" +title: "Input and editing in the Warp CLI" description: >- - Compose prompts and commands in the {{WARP_CLI}} input editor with slash + Compose prompts and commands in the Warp CLI input editor with slash commands, history, completions, mouse support, images, and voice input. --- import { VARS } from '@data/vars'; From 490a7e008c23933f9e0e580657e0a0250232a407 Mon Sep 17 00:00:00 2001 From: Hong Yi Chen <hongyigma@gmail.com> Date: Tue, 28 Jul 2026 14:58:37 -0700 Subject: [PATCH 03/12] docs(cli): absorb shell commands page into input page Consolidation: merge the verified content of cli/shell-commands.mdx (PR #403, branch hyc/launch-cli-cli-shell-commands) into cli/input-and-editing.mdx as a single "Input and shell commands in the Warp CLI" page. Adds shell mode, natural language detection, long-running and interactive commands, full-screen apps, and stopping/ exiting sections; merges the two history sections into one (adopting the verified submit-on-Enter semantics); rewires shell-mode links to in-page anchors. File rename to the new slug happens at integration. Co-Authored-By: Oz <oz-agent@warp.dev> --- src/content/docs/cli/input-and-editing.mdx | 87 +++++++++++++++++++--- 1 file changed, 76 insertions(+), 11 deletions(-) diff --git a/src/content/docs/cli/input-and-editing.mdx b/src/content/docs/cli/input-and-editing.mdx index 52bc9851..e1558f25 100644 --- a/src/content/docs/cli/input-and-editing.mdx +++ b/src/content/docs/cli/input-and-editing.mdx @@ -1,12 +1,13 @@ --- -title: "Input and editing in the Warp CLI" +title: "Input and shell commands in the Warp CLI" description: >- - Compose prompts and commands in the Warp CLI input editor with slash - commands, history, completions, mouse support, images, and voice input. + Compose prompts, edit input, and run shell commands in the Warp CLI, + including menus, history, completions, images, voice, and interactive + commands. --- import { VARS } from '@data/vars'; -The {VARS.WARP_CLI} input is a multiline editor for prompts and shell commands. It combines readline-style editing with inline menus for slash commands, history, and completions, plus mouse support, image attachments, and voice input. This page covers how to compose and edit input. For the complete list of flags, slash commands, and keyboard shortcuts, see the [{VARS.WARP_CLI} reference](/cli/reference/). +The {VARS.WARP_CLI} is a full terminal as well as an agent: every session runs a real shell, so you can run commands in the same place you prompt the agent. The input is a multiline editor that combines readline-style editing with inline menus for slash commands, history, and completions, plus mouse support, image attachments, and voice input. This page covers composing and editing input and running shell commands. For the complete list of flags, slash commands, and keyboard shortcuts, see the [{VARS.WARP_CLI} reference](/cli/reference/). ## Editing basics @@ -32,18 +33,21 @@ Your [skills](/cli/context/) also appear in the slash command menu, so you can i The full command table is in the [slash commands reference](/cli/reference/#slash-commands). -## Prompt history +## Input history -Press `↑` with the cursor on the first row of the input to open your input history. +Press `↑` with the cursor on the first row of the input to open the history menu. -* **What's listed** - In agent mode, the menu lists your previous prompts and shell commands together. Shell command entries carry a `!` prefix. In [shell mode](/cli/shell-commands/), the menu lists commands only. +* **What's listed** - In agent mode, the menu combines your previous prompts and shell commands in one list, with commands marked by a `!` prefix. In [shell mode](#shell-mode), the menu lists commands only. * **Filter** - Keep typing to filter the list. -* **Preview and accept** - The highlighted entry previews directly in the input. Press `Enter` to keep it, then edit or submit it as usual. -* **Dismiss** - Press `Esc` to close the menu and restore what you were typing. Pressing `↓` past the newest entry does the same. +* **Preview** - Moving the selection previews each entry in the input and switches the input to the matching mode: recalled commands run as shell commands, and recalled prompts go to the agent. +* **Submit** - Press `Enter` to run the selected command or send the selected prompt. +* **Dismiss** - Press `Esc` to close the menu and restore what you had typed. Pressing `↓` past the newest entry does the same. + +Commands you run in the {VARS.WARP_CLI} are added to your command history. ## Tab completions -In [shell mode](/cli/shell-commands/), press `Tab` to complete the command you're typing, including file and directory paths. +In [shell mode](#shell-mode), press `Tab` to complete the command you're typing, including file and directory paths. * If exactly one completion matches, the {VARS.WARP_CLI} applies it immediately. * If several completions match, the {VARS.WARP_CLI} inserts the longest shared prefix and opens a completion menu. Press `Tab` or `↓` to move through the suggestions, `Enter` to accept the selected one, or `Esc` to dismiss the menu. @@ -102,8 +106,69 @@ The {VARS.WARP_CLI} surfaces its shortcuts contextually, so you rarely need to m * **Placeholder hints** - An empty input shows ghost-text hints for the current state, for example "Ask the agent anything • ? for shortcuts • ! for shell mode • / for commands" in agent mode, or "Run a shell command • ? for shortcuts • esc for agent mode" in shell mode. While a long-running command owns the input, the hint row shows "ctrl-c to interrupt". * **Shortcuts menu** - Type `?` in an empty input to open a shortcuts overview. Its contents adapt to what you're doing: agent mode lists the menu triggers and input history, shell mode shows how to return to agent mode, and extra sections appear during multi-agent sessions or agent-controlled terminal use. Press `Esc`, or just start typing, to close it. +## Shell mode + +The input is agent-first: by default, pressing `Enter` sends your text to the agent as a prompt. Use shell mode to run a command instead: + +1. Press `!` at the start of the input. The prompt marker changes from `>` to `!`, and the statusline below the input shows **Shell mode**. +2. Type a command and press `Enter`. The command runs in the session's shell, and the input returns to agent mode. + +To leave shell mode without running a command, press `Esc`, or press `Backspace` at the start of the input. Any text you typed stays in the input. + +In the transcript, each command you run is marked with a `!` prefix and a highlighted row background, so shell commands stay visually distinct from prompts and agent responses. Output streams in below the command as it's produced. + +In shell mode, press `Tab` to complete commands and paths; see [Tab completions](#tab-completions). + +:::note +Running a shell command cancels the agent's in-progress response, if there is one. +::: + +## Natural language detection + +Out of the box, the {VARS.WARP_CLI} never guesses what your input is: everything goes to the agent unless you enter shell mode. To type commands directly without the `!` prefix, turn on natural language detection: + +- **Toggle detection** - Run `/natural-language-detection` to turn detection on or off. The statusline confirms the change, and the setting persists across sessions. +- **Automatic classification** - With detection on, the {VARS.WARP_CLI} classifies your input as you type. When the input looks like a shell command (for example, `git status`), the input switches to shell mode, and `Enter` runs it as a command. Everything else is sent to the agent. +- **Biased toward the agent** - Short or ambiguous input stays in agent mode, and a single word switches to shell mode only when it matches a command available in your shell. + +The prompt marker and statusline always show the current mode before you press `Enter`. If detection classifies input differently than you intended, press `Esc` to switch back to agent mode, or press `!` at the start of the input to force shell mode. + +## Long-running and interactive commands + +When a command keeps running, such as a dev server, a package install, or an interactive prompt, the {VARS.WARP_CLI} hands input over to it: + +- **Input passthrough** - Keystrokes and pasted text are forwarded to the running process, so password requests, confirmation prompts, and other interactive programs work as they do in a plain terminal. +- **Interrupt hint** - While the command owns input, a dimmed `ctrl-c to interrupt` hint replaces the input. Press `Ctrl+C` to stop the command. +- **Type ahead** - If you start typing your next command before the current one finishes, the typed characters are carried into the input when the command completes, with the cursor at the end. This matches type-ahead behavior in shells like zsh and bash. + +One command runs in the session at a time. If the terminal is already busy, for example while the agent is running a command of its own, submitting a shell command shows a notice in the statusline and keeps your text in the input. + +## Full-screen terminal apps + +Commands that switch the terminal to the alternate screen, such as `vim`, `htop`, or `less`, take over the whole {VARS.WARP_CLI} view: + +- The app renders full-screen and receives keyboard, paste, scroll, and mouse input, so editors and other terminal UIs are fully usable inside the {VARS.WARP_CLI}. +- When the app exits, the transcript returns with your conversation intact. + +## Stopping commands and exiting + +`Ctrl+C` performs one contextual action per press: + +- **While a command is running** - `Ctrl+C` interrupts the running command, as in a plain terminal. It doesn't exit the {VARS.WARP_CLI}. +- **While the agent is responding** - `Ctrl+C` cancels the in-progress response. Text in the input is preserved. +- **At an idle prompt** - `Ctrl+C` clears the input if it has text. + +After a press at the prompt, the statusline shows `ctrl-c again to exit` for about one second. Press `Ctrl+C` a second time within that window to exit the {VARS.WARP_CLI}. This works even while the agent is responding; while a shell command is running, `Ctrl+C` keeps interrupting the command instead. + +There are two other ways to exit: + +- **`Ctrl+D`** - Exits immediately when the input is empty. +- **`/exit`** - Exits from the slash command menu. + +When you exit, the {VARS.WARP_CLI} prints a command you can use to pick the conversation back up later. See [Managing conversations](/cli/conversations/) for resuming and switching conversations. + ## Related pages * [{VARS.WARP_CLI} reference](/cli/reference/) - Flags, environment variables, slash commands, and keyboard shortcuts. -* [Shell commands in the {VARS.WARP_CLI}](/cli/shell-commands/) - Shell mode, natural language detection, and long-running commands. * [Agent conversations in the {VARS.WARP_CLI}](/cli/agent-conversations/) - The transcript, tool calls, and diffs. +* [Managing conversations in the {VARS.WARP_CLI}](/cli/conversations/) - Persistence, resuming, and switching conversations. From 438d0dec3ce49e45c31020ed6a76e6f1ec51bb76 Mon Sep 17 00:00:00 2001 From: Hong Yi Chen <hongyigma@gmail.com> Date: Tue, 28 Jul 2026 15:06:51 -0700 Subject: [PATCH 04/12] docs(cli): rename Warp CLI to Warp Agent CLI in frontmatter Launch name confirmed as Warp Agent CLI. Base branch merge picks up the WARP_CLI var change (e2aebe3c) for body prose; this updates the two literal frontmatter strings (title, description). Verified the built title reads "Input and shell commands in the Warp Agent CLI". Co-Authored-By: Oz <oz-agent@warp.dev> --- src/content/docs/cli/input-and-editing.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/content/docs/cli/input-and-editing.mdx b/src/content/docs/cli/input-and-editing.mdx index e1558f25..4b3e7502 100644 --- a/src/content/docs/cli/input-and-editing.mdx +++ b/src/content/docs/cli/input-and-editing.mdx @@ -1,7 +1,7 @@ --- -title: "Input and shell commands in the Warp CLI" +title: "Input and shell commands in the Warp Agent CLI" description: >- - Compose prompts, edit input, and run shell commands in the Warp CLI, + Compose prompts, edit input, and run shell commands in the Warp Agent CLI, including menus, history, completions, images, voice, and interactive commands. --- From 1bd36e64a2c2f25cb78b21b88b6f2f2983d547b4 Mon Sep 17 00:00:00 2001 From: Hong Yi Chen <hongyigma@gmail.com> Date: Wed, 29 Jul 2026 16:08:16 -0700 Subject: [PATCH 05/12] docs(cli): light editorial polish on input page Reduce product-name density (prefer "the CLI" after the intro; keep the full name in the intro and Related pages), drop one banned word ("just"), remove a filler wayfinding sentence from the intro, vary a repeated cross-reference rhythm, dedupe "lands in the input", and use a plainer verb for the hints section opener. No heading, fact, or link target changes. Co-Authored-By: Oz <oz-agent@warp.dev> --- src/content/docs/cli/input-and-editing.mdx | 38 +++++++++++----------- 1 file changed, 19 insertions(+), 19 deletions(-) diff --git a/src/content/docs/cli/input-and-editing.mdx b/src/content/docs/cli/input-and-editing.mdx index 4b3e7502..40403257 100644 --- a/src/content/docs/cli/input-and-editing.mdx +++ b/src/content/docs/cli/input-and-editing.mdx @@ -7,7 +7,7 @@ description: >- --- import { VARS } from '@data/vars'; -The {VARS.WARP_CLI} is a full terminal as well as an agent: every session runs a real shell, so you can run commands in the same place you prompt the agent. The input is a multiline editor that combines readline-style editing with inline menus for slash commands, history, and completions, plus mouse support, image attachments, and voice input. This page covers composing and editing input and running shell commands. For the complete list of flags, slash commands, and keyboard shortcuts, see the [{VARS.WARP_CLI} reference](/cli/reference/). +The {VARS.WARP_CLI} is a full terminal as well as an agent: every session runs a real shell, so you can run commands in the same place you prompt the agent. The input is a multiline editor that combines readline-style editing with inline menus for slash commands, history, and completions, plus mouse support, image attachments, and voice input. For the complete list of flags, slash commands, and keyboard shortcuts, see the [{VARS.WARP_CLI} reference](/cli/reference/). ## Editing basics @@ -31,7 +31,7 @@ When a command takes an argument, the input shows a ghost-text argument hint aft Your [skills](/cli/context/) also appear in the slash command menu, so you can invoke a skill by typing `/` followed by its name. -The full command table is in the [slash commands reference](/cli/reference/#slash-commands). +The [slash commands reference](/cli/reference/#slash-commands) lists every command. ## Input history @@ -43,18 +43,18 @@ Press `↑` with the cursor on the first row of the input to open the history me * **Submit** - Press `Enter` to run the selected command or send the selected prompt. * **Dismiss** - Press `Esc` to close the menu and restore what you had typed. Pressing `↓` past the newest entry does the same. -Commands you run in the {VARS.WARP_CLI} are added to your command history. +Commands you run in the CLI are added to your command history. ## Tab completions In [shell mode](#shell-mode), press `Tab` to complete the command you're typing, including file and directory paths. -* If exactly one completion matches, the {VARS.WARP_CLI} applies it immediately. -* If several completions match, the {VARS.WARP_CLI} inserts the longest shared prefix and opens a completion menu. Press `Tab` or `↓` to move through the suggestions, `Enter` to accept the selected one, or `Esc` to dismiss the menu. +* If exactly one completion matches, the CLI applies it immediately. +* If several completions match, the CLI inserts the longest shared prefix and opens a completion menu. Press `Tab` or `↓` to move through the suggestions, `Enter` to accept the selected one, or `Esc` to dismiss the menu. ## Mouse support -The {VARS.WARP_CLI} runs in your terminal, but the input is fully mouse-aware: +The CLI runs in your terminal, but the input is fully mouse-aware: * **Position the cursor** - Click anywhere in the input to move the cursor there. * **Select text** - Drag to select. Double-click selects a word, and triple-click selects a line. @@ -68,7 +68,7 @@ The {VARS.WARP_CLI} runs in your terminal, but the input is fully mouse-aware: * **Paste** - Press `Ctrl+V` or `Ctrl+Shift+V` (also `Alt+V` on Windows). Your terminal's own paste shortcut works as well. :::note -Copying works over SSH: on remote sessions the {VARS.WARP_CLI} writes the clipboard through the OSC 52 escape sequence (including tmux passthrough), so your local clipboard receives the text when your terminal supports OSC 52. +Copying works over SSH: on remote sessions the CLI writes the clipboard through the OSC 52 escape sequence (including tmux passthrough), so your local clipboard receives the text when your terminal supports OSC 52. ::: ## Attach images @@ -76,7 +76,7 @@ Copying works over SSH: on remote sessions the {VARS.WARP_CLI} writes the clipbo Attach images to a prompt so the agent can analyze them: * **Paste an image** - Copy an image to your clipboard and press `Ctrl+V`. -* **Paste or drop a file path** - Paste the path to an image file, or drag the file onto your terminal window so its path lands in the input. Absolute paths, paths relative to the working directory, and `~` paths all resolve. +* **Paste or drop a file path** - Paste the path to an image file, or drag the file onto your terminal window to insert its path. Absolute paths, paths relative to the working directory, and `~` paths all resolve. Supported formats are PNG, JPEG, GIF, and WebP. Attaching an image locks the input to agent mode, since images are sent to the agent rather than the shell. @@ -97,14 +97,14 @@ Dictate prompts instead of typing them: Press `Esc` while transcription is in progress to cancel it. `/voice` clears the input before recording; `Ctrl+S` keeps what you've already typed. -Voice input in the {VARS.WARP_CLI} uses the same transcription service as the Warp app. See [voice input for agents](/agent-platform/local-agents/interacting-with-agents/voice/) for microphone setup, privacy, and usage limits. +Voice input in the CLI uses the same transcription service as the Warp app. See [voice input for agents](/agent-platform/local-agents/interacting-with-agents/voice/) for microphone setup, privacy, and usage limits. ## Keyboard hints and the shortcuts menu -The {VARS.WARP_CLI} surfaces its shortcuts contextually, so you rarely need to memorize them: +The CLI shows its shortcuts in context, so you rarely need to memorize them: * **Placeholder hints** - An empty input shows ghost-text hints for the current state, for example "Ask the agent anything • ? for shortcuts • ! for shell mode • / for commands" in agent mode, or "Run a shell command • ? for shortcuts • esc for agent mode" in shell mode. While a long-running command owns the input, the hint row shows "ctrl-c to interrupt". -* **Shortcuts menu** - Type `?` in an empty input to open a shortcuts overview. Its contents adapt to what you're doing: agent mode lists the menu triggers and input history, shell mode shows how to return to agent mode, and extra sections appear during multi-agent sessions or agent-controlled terminal use. Press `Esc`, or just start typing, to close it. +* **Shortcuts menu** - Type `?` in an empty input to open a shortcuts overview. Its contents adapt to what you're doing: agent mode lists the menu triggers and input history, shell mode shows how to return to agent mode, and extra sections appear during multi-agent sessions or agent-controlled terminal use. Press `Esc`, or start typing, to close it. ## Shell mode @@ -125,17 +125,17 @@ Running a shell command cancels the agent's in-progress response, if there is on ## Natural language detection -Out of the box, the {VARS.WARP_CLI} never guesses what your input is: everything goes to the agent unless you enter shell mode. To type commands directly without the `!` prefix, turn on natural language detection: +Out of the box, the CLI never guesses what your input is: everything goes to the agent unless you enter shell mode. To type commands directly without the `!` prefix, turn on natural language detection: - **Toggle detection** - Run `/natural-language-detection` to turn detection on or off. The statusline confirms the change, and the setting persists across sessions. -- **Automatic classification** - With detection on, the {VARS.WARP_CLI} classifies your input as you type. When the input looks like a shell command (for example, `git status`), the input switches to shell mode, and `Enter` runs it as a command. Everything else is sent to the agent. +- **Automatic classification** - With detection on, the CLI classifies your input as you type. When the input looks like a shell command (for example, `git status`), the input switches to shell mode, and `Enter` runs it as a command. Everything else is sent to the agent. - **Biased toward the agent** - Short or ambiguous input stays in agent mode, and a single word switches to shell mode only when it matches a command available in your shell. The prompt marker and statusline always show the current mode before you press `Enter`. If detection classifies input differently than you intended, press `Esc` to switch back to agent mode, or press `!` at the start of the input to force shell mode. ## Long-running and interactive commands -When a command keeps running, such as a dev server, a package install, or an interactive prompt, the {VARS.WARP_CLI} hands input over to it: +When a command keeps running, such as a dev server, a package install, or an interactive prompt, the CLI hands input over to it: - **Input passthrough** - Keystrokes and pasted text are forwarded to the running process, so password requests, confirmation prompts, and other interactive programs work as they do in a plain terminal. - **Interrupt hint** - While the command owns input, a dimmed `ctrl-c to interrupt` hint replaces the input. Press `Ctrl+C` to stop the command. @@ -145,27 +145,27 @@ One command runs in the session at a time. If the terminal is already busy, for ## Full-screen terminal apps -Commands that switch the terminal to the alternate screen, such as `vim`, `htop`, or `less`, take over the whole {VARS.WARP_CLI} view: +Commands that switch the terminal to the alternate screen, such as `vim`, `htop`, or `less`, take over the whole CLI view: -- The app renders full-screen and receives keyboard, paste, scroll, and mouse input, so editors and other terminal UIs are fully usable inside the {VARS.WARP_CLI}. +- The app renders full-screen and receives keyboard, paste, scroll, and mouse input, so editors and other terminal UIs are fully usable inside the CLI. - When the app exits, the transcript returns with your conversation intact. ## Stopping commands and exiting `Ctrl+C` performs one contextual action per press: -- **While a command is running** - `Ctrl+C` interrupts the running command, as in a plain terminal. It doesn't exit the {VARS.WARP_CLI}. +- **While a command is running** - `Ctrl+C` interrupts the running command, as in a plain terminal. It doesn't exit the CLI. - **While the agent is responding** - `Ctrl+C` cancels the in-progress response. Text in the input is preserved. - **At an idle prompt** - `Ctrl+C` clears the input if it has text. -After a press at the prompt, the statusline shows `ctrl-c again to exit` for about one second. Press `Ctrl+C` a second time within that window to exit the {VARS.WARP_CLI}. This works even while the agent is responding; while a shell command is running, `Ctrl+C` keeps interrupting the command instead. +After a press at the prompt, the statusline shows `ctrl-c again to exit` for about one second. Press `Ctrl+C` a second time within that window to exit the CLI. This works even while the agent is responding; while a shell command is running, `Ctrl+C` keeps interrupting the command instead. There are two other ways to exit: - **`Ctrl+D`** - Exits immediately when the input is empty. - **`/exit`** - Exits from the slash command menu. -When you exit, the {VARS.WARP_CLI} prints a command you can use to pick the conversation back up later. See [Managing conversations](/cli/conversations/) for resuming and switching conversations. +When you exit, the CLI prints a command you can use to pick the conversation back up later. See [Managing conversations](/cli/conversations/) for resuming and switching conversations. ## Related pages From b91654adda76a53e65a385582c710dd7a2ce2a07 Mon Sep 17 00:00:00 2001 From: Hong Yi Chen <hongyigma@gmail.com> Date: Wed, 29 Jul 2026 16:26:33 -0700 Subject: [PATCH 06/12] docs(cli): trim narration of obvious UI mechanics Per editorial direction: cut the slash-menu usage steps, the Submit and six-row-scroll narration in editing basics, the history Filter bullet, completion-menu Enter/Esc narration, cursor-click and scroll-wheel bullets, the attachment-bar arrow/Enter steps (kept Tab focus, Backspace remove, Esc return as one sentence), the "Speak your prompt" voice step, the duplicated long-running interrupt hint, type-and-press- Enter in shell mode, and the output-streams-in sentence. Kept non-obvious keys, defaults, and gotchas (submit-on-Enter history semantics, restore-on-dismiss, OSC 52 note). No heading changes. Co-Authored-By: Oz <oz-agent@warp.dev> --- src/content/docs/cli/input-and-editing.mdx | 32 ++++++---------------- 1 file changed, 9 insertions(+), 23 deletions(-) diff --git a/src/content/docs/cli/input-and-editing.mdx b/src/content/docs/cli/input-and-editing.mdx index 40403257..c5c783d9 100644 --- a/src/content/docs/cli/input-and-editing.mdx +++ b/src/content/docs/cli/input-and-editing.mdx @@ -11,9 +11,8 @@ The {VARS.WARP_CLI} is a full terminal as well as an agent: every session runs a ## Editing basics -The input accepts multiple lines and soft-wraps long lines to your terminal width. It grows up to six rows tall, then scrolls. +The input accepts multiple lines and soft-wraps long lines to your terminal width. -* **Submit** - Press `Enter` to send a prompt to the agent or run a shell command. * **Insert a newline** - Press `Ctrl+J`, or `Shift+Enter` in terminals that support distinguishing it. `Alt+Enter` also works. * **Edit with readline-style keys** - The editor supports familiar bindings such as `Ctrl+A` and `Ctrl+E` (start and end of line), `Ctrl+W` (delete the previous word), `Ctrl+K` and `Ctrl+U` (delete to the end or start of the line), `Ctrl+Y` (reinsert the last deleted text), and `Ctrl+Z` (undo). @@ -21,13 +20,9 @@ The full editing and selection table is in the [keyboard shortcuts reference](/c ## Slash commands -Type `/` at the start of an empty input to open the slash command menu. The menu filters as you type, and entries for toggles and pickers show their current state, for example `/theme (currently auto: Dark)` or `/auto-approve (currently off)`. +Type `/` at the start of an empty input to open the slash command menu. Entries for toggles and pickers show their current state, for example `/theme (currently auto: Dark)` or `/auto-approve (currently off)`. -1. Type `/` followed by part of a command name. -2. Press `↑` or `↓` to change the selection. -3. Press `Enter` to run the selected command, or `Esc` to close the menu. - -When a command takes an argument, the input shows a ghost-text argument hint after the full command name, for example `/theme <auto|light|dark>`. Type the argument after the command name, then press `Enter`. +When a command takes an argument, the input shows a ghost-text argument hint after the full command name, for example `/theme <auto|light|dark>`. Your [skills](/cli/context/) also appear in the slash command menu, so you can invoke a skill by typing `/` followed by its name. @@ -38,7 +33,6 @@ The [slash commands reference](/cli/reference/#slash-commands) lists every comma Press `↑` with the cursor on the first row of the input to open the history menu. * **What's listed** - In agent mode, the menu combines your previous prompts and shell commands in one list, with commands marked by a `!` prefix. In [shell mode](#shell-mode), the menu lists commands only. -* **Filter** - Keep typing to filter the list. * **Preview** - Moving the selection previews each entry in the input and switches the input to the matching mode: recalled commands run as shell commands, and recalled prompts go to the agent. * **Submit** - Press `Enter` to run the selected command or send the selected prompt. * **Dismiss** - Press `Esc` to close the menu and restore what you had typed. Pressing `↓` past the newest entry does the same. @@ -50,15 +44,13 @@ Commands you run in the CLI are added to your command history. In [shell mode](#shell-mode), press `Tab` to complete the command you're typing, including file and directory paths. * If exactly one completion matches, the CLI applies it immediately. -* If several completions match, the CLI inserts the longest shared prefix and opens a completion menu. Press `Tab` or `↓` to move through the suggestions, `Enter` to accept the selected one, or `Esc` to dismiss the menu. +* If several completions match, the CLI inserts the longest shared prefix and opens a completion menu. Press `Tab` again to cycle through the suggestions. ## Mouse support The CLI runs in your terminal, but the input is fully mouse-aware: -* **Position the cursor** - Click anywhere in the input to move the cursor there. * **Select text** - Drag to select. Double-click selects a word, and triple-click selects a line. -* **Scroll** - Use the scroll wheel to scroll the input viewport or the conversation transcript. * **Click controls** - Interactive elements such as the **Voice** footer entry and the attachment bar controls respond to clicks. ## Selection and clipboard @@ -80,20 +72,14 @@ Attach images to a prompt so the agent can analyze them: Supported formats are PNG, JPEG, GIF, and WebP. Attaching an image locks the input to agent mode, since images are sent to the agent rather than the shell. -Attached images appear in an attachment bar above the input: - -1. Press `Tab` to focus the attachment bar. -2. Press `←` and `→` (or `Tab` and `Shift+Tab`) to move between attachments. -3. Press `Backspace` to remove the selected attachment. -4. Press `Esc` or `Enter` to return focus to the input. +Attached images appear in an attachment bar above the input. Press `Tab` to focus the bar, `Backspace` to remove the selected attachment, and `Esc` to return to the input. ## Voice input Dictate prompts instead of typing them: 1. Start listening with `Ctrl+S`, the `/voice` slash command, or by clicking **Voice** in the footer. The footer shows **Listening** while recording. -2. Speak your prompt. -3. Press `Enter`, or click the footer entry again, to stop recording. The footer shows **Transcribing**, and the transcribed text lands in the input so you can review and edit it before submitting. +2. Press `Enter`, or click the footer entry again, to stop recording. The transcribed text lands in the input so you can review and edit it before submitting. Press `Esc` while transcription is in progress to cancel it. `/voice` clears the input before recording; `Ctrl+S` keeps what you've already typed. @@ -103,7 +89,7 @@ Voice input in the CLI uses the same transcription service as the Warp app. See The CLI shows its shortcuts in context, so you rarely need to memorize them: -* **Placeholder hints** - An empty input shows ghost-text hints for the current state, for example "Ask the agent anything • ? for shortcuts • ! for shell mode • / for commands" in agent mode, or "Run a shell command • ? for shortcuts • esc for agent mode" in shell mode. While a long-running command owns the input, the hint row shows "ctrl-c to interrupt". +* **Placeholder hints** - An empty input shows ghost-text hints for the current state, for example "Ask the agent anything • ? for shortcuts • ! for shell mode • / for commands" in agent mode, or "Run a shell command • ? for shortcuts • esc for agent mode" in shell mode. * **Shortcuts menu** - Type `?` in an empty input to open a shortcuts overview. Its contents adapt to what you're doing: agent mode lists the menu triggers and input history, shell mode shows how to return to agent mode, and extra sections appear during multi-agent sessions or agent-controlled terminal use. Press `Esc`, or start typing, to close it. ## Shell mode @@ -111,11 +97,11 @@ The CLI shows its shortcuts in context, so you rarely need to memorize them: The input is agent-first: by default, pressing `Enter` sends your text to the agent as a prompt. Use shell mode to run a command instead: 1. Press `!` at the start of the input. The prompt marker changes from `>` to `!`, and the statusline below the input shows **Shell mode**. -2. Type a command and press `Enter`. The command runs in the session's shell, and the input returns to agent mode. +2. Run a command. It executes in the session's shell, and the input returns to agent mode. To leave shell mode without running a command, press `Esc`, or press `Backspace` at the start of the input. Any text you typed stays in the input. -In the transcript, each command you run is marked with a `!` prefix and a highlighted row background, so shell commands stay visually distinct from prompts and agent responses. Output streams in below the command as it's produced. +In the transcript, each command you run is marked with a `!` prefix and a highlighted row background, so shell commands stay visually distinct from prompts and agent responses. In shell mode, press `Tab` to complete commands and paths; see [Tab completions](#tab-completions). From 62568aa4e08ed2048abecc3224a9347ebf5a9f25 Mon Sep 17 00:00:00 2001 From: Hong Yi Chen <hongyigma@gmail.com> Date: Wed, 29 Jul 2026 16:28:47 -0700 Subject: [PATCH 07/12] docs(cli): address review comments on NLD and interrupt hint Rename the natural-language-detection bullet lead from "Biased toward the agent" to "Ambiguous input" so it states the behavior without characterizing the classifier, and drop the interrupt-hint bullet from long-running commands (Ctrl+C interrupt is already covered in Stopping commands and exiting). Co-Authored-By: Oz <oz-agent@warp.dev> --- src/content/docs/cli/input-and-editing.mdx | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/src/content/docs/cli/input-and-editing.mdx b/src/content/docs/cli/input-and-editing.mdx index c5c783d9..81ef54f3 100644 --- a/src/content/docs/cli/input-and-editing.mdx +++ b/src/content/docs/cli/input-and-editing.mdx @@ -115,7 +115,7 @@ Out of the box, the CLI never guesses what your input is: everything goes to the - **Toggle detection** - Run `/natural-language-detection` to turn detection on or off. The statusline confirms the change, and the setting persists across sessions. - **Automatic classification** - With detection on, the CLI classifies your input as you type. When the input looks like a shell command (for example, `git status`), the input switches to shell mode, and `Enter` runs it as a command. Everything else is sent to the agent. -- **Biased toward the agent** - Short or ambiguous input stays in agent mode, and a single word switches to shell mode only when it matches a command available in your shell. +- **Ambiguous input** - Short or ambiguous input stays in agent mode, and a single word switches to shell mode only when it matches a command available in your shell. The prompt marker and statusline always show the current mode before you press `Enter`. If detection classifies input differently than you intended, press `Esc` to switch back to agent mode, or press `!` at the start of the input to force shell mode. @@ -124,7 +124,6 @@ The prompt marker and statusline always show the current mode before you press ` When a command keeps running, such as a dev server, a package install, or an interactive prompt, the CLI hands input over to it: - **Input passthrough** - Keystrokes and pasted text are forwarded to the running process, so password requests, confirmation prompts, and other interactive programs work as they do in a plain terminal. -- **Interrupt hint** - While the command owns input, a dimmed `ctrl-c to interrupt` hint replaces the input. Press `Ctrl+C` to stop the command. - **Type ahead** - If you start typing your next command before the current one finishes, the typed characters are carried into the input when the command completes, with the cursor at the end. This matches type-ahead behavior in shells like zsh and bash. One command runs in the session at a time. If the terminal is already busy, for example while the agent is running a command of its own, submitting a shell command shows a notice in the statusline and keeps your text in the input. From 73cdeabf940611741ef3d033b367d2dc848e16d3 Mon Sep 17 00:00:00 2001 From: Hong Yi Chen <hongyigma@gmail.com> Date: Wed, 29 Jul 2026 16:38:39 -0700 Subject: [PATCH 08/12] docs(cli): apply orchestrator editorial audit Shorten the editing-basics intro, add the verified macOS/Linux Alt keybinding note, sharpen the history Submit/Dismiss bullets and drop the command-history sentence, fold the click-controls bullet into Selection and clipboard and remove the Mouse support section (no inbound #mouse-support links), trim the copied-to-clipboard footer narration, generalize the placeholder-hints bullet, simplify shell-mode step 2, and remove the transcript-styling sentence. Co-Authored-By: Oz <oz-agent@warp.dev> --- src/content/docs/cli/input-and-editing.mdx | 28 +++++++++------------- 1 file changed, 11 insertions(+), 17 deletions(-) diff --git a/src/content/docs/cli/input-and-editing.mdx b/src/content/docs/cli/input-and-editing.mdx index 81ef54f3..313c061d 100644 --- a/src/content/docs/cli/input-and-editing.mdx +++ b/src/content/docs/cli/input-and-editing.mdx @@ -11,13 +11,17 @@ The {VARS.WARP_CLI} is a full terminal as well as an agent: every session runs a ## Editing basics -The input accepts multiple lines and soft-wraps long lines to your terminal width. +The input is a multiline editor. * **Insert a newline** - Press `Ctrl+J`, or `Shift+Enter` in terminals that support distinguishing it. `Alt+Enter` also works. * **Edit with readline-style keys** - The editor supports familiar bindings such as `Ctrl+A` and `Ctrl+E` (start and end of line), `Ctrl+W` (delete the previous word), `Ctrl+K` and `Ctrl+U` (delete to the end or start of the line), `Ctrl+Y` (reinsert the last deleted text), and `Ctrl+Z` (undo). The full editing and selection table is in the [keyboard shortcuts reference](/cli/reference/#keyboard-shortcuts). +:::note +Bindings are identical on macOS and Linux. Shortcuts that use `Alt` require some macOS terminals' Option-as-Alt (Meta) setting. +::: + ## Slash commands Type `/` at the start of an empty input to open the slash command menu. Entries for toggles and pickers show their current state, for example `/theme (currently auto: Dark)` or `/auto-approve (currently off)`. @@ -34,10 +38,8 @@ Press `↑` with the cursor on the first row of the input to open the history me * **What's listed** - In agent mode, the menu combines your previous prompts and shell commands in one list, with commands marked by a `!` prefix. In [shell mode](#shell-mode), the menu lists commands only. * **Preview** - Moving the selection previews each entry in the input and switches the input to the matching mode: recalled commands run as shell commands, and recalled prompts go to the agent. -* **Submit** - Press `Enter` to run the selected command or send the selected prompt. -* **Dismiss** - Press `Esc` to close the menu and restore what you had typed. Pressing `↓` past the newest entry does the same. - -Commands you run in the CLI are added to your command history. +* **Submit** - `Enter` runs the selection immediately; it doesn't insert it for editing. +* **Dismiss** - `Esc` restores what you had typed; `↓` past the newest entry does the same. ## Tab completions @@ -46,18 +48,12 @@ In [shell mode](#shell-mode), press `Tab` to complete the command you're typing, * If exactly one completion matches, the CLI applies it immediately. * If several completions match, the CLI inserts the longest shared prefix and opens a completion menu. Press `Tab` again to cycle through the suggestions. -## Mouse support - -The CLI runs in your terminal, but the input is fully mouse-aware: - -* **Select text** - Drag to select. Double-click selects a word, and triple-click selects a line. -* **Click controls** - Interactive elements such as the **Voice** footer entry and the attachment bar controls respond to clicks. - ## Selection and clipboard -* **Highlight to copy** - Finishing a mouse selection in the input or the [conversation transcript](/cli/agent-conversations/) automatically copies it, and the footer briefly shows "copied to clipboard". +* **Highlight to copy** - Finishing a mouse selection in the input or the [conversation transcript](/cli/agent-conversations/) automatically copies it. * **Keyboard selection** - Extend the selection with `Shift` plus the arrow keys, or select everything with `Ctrl+Shift+A`. Copy with `Ctrl+Shift+C` and cut with `Ctrl+X`. * **Paste** - Press `Ctrl+V` or `Ctrl+Shift+V` (also `Alt+V` on Windows). Your terminal's own paste shortcut works as well. +* **Click controls** - Interactive elements such as the **Voice** footer entry and the attachment bar controls respond to clicks. :::note Copying works over SSH: on remote sessions the CLI writes the clipboard through the OSC 52 escape sequence (including tmux passthrough), so your local clipboard receives the text when your terminal supports OSC 52. @@ -89,7 +85,7 @@ Voice input in the CLI uses the same transcription service as the Warp app. See The CLI shows its shortcuts in context, so you rarely need to memorize them: -* **Placeholder hints** - An empty input shows ghost-text hints for the current state, for example "Ask the agent anything • ? for shortcuts • ! for shell mode • / for commands" in agent mode, or "Run a shell command • ? for shortcuts • esc for agent mode" in shell mode. +* **Placeholder hints** - An empty input shows the key triggers for the current mode. * **Shortcuts menu** - Type `?` in an empty input to open a shortcuts overview. Its contents adapt to what you're doing: agent mode lists the menu triggers and input history, shell mode shows how to return to agent mode, and extra sections appear during multi-agent sessions or agent-controlled terminal use. Press `Esc`, or start typing, to close it. ## Shell mode @@ -97,12 +93,10 @@ The CLI shows its shortcuts in context, so you rarely need to memorize them: The input is agent-first: by default, pressing `Enter` sends your text to the agent as a prompt. Use shell mode to run a command instead: 1. Press `!` at the start of the input. The prompt marker changes from `>` to `!`, and the statusline below the input shows **Shell mode**. -2. Run a command. It executes in the session's shell, and the input returns to agent mode. +2. Run a command. The input returns to agent mode afterward. To leave shell mode without running a command, press `Esc`, or press `Backspace` at the start of the input. Any text you typed stays in the input. -In the transcript, each command you run is marked with a `!` prefix and a highlighted row background, so shell commands stay visually distinct from prompts and agent responses. - In shell mode, press `Tab` to complete commands and paths; see [Tab completions](#tab-completions). :::note From 426800ff569a871f333b12d0a262462fbe16ce05 Mon Sep 17 00:00:00 2001 From: Hong Yi Chen <hongyigma@gmail.com> Date: Fri, 31 Jul 2026 16:56:49 -0700 Subject: [PATCH 09/12] docs(cli): repoint links to removed context and conversations pages The base branch merged context.mdx into configuration.mdx and folded the conversations page into agent-conversations.mdx. Repoint the skills link to /cli/configuration/#skills, and the two Managing conversations links to /cli/agent-conversations/#managing-conversations (verified both anchors exist in the merged base). Related pages now lists a single agent-conversations entry. Co-Authored-By: Oz <oz-agent@warp.dev> --- src/content/docs/cli/input-and-editing.mdx | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/src/content/docs/cli/input-and-editing.mdx b/src/content/docs/cli/input-and-editing.mdx index 313c061d..02c8c059 100644 --- a/src/content/docs/cli/input-and-editing.mdx +++ b/src/content/docs/cli/input-and-editing.mdx @@ -28,7 +28,7 @@ Type `/` at the start of an empty input to open the slash command menu. Entries When a command takes an argument, the input shows a ghost-text argument hint after the full command name, for example `/theme <auto|light|dark>`. -Your [skills](/cli/context/) also appear in the slash command menu, so you can invoke a skill by typing `/` followed by its name. +Your [skills](/cli/configuration/#skills) also appear in the slash command menu, so you can invoke a skill by typing `/` followed by its name. The [slash commands reference](/cli/reference/#slash-commands) lists every command. @@ -144,10 +144,9 @@ There are two other ways to exit: - **`Ctrl+D`** - Exits immediately when the input is empty. - **`/exit`** - Exits from the slash command menu. -When you exit, the CLI prints a command you can use to pick the conversation back up later. See [Managing conversations](/cli/conversations/) for resuming and switching conversations. +When you exit, the CLI prints a command you can use to pick the conversation back up later. See [Managing conversations](/cli/agent-conversations/#managing-conversations) for resuming and switching conversations. ## Related pages * [{VARS.WARP_CLI} reference](/cli/reference/) - Flags, environment variables, slash commands, and keyboard shortcuts. -* [Agent conversations in the {VARS.WARP_CLI}](/cli/agent-conversations/) - The transcript, tool calls, and diffs. -* [Managing conversations in the {VARS.WARP_CLI}](/cli/conversations/) - Persistence, resuming, and switching conversations. +* [Agent conversations in the {VARS.WARP_CLI}](/cli/agent-conversations/) - The transcript, tool calls, diffs, and managing conversations. From 7824074fd37d11d6d238733779fa9c6384959a48 Mon Sep 17 00:00:00 2001 From: Yunfan Yang <kevin@warp.dev> Date: Tue, 4 Aug 2026 01:06:10 -0400 Subject: [PATCH 10/12] docs(cli): clarify keyboard and voice support Co-Authored-By: Oz <oz-agent@warp.dev> --- src/content/docs/cli/input-and-editing.mdx | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/src/content/docs/cli/input-and-editing.mdx b/src/content/docs/cli/input-and-editing.mdx index 02c8c059..e96438f2 100644 --- a/src/content/docs/cli/input-and-editing.mdx +++ b/src/content/docs/cli/input-and-editing.mdx @@ -15,11 +15,12 @@ The input is a multiline editor. * **Insert a newline** - Press `Ctrl+J`, or `Shift+Enter` in terminals that support distinguishing it. `Alt+Enter` also works. * **Edit with readline-style keys** - The editor supports familiar bindings such as `Ctrl+A` and `Ctrl+E` (start and end of line), `Ctrl+W` (delete the previous word), `Ctrl+K` and `Ctrl+U` (delete to the end or start of the line), `Ctrl+Y` (reinsert the last deleted text), and `Ctrl+Z` (undo). +* **Use macOS Command shortcuts** - When the Kitty keyboard protocol is enabled in your terminal, the editor supports Command-modified shortcuts such as `⌘+X` to cut and `⌘+Shift+←` or `⌘+Shift+→` to extend the selection. The full editing and selection table is in the [keyboard shortcuts reference](/cli/reference/#keyboard-shortcuts). :::note -Bindings are identical on macOS and Linux. Shortcuts that use `Alt` require some macOS terminals' Option-as-Alt (Meta) setting. +Core `Ctrl` and `Alt` bindings are cross-platform. Shortcuts that use `Alt` require some macOS terminals' Option-as-Alt (Meta) setting. Command-modified shortcuts require a terminal with the Kitty keyboard protocol enabled. ::: ## Slash commands @@ -74,6 +75,10 @@ Attached images appear in an attachment bar above the input. Press `Tab` to focu Dictate prompts instead of typing them: +:::caution +Voice input isn't currently available on Linux. Linux support is planned. +::: + 1. Start listening with `Ctrl+S`, the `/voice` slash command, or by clicking **Voice** in the footer. The footer shows **Listening** while recording. 2. Press `Enter`, or click the footer entry again, to stop recording. The transcribed text lands in the input so you can review and edit it before submitting. From 94d0890fec9994ab01ba771b9aa2d9dc1bbb0d66 Mon Sep 17 00:00:00 2001 From: Yunfan Yang <kevin@warp.dev> Date: Tue, 4 Aug 2026 01:15:09 -0400 Subject: [PATCH 11/12] docs(cli): clarify Linux voice packaging Co-Authored-By: Oz <oz-agent@warp.dev> --- src/content/docs/cli/input-and-editing.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/cli/input-and-editing.mdx b/src/content/docs/cli/input-and-editing.mdx index e96438f2..32451d49 100644 --- a/src/content/docs/cli/input-and-editing.mdx +++ b/src/content/docs/cli/input-and-editing.mdx @@ -76,7 +76,7 @@ Attached images appear in an attachment bar above the input. Press `Tab` to focu Dictate prompts instead of typing them: :::caution -Voice input isn't currently available on Linux. Linux support is planned. +Voice input isn't currently included in the official Linux build. Linux support is planned. ::: 1. Start listening with `Ctrl+S`, the `/voice` slash command, or by clicking **Voice** in the footer. The footer shows **Listening** while recording. From 655e752f680abb0026c27a31dffdc7a4c179c1fd Mon Sep 17 00:00:00 2001 From: Yunfan Yang <kevin@warp.dev> Date: Tue, 4 Aug 2026 01:23:34 -0400 Subject: [PATCH 12/12] docs(cli): fix renamed agent docs links Co-Authored-By: Oz <oz-agent@warp.dev> --- src/content/docs/cli/agent-conversations.mdx | 8 ++++---- src/content/docs/cli/configuration.mdx | 18 ++++++++--------- src/content/docs/cli/input-and-editing.mdx | 2 +- src/content/docs/cli/models-and-usage.mdx | 20 +++++++++---------- .../docs/cli/permissions-and-profiles.mdx | 4 ++-- src/content/docs/cli/reference.mdx | 2 +- 6 files changed, 27 insertions(+), 27 deletions(-) diff --git a/src/content/docs/cli/agent-conversations.mdx b/src/content/docs/cli/agent-conversations.mdx index ab1e139a..493593bd 100644 --- a/src/content/docs/cli/agent-conversations.mdx +++ b/src/content/docs/cli/agent-conversations.mdx @@ -56,7 +56,7 @@ For multi-step work, the agent tracks its progress with a task list rendered dir Canceled tasks appear struck through. As the agent finishes tasks, compact confirmation rows (e.g., `✓ Completed <task> (2/5)`) track progress without repeating the whole list. -Task lists in the CLI reflect the same agent behavior as in the Warp app. Learn more about [how task lists work](/agent-platform/capabilities/task-lists/). +Task lists in the CLI reflect the same agent behavior as in the Warp app. Learn more about [how task lists work](/agents/capabilities/task-lists/). ## Planning @@ -64,7 +64,7 @@ To have the agent first research and produce a plan before making changes, use t The plan renders inline in the transcript as a formatted document with its own header row showing the plan's status. An `Updated plan` entry appears when the agent revises it. Press `Ctrl+Shift+P` to expand or collapse the latest plan. -Planning in the CLI follows the same workflow as the Warp app. See [Planning](/agent-platform/capabilities/planning/) to learn how to create, review, and execute plans. +Planning in the CLI follows the same workflow as the Warp app. See [Planning](/agents/capabilities/planning/) to learn how to create, review, and execute plans. ## Selecting and copying output @@ -142,5 +142,5 @@ After compaction, a collapsed **Conversation summary** block appears in the tran * **[Running shell commands](/cli/shell-commands/)** - How commands the agent (or you) run appear in the transcript. * **[Cloud handoff and orchestration](/cli/cloud-and-orchestration/)** - Hand off conversations to cloud agents and resume cloud runs. * **[{VARS.WARP_CLI} reference](/cli/reference/)** - Command-line flags, slash commands, and keyboard shortcuts. -* **[Planning](/agent-platform/capabilities/planning/)** - The full planning workflow. -* **[Task lists](/agent-platform/capabilities/task-lists/)** - How agents create and update task lists. +* **[Planning](/agents/capabilities/planning/)** - The full planning workflow. +* **[Task lists](/agents/capabilities/task-lists/)** - How agents create and update task lists. diff --git a/src/content/docs/cli/configuration.mdx b/src/content/docs/cli/configuration.mdx index d4983f6a..c595ebf1 100644 --- a/src/content/docs/cli/configuration.mdx +++ b/src/content/docs/cli/configuration.mdx @@ -107,16 +107,16 @@ The agent works in your session's current directory. When you `cd`, project rule Within a project, the CLI picks up the same rule files as the Warp app: -* **Project rules** - `AGENTS.md` (or `WARP.md`) files in your repository apply automatically, starting from the repository root and your current directory. See [Rules](/agent-platform/capabilities/rules/) for the file format, nested rules in subdirectories, and precedence. +* **Project rules** - `AGENTS.md` (or `WARP.md`) files in your repository apply automatically, starting from the repository root and your current directory. See [Rules](/agents/capabilities/rules/) for the file format, nested rules in subdirectories, and precedence. * **Global rules** - A rule file at `~/.agents/AGENTS.md` applies across all projects on your machine. Because rules and skills come from the same shared locations, a repository already configured for agents in the Warp app (or any tool that reads `AGENTS.md`) works in the CLI immediately. ## Skills -[Skills](/agent-platform/capabilities/skills/) are reusable instruction sets the agent can invoke to perform specific tasks. The CLI discovers the same skills as the Warp app. Project skills come from your repository's skill directories (e.g., `.agents/skills/`), and personal skills come from your home directory (e.g., `~/.agents/skills/`), scoped to your current working directory. +[Skills](/agents/capabilities/skills/) are reusable instruction sets the agent can invoke to perform specific tasks. The CLI discovers the same skills as the Warp app. Project skills come from your repository's skill directories (e.g., `.agents/skills/`), and personal skills come from your home directory (e.g., `~/.agents/skills/`), scoped to your current working directory. -Run `/skills` to browse every skill in scope. Selecting a skill inserts `/skill-name` into the input so you can add extra instructions before running it. Any text after the skill name is passed along, either as [skill arguments](/agent-platform/capabilities/skills/#skill-arguments) or as additional context for the agent. You can also invoke a skill directly by typing `/` followed by its name, for example `/deploy push the latest changes to staging`. +Run `/skills` to browse every skill in scope. Selecting a skill inserts `/skill-name` into the input so you can add extra instructions before running it. Any text after the skill name is passed along, either as [skill arguments](/agents/capabilities/skills/#skill-arguments) or as additional context for the agent. You can also invoke a skill directly by typing `/` followed by its name, for example `/deploy push the latest changes to staging`. ### Bundled skills @@ -127,9 +127,9 @@ The CLI ships with built-in skills that appear in the skills menu alongside your ## MCP servers -[MCP servers](/agent-platform/capabilities/mcp/) extend the agent with external tools and data sources. The CLI keeps its own MCP server configuration, separate from the Warp app's, so each can run its own set of servers. +[MCP servers](/agents/capabilities/mcp/) extend the agent with external tools and data sources. The CLI keeps its own MCP server configuration, separate from the Warp app's, so each can run its own set of servers. -Servers are defined in a JSON config file using the same `mcpServers` format as [file-based MCP servers](/agent-platform/capabilities/mcp/#file-based-mcp-servers) in the Warp app (on macOS, the file is `~/.warp_cli/.mcp.json`). Edit the file to add or remove servers. The CLI picks up changes automatically. Configured servers start automatically once you're logged in. +Servers are defined in a JSON config file using the same `mcpServers` format as [file-based MCP servers](/agents/capabilities/mcp/#file-based-mcp-servers) in the Warp app (on macOS, the file is `~/.warp_cli/.mcp.json`). Edit the file to add or remove servers. The CLI picks up changes automatically. Configured servers start automatically once you're logged in. :::note The CLI reads MCP servers from its global config file only. Project-scoped MCP config files in repositories are not detected. To copy global server definitions from the Warp app, use the `/tui-migrate-setup` bundled skill. @@ -145,8 +145,8 @@ Press `Enter` on a server to start, stop, or retry it depending on its state. Fa ## Related pages -* [Rules](/agent-platform/capabilities/rules/) - Full guide to project and global rules -* [Skills](/agent-platform/capabilities/skills/) - Authoring skills, skill arguments, and skill locations -* [MCP servers](/agent-platform/capabilities/mcp/) - Config format, server examples, and authentication -* [Codebase Context](/agent-platform/capabilities/codebase-context/) - Codebase indexing in the Warp app +* [Rules](/agents/capabilities/rules/) - Full guide to project and global rules +* [Skills](/agents/capabilities/skills/) - Authoring skills, skill arguments, and skill locations +* [MCP servers](/agents/capabilities/mcp/) - Config format, server examples, and authentication +* [Codebase Context](/agents/capabilities/codebase-context/) - Codebase indexing in the Warp app * [{VARS.WARP_CLI} reference](/cli/reference/) - Command-line flags, slash commands, and keyboard shortcuts diff --git a/src/content/docs/cli/input-and-editing.mdx b/src/content/docs/cli/input-and-editing.mdx index 32451d49..f3e5b8b6 100644 --- a/src/content/docs/cli/input-and-editing.mdx +++ b/src/content/docs/cli/input-and-editing.mdx @@ -84,7 +84,7 @@ Voice input isn't currently included in the official Linux build. Linux support Press `Esc` while transcription is in progress to cancel it. `/voice` clears the input before recording; `Ctrl+S` keeps what you've already typed. -Voice input in the CLI uses the same transcription service as the Warp app. See [voice input for agents](/agent-platform/local-agents/interacting-with-agents/voice/) for microphone setup, privacy, and usage limits. +Voice input in the CLI uses the same transcription service as the Warp app. See [voice input for agents](/agents/local-agents/interacting-with-agents/voice/) for microphone setup, privacy, and usage limits. ## Keyboard hints and the shortcuts menu diff --git a/src/content/docs/cli/models-and-usage.mdx b/src/content/docs/cli/models-and-usage.mdx index e21787b8..6e26ff81 100644 --- a/src/content/docs/cli/models-and-usage.mdx +++ b/src/content/docs/cli/models-and-usage.mdx @@ -14,30 +14,30 @@ Run `/model` to open the model picker. You can also click the model name in the Models that your plan or your team's settings don't allow appear disabled in the picker. -Your choice is saved as the base model of your active profile, so it persists across sessions. See [permissions and profiles](/cli/permissions-and-profiles/) for how profiles work in the CLI. For the full list of supported models and to learn more about how Warp's Auto models pick for you, see [Model choice](/agent-platform/inference/model-choice/). +Your choice is saved as the base model of your active profile, so it persists across sessions. See [permissions and profiles](/cli/permissions-and-profiles/) for how profiles work in the CLI. For the full list of supported models and to learn more about how Warp's Auto models pick for you, see [Model choice](/agents/inference/model-choice/). ## Bring your own API key -The CLI supports [Bring Your Own API Key (BYOK)](/agent-platform/inference/bring-your-own-api-key/) for OpenAI, Anthropic, and Google models, and can connect an [X Premium or SuperGrok subscription](/agent-platform/inference/grok-subscription/) for Grok models. When you select a model covered by one of your keys, requests are billed through your provider account and don't consume your Warp [credits](/support-and-community/plans-and-billing/credits/). +The CLI supports [Bring Your Own API Key (BYOK)](/agents/inference/bring-your-own-api-key/) for OpenAI, Anthropic, and Google models, and can connect an [X Premium or SuperGrok subscription](/agents/inference/grok-subscription/) for Grok models. When you select a model covered by one of your keys, requests are billed through your provider account and don't consume your Warp [credits](/support-and-community/plans-and-billing/credits/). Run `/api-keys` to open the key management menu. It lists each provider with its connection state, plus a Warp credit fallback toggle: * **Set a key** - Press `Enter` on OpenAI, Anthropic, or Google and enter the key. Input is masked, so the key never appears in your transcript or shell history, and it's saved to your device's secure storage. Warp does not store provider keys on its servers. * **Replace or clear a key** - On a connected provider, `Enter` loads the stored key (still masked) for editing, and saving an empty field clears it. `Ctrl+X` clears the highlighted provider's key from the list. * **Connect X Premium or SuperGrok** - Press `Enter` on the subscription row and the CLI opens your browser to sign in to your xAI account. `Ctrl+X` disconnects it. -* **Warp credit fallback** - Press `Enter` to toggle whether a request that fails through your key is retried with Warp credits. See [failover and fallback behavior](/agent-platform/inference/bring-your-own-api-key/#failover-and-fallback-behavior). +* **Warp credit fallback** - Press `Enter` to toggle whether a request that fails through your key is retried with Warp credits. See [failover and fallback behavior](/agents/inference/bring-your-own-api-key/#failover-and-fallback-behavior). You can also store or clear keys outside a session with the `--set-provider-api-key` and `--clear-provider-api-key` flags. See the [{VARS.WARP_CLI} reference](/cli/reference/#command-line-flags). X Premium/SuperGrok connections can only be managed through `/api-keys`. :::note -Warp's built-in Auto models always consume Warp credits, even with BYOK configured. To bill through your own account, select a specific provider model, or use a [custom router](/agent-platform/inference/custom-routers/#using-your-own-api-keys-byok) whose targets your keys cover. See [BYOK usage and billing behavior](/agent-platform/inference/bring-your-own-api-key/#byok-usage-and-billing-behavior) for the full rules. +Warp's built-in Auto models always consume Warp credits, even with BYOK configured. To bill through your own account, select a specific provider model, or use a [custom router](/agents/inference/custom-routers/#using-your-own-api-keys-byok) whose targets your keys cover. See [BYOK usage and billing behavior](/agents/inference/bring-your-own-api-key/#byok-usage-and-billing-behavior) for the full rules. ::: ## Custom model routing -[Custom routers](/agent-platform/inference/custom-routers/) appear in the `/model` picker alongside individual models. Select one and each prompt resolves to a concrete model using the routing logic you defined. +[Custom routers](/agents/inference/custom-routers/) appear in the `/model` picker alongside individual models. Select one and each prompt resolves to a concrete model using the routing logic you defined. -The CLI loads the same router definitions as the Warp app. These are YAML files in `~/.warp/custom_model_routers/`, plus any team-synced routers your admin shares. [Authoring a router as a file](/agent-platform/inference/custom-routers/#author-a-router-as-a-file) documents the file format. +The CLI loads the same router definitions as the Warp app. These are YAML files in `~/.warp/custom_model_routers/`, plus any team-synced routers your admin shares. [Authoring a router as a file](/agents/inference/custom-routers/#author-a-router-as-a-file) documents the file format. ## Usage and cost @@ -50,8 +50,8 @@ Credits are Warp's unit of usage for agent requests. For what credits cover and ## Related pages -* [Model choice](/agent-platform/inference/model-choice/) - Supported models and how automatic model selection works. -* [Bring Your Own API Key](/agent-platform/inference/bring-your-own-api-key/) - How BYOK works, key storage, and billing behavior. -* [SuperGrok subscription](/agent-platform/inference/grok-subscription/) - Use Grok models through your xAI account. -* [Custom routers](/agent-platform/inference/custom-routers/) - Define routing logic that picks a model per task. +* [Model choice](/agents/inference/model-choice/) - Supported models and how automatic model selection works. +* [Bring Your Own API Key](/agents/inference/bring-your-own-api-key/) - How BYOK works, key storage, and billing behavior. +* [SuperGrok subscription](/agents/inference/grok-subscription/) - Use Grok models through your xAI account. +* [Custom routers](/agents/inference/custom-routers/) - Define routing logic that picks a model per task. * [{VARS.WARP_CLI} reference](/cli/reference/) - Flags and slash commands, including the API key commands. diff --git a/src/content/docs/cli/permissions-and-profiles.mdx b/src/content/docs/cli/permissions-and-profiles.mdx index 92ac3c15..d3057e43 100644 --- a/src/content/docs/cli/permissions-and-profiles.mdx +++ b/src/content/docs/cli/permissions-and-profiles.mdx @@ -6,7 +6,7 @@ description: >- --- import { VARS } from '@data/vars'; -The {VARS.WARP_CLI} uses the same permission model as the Warp app: you choose how much approval each type of action needs. This page covers how to set permissions in the CLI, what happens when the agent asks for approval, and how to grant full autonomy with auto-approve. For the full permission model, including team-wide controls, see [Profiles & Permissions](/agent-platform/capabilities/agent-profiles-permissions/). +The {VARS.WARP_CLI} uses the same permission model as the Warp app: you choose how much approval each type of action needs. This page covers how to set permissions in the CLI, what happens when the agent asks for approval, and how to grant full autonomy with auto-approve. For the full permission model, including team-wide controls, see [Profiles & Permissions](/agents/capabilities/agent-profiles-permissions/). ## How permissions work @@ -97,6 +97,6 @@ The profile collection is validated as a whole. If any profile contains an inval ## Related pages -* [Profiles & Permissions](/agent-platform/capabilities/agent-profiles-permissions/) - The full permission model, autonomy levels, and allowlist/denylist behavior. +* [Profiles & Permissions](/agents/capabilities/agent-profiles-permissions/) - The full permission model, autonomy levels, and allowlist/denylist behavior. * [Configuring the {VARS.WARP_CLI}](/cli/configuration/) - The settings file, themes, statusline, and keybindings. * [Agent conversations in the {VARS.WARP_CLI}](/cli/agent-conversations/) - How tool calls, diffs, and agent questions render in the transcript. diff --git a/src/content/docs/cli/reference.mdx b/src/content/docs/cli/reference.mdx index af79bf9d..a381737f 100644 --- a/src/content/docs/cli/reference.mdx +++ b/src/content/docs/cli/reference.mdx @@ -56,7 +56,7 @@ Create a key in the Warp app under **Settings** > **Platform**; see the [API key ### `--set-provider-api-key` -Securely stores a model-provider API key for [Bring Your Own API Key (BYOK)](/agent-platform/inference/bring-your-own-api-key/), then exits. The provider is one of `openai`, `anthropic`, or `google`. +Securely stores a model-provider API key for [Bring Your Own API Key (BYOK)](/agents/inference/bring-your-own-api-key/), then exits. The provider is one of `openai`, `anthropic`, or `google`. ```bash warp --set-provider-api-key anthropic