docs(cli): input and shell commands by hongyi-chen · Pull Request #406 · warpdotdev/docs

hongyi-chen · 2026-07-28T21:35:11Z

Pages changed

src/content/docs/cli/input-and-editing.mdx (stub to full draft, now titled "Input and shell commands in the Warp CLI")

Consolidation note: this PR absorbs the content of PR #403 (cli/shell-commands.mdx, which will be closed). The orchestrator deletes shell-commands.mdx and renames this page's slug to input-and-shell-commands at integration.

Features covered

Input and editing:

Editing basics: multiline input, soft wrap, six-row viewport, newline keys (Ctrl+J / Shift+Enter / Alt+Enter), readline-style editing keys
Slash command menu: / trigger, filtering, current-state suffixes (e.g. /theme, /auto-approve), ghost-text argument hints (e.g. /theme <auto|light|dark>), skills in the menu; links to cli/reference for the full table
Input history (merged section): up-arrow menu combining prompts + !-prefixed commands (commands-only in shell mode), filter, mode-switching preview, submit-on-Enter, Esc restore
Tab completions (shell mode): single-match auto-apply, longest-common-prefix insert + menu, Tab/Down cycle, Enter accept
Mouse support: click-to-position cursor, drag/double-click/triple-click selection, wheel scrolling, clickable footer + attachment-bar controls
Selection and clipboard: highlight-to-copy with "copied to clipboard" notice, keyboard selection/copy/cut keys, paste keys, OSC 52 copy over SSH (with tmux passthrough)
Image attachments: clipboard image paste, image file-path paste/drop, PNG/JPEG/GIF/WebP, agent-mode lock, attachment bar navigation
Voice input: /voice, Ctrl+S, footer Voice control, Listening/Transcribing states, Enter-to-transcribe, Esc-to-cancel; cross-links the agent-platform voice page
Keyboard hints: contextual placeholder ghost text and the ? shortcuts menu with adaptive sections

Shell commands (absorbed from #403):

Shell mode: agent-first input, ! prefix to enter, Esc/Backspace to exit, > vs ! prompt marker, Shell mode statusline label, !-prefixed highlighted command rows in the transcript, note that running a command cancels an in-progress agent response
Natural language detection: off by default (opt-in), /natural-language-detection toggle persists across sessions, agent-biased classification (single tokens switch only with command evidence)
Long-running/interactive commands: input passthrough, dimmed "ctrl-c to interrupt" hint, typed-character carryover (shell type-ahead), one-command-at-a-time notice
Full-screen (alt-screen) apps: full-area rendering, keyboard/paste/scroll/mouse forwarding, transcript restored on exit
Ctrl+C semantics: interrupt running command (never exits), cancel streaming response, clear input, "ctrl-c again to exit" 1s double-press window; Ctrl+D on empty input and /exit; pointer to conversations page for resume

Dropped/unconfirmed

From this PR's original scope:

Vim mode: not merged to warp master; no vim wiring or setting in the CLI runtime (only listed as a follow-up in the input-view tech spec). Section removed.
Clicking inline menu rows: inline menus (slash/history/completions) have no mouse handling on master; menu rows are keyboard-driven. Claim removed; other mouse support is documented.
Configurable voice keybinding / keybinding remapping: the CLI registers remappable-by-name bindings but does not load keybindings.yaml overrides yet (loading is explicitly a follow-up, and the GUI's keybinding-loading launch path is unreachable for the CLI). Documented Ctrl+S as fixed, with no configurability claims.
"Opt-in" auto-copy on selection: highlight-to-copy is unconditional in the CLI (no opt-in/opt-out setting; terminal.copy_on_select is GUI-surfaced only). Documented the actual always-on behavior; flagging for eng review in case an opt-in setting lands before launch.

Carried over from #403:

Manual attach (CODE-1915): no commits on master or any branch reference this ticket; not shipped, so it is not documented.
Command row color: documented as a ! marker + highlighted row background without naming a color (plan mentioned yellow rows; current master uses a theme-blended tint).

Notes for review

Anchors /cli/reference/#keyboard-shortcuts and /cli/reference/#slash-commands assume the reference stub's current H2s keep their names.
Merging the two history sections surfaced a conflict: my original draft said Enter inserts the recalled entry for editing; code confirms accepting a history entry submits it immediately (handle_accepted_prompt_and_command_history calls handle_submitted). The merged section documents submit-on-Enter.
Confirm always-on highlight-to-copy is the intended launch behavior.
npm run build passes (363 pages); built title verified as "Input and shell commands in the Warp CLI".

Suggested reviewer(s): Kevin, moira

Co-Authored-By: Oz oz-agent@warp.dev

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 <oz-agent@warp.dev>

vercel · 2026-07-28T21:35:17Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
docs	Ready	Preview	Jul 29, 2026 11:41pm

oz-for-oss · 2026-07-28T21:35:23Z

@hongyi-chen

I'm starting a first review of this pull request.

You can view the conversation on Warp.

I completed the review and no human review was requested for this pull request.

Comment /oz-review on this pull request to retrigger a review (up to 3 times on the same pull request).

Powered by Oz

oz-for-oss

Overview

This PR expands the Warp CLI input and editing page from a stub into a full feature document covering editing, slash commands, history, shell completions, mouse support, clipboard behavior, image attachments, voice input, and keyboard hints. I reviewed the changed docs against the annotated diff, the security checklist, and the provided spec context.

Concerns

No blocking concerns found. The provided spec context states that no approved or repository spec context was found, and the docs-only diff does not introduce security-sensitive code or configuration.

Verdict

Found: 0 critical, 0 important, 0 suggestions

Approve

Comment /oz-review on this pull request to retrigger a review (up to 3 times on the same pull request).

Powered by Oz

{{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 <title> now reads "Input and editing in the Warp CLI". Co-Authored-By: Oz <oz-agent@warp.dev>

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>

…cli-cli-input

Launch name confirmed as Warp Agent CLI. Base branch merge picks up the WARP_CLI var change (e2aebe3) 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>

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>

hongyi-chen · 2026-07-29T23:23:18Z

+
+- **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.


no need to mention biased towards the agent

Done in 62568aa: renamed the bullet lead to "Ambiguous input" so it states the behavior without characterizing the classifier bias.

hongyi-chen · 2026-07-29T23:23:40Z

+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.


feels like an implementation detail, does this matter? prob not worth mentioning as well

Done in 62568aa: removed the interrupt-hint bullet. Ctrl+C interrupt behavior is still covered under "Stopping commands and exiting".

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>

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>

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>

cla-bot Bot added the cla-signed label Jul 28, 2026

vercel Bot deployed to Preview July 28, 2026 21:37 View deployment

oz-for-oss Bot reviewed Jul 28, 2026

View reviewed changes

vercel Bot deployed to Preview July 28, 2026 21:48 View deployment

hongyi-chen changed the title ~~docs(cli): input and editing~~ docs(cli): input and shell commands Jul 28, 2026

vercel Bot deployed to Preview July 28, 2026 22:01 View deployment

hongyi-chen mentioned this pull request Jul 28, 2026

docs(cli): shell commands #403

Closed

hongyi-chen and others added 2 commits July 28, 2026 15:03

Merge remote-tracking branch 'origin/hyc/launch-cli' into hyc/launch-…

46adfbc

…cli-cli-input

vercel Bot deployed to Preview July 28, 2026 22:09 View deployment

hongyi-chen mentioned this pull request Jul 29, 2026

docs: Warp Agent CLI launch documentation #411

Draft

5 tasks

vercel Bot deployed to Preview July 29, 2026 23:11 View deployment

hongyi-chen commented Jul 29, 2026

View reviewed changes

hongyi-chen and others added 2 commits July 29, 2026 16:26

vercel Bot deployed to Preview July 29, 2026 23:31 View deployment

vercel Bot deployed to Preview July 29, 2026 23:41 View deployment

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

docs(cli): input and shell commands - #406

docs(cli): input and shell commands#406
hongyi-chen wants to merge 9 commits into
hyc/launch-clifrom
hyc/launch-cli-cli-input

hongyi-chen commented Jul 28, 2026 •

edited

Loading

Uh oh!

vercel Bot commented Jul 28, 2026 •

edited

Loading

Uh oh!

oz-for-oss Bot commented Jul 28, 2026 •

edited

Loading

Uh oh!

oz-for-oss Bot left a comment

Uh oh!

hongyi-chen Jul 29, 2026

Uh oh!

hongyi-chen Jul 29, 2026

Uh oh!

hongyi-chen Jul 29, 2026

Uh oh!

hongyi-chen Jul 29, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Uh oh!

Conversation

hongyi-chen commented Jul 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Pages changed

Features covered

Dropped/unconfirmed

Notes for review

Uh oh!

vercel Bot commented Jul 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

oz-for-oss Bot commented Jul 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

oz-for-oss Bot left a comment

Choose a reason for hiding this comment

Overview

Concerns

Verdict

Uh oh!

hongyi-chen Jul 29, 2026

Choose a reason for hiding this comment

Uh oh!

hongyi-chen Jul 29, 2026

Choose a reason for hiding this comment

Uh oh!

hongyi-chen Jul 29, 2026

Choose a reason for hiding this comment

Uh oh!

hongyi-chen Jul 29, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

hongyi-chen commented Jul 28, 2026 •

edited

Loading

vercel Bot commented Jul 28, 2026 •

edited

Loading

oz-for-oss Bot commented Jul 28, 2026 •

edited

Loading