docs(cli): models and usage + reference with troubleshooting - #405
Merged
Conversation
Fill in the three cli-reference pages from the Warp CLI launch skeleton: - cli/reference: command-line flags with examples, environment variables, full slash-command table (25 commands verified against the CLI command registry), and default keyboard shortcuts sourced from the CLI keybinding definitions. - cli/models-and-usage: /model picker and footer model entry, BYOK via /add-api-key + provider flags (OpenAI/Anthropic/Google), custom model routers in the picker, and cost transparency (footer credits toggle, /cost per-response summary). - cli/troubleshooting: /view-logs bundling and log locations, login troubleshooting, autoupdate behavior with /version and --version, and support links. Co-Authored-By: Oz <oz-agent@warp.dev>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
Contributor
|
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 Powered by Oz |
![oz-for-oss[bot]](https://avatars.githubusercontent.com/in/3450139?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Overview
This PR replaces placeholder CLI documentation with reference, model/usage, and troubleshooting content. The general structure is solid, but the API-key examples need safer secret-handling guidance before merge.
Concerns
- The
--api-keyexample encourages putting a Warp API key directly in the command line, where it can be captured in shell history or process listings. - The provider-key stdin example uses a plaintext
key.txtfile without warning users to avoid persistent or checked-in secret files.
Security
- Update the API-key examples to prefer
WARP_API_KEYor clearly warn about command-line exposure. - Add a caveat for stdin-based provider keys so users use a secure temporary file or secret-manager output rather than a long-lived plaintext file.
Verdict
Found: 0 critical, 1 important, 1 suggestions
Request changes
Comment /oz-review on this pull request to retrigger a review (up to 3 times on the same pull request).
Powered by Oz
| Authenticates with a Warp API key instead of the interactive browser login. Useful on hosts where a browser sign-in is inconvenient. | ||
|
|
||
| ```bash | ||
| warp --api-key YOUR_API_KEY |
Contributor
There was a problem hiding this comment.
WARP_API_KEY=YOUR_API_KEY warp as the primary example, or add an explicit warning before documenting --api-key.
Collaborator
Author
There was a problem hiding this comment.
Fixed in 1c6b6ae: WARP_API_KEY=YOUR_API_KEY warp is now the primary non-interactive auth example; --api-key stays documented secondarily with a caution that command-line arguments can be captured in shell history and process listings. The troubleshooting sign-in section now also lists the environment variable first.
| The CLI prompts for the key with masked input, so the key never appears in your shell history. When stdin is piped, the key is read from stdin instead: | ||
|
|
||
| ```bash | ||
| warp --set-provider-api-key anthropic < key.txt |
Contributor
There was a problem hiding this comment.
💡 [SUGGESTION] [SECURITY] The stdin example should warn users not to keep provider keys in a persistent plaintext key.txt file; suggest using a secure temporary file or piping from a secret manager and deleting any local file afterward.
Collaborator
Author
There was a problem hiding this comment.
Fixed in 1c6b6ae: the stdin example now pipes from a secret manager (tool-agnostic placeholder) instead of a persistent key.txt, with a note to avoid plaintext key files and delete any temporary file immediately afterward.
Frontmatter {{WARP_CLI}} tokens are not substituted by the build (Astro's
content layer parses frontmatter outside Vite), so built titles showed the
raw token. Body prose keeps {VARS.WARP_CLI}.
Co-Authored-By: Oz <oz-agent@warp.dev>
Consolidation: the standalone troubleshooting page merges into cli/reference.mdx as a final Troubleshooting section with problem-oriented H3 subsections. Existing H2 anchors (#slash-commands, #keyboard-shortcuts) are unchanged; internal links now point at #updating and #command-line-flags. troubleshooting.mdx is restored to the base-branch stub (the orchestrator removes it at integration). Co-Authored-By: Oz <oz-agent@warp.dev>
hongyi-chen
changed the title
…cli-cli-reference
Follows the base-branch WARP_CLI var value change; body prose picks up the
new name automatically via {VARS.WARP_CLI}.
Co-Authored-By: Oz <oz-agent@warp.dev>
4 tasks
Address review feedback: - Make WARP_API_KEY=... warp the primary non-interactive auth example and document --api-key secondarily with a caution that command-line arguments can be captured in shell history and process listings. - Replace the persistent key.txt stdin example with a tool-agnostic secret-manager pipe and a note against staging keys in plaintext files. Co-Authored-By: Oz <oz-agent@warp.dev>
Reduce product-name density after each page's intro (prefer "the CLI"), vary repeated trailing "See [X]" sentences, and fold two cross-links into their sentences. No structural, factual, heading, or link-target changes. Co-Authored-By: Oz <oz-agent@warp.dev>
Cut the type-to-filter/arrows/Enter sentence from the model picker prose and the keep-typing-to-filter clause from the slash-command intro, per the editorial bar against narrating self-evident UI mechanics. Defaults, exceptions, and lookup tables are unchanged. Co-Authored-By: Oz <oz-agent@warp.dev>
Platform audit: every keybinding registration is identical on macOS and Linux (the only platform-conditional binding is a Windows-only Alt+V paste, which is not documented since no Windows build ships). Input arrives as terminal key events, so Alt shortcuts depend on the host terminal delivering Option as Alt on macOS; add one note to the keyboard shortcuts section instead of per-row annotations. Co-Authored-By: Oz <oz-agent@warp.dev>
Co-Authored-By: Oz <oz-agent@warp.dev>
harryalbert
approved these changes
Jul 30, 2026
harryalbert
left a comment
harryalbert
left a comment
Contributor
There was a problem hiding this comment.
approving to unblock but worth a rewrite of the api keys section because I just merged a change that significantly changes that flow
| {/* TODO(cli-reference): draft per drafts/warp-cli-launch-plan.md — "cli/models-and-usage.mdx" section. Feature-doc content type. */} | ||
|
|
||
| The {VARS.WARP_CLI} documentation for this page is in progress. | ||
| The {VARS.WARP_CLI} gives you the same model options as the Warp app: pick the model that powers your conversations, bring your own provider API keys, route requests through custom model routers, and see what every response costs as you work. |
Contributor
There was a problem hiding this comment.
was keeping {VARS.WARP_CLI} here intentional?
Collaborator
Author
There was a problem hiding this comment.
Yes, intentional. {VARS.WARP_CLI} works in body prose (real MDX import), but the {{WARP_CLI}} tokens in frontmatter weren't being substituted at build time (Astro's content layer parses frontmatter outside Vite), so built page titles showed the raw token — hence hardcoding just the frontmatter title/description (commits 68bd887/4bed38a) while body prose keeps the variable. Other cli/ pages still using {{WARP_CLI}} frontmatter are base-branch stubs that will need the same treatment at integration.
| {/* TODO(cli-reference): /add-api-key, /clear-provider-api-key, --set-provider-api-key, --clear-provider-api-key; supported providers; cross-link agent-platform/inference/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. 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/). | ||
|
|
||
| To store a key, run `/add-api-key` with one of `openai`, `anthropic`, or `google`: |
Contributor
There was a problem hiding this comment.
Could you ask an agent to rewrite this section? I just merged this PR which updates the api key flow and makes it a lot better/clearer in-app
Collaborator
Author
There was a problem hiding this comment.
Rewrote in be16142 against the merged /api-keys flow (warpdotdev/warp#14472 + CODE-1930 spec). The section now covers the /api-keys menu: masked set/replace/clear for OpenAI/Anthropic/Google (saving an empty field or Ctrl+X clears), X Premium/SuperGrok connection via browser sign-in, and the Warp credit fallback toggle. Kept --set-provider-api-key/--clear-provider-api-key documented for scripting since the spec explicitly preserves them, with a note that X Premium/SuperGrok is managed only through /api-keys.
| The {VARS.WARP_CLI} documentation for this page is in progress. | ||
| This page is a lookup reference for the {VARS.WARP_CLI}: the flags and environment variables the `warp` command accepts, every slash command available in a session, the default keyboard shortcuts, and fixes for common issues. | ||
|
|
||
| ## Command-line flags |
Contributor
There was a problem hiding this comment.
probably merged after these docs were written, but there's now also a --fast-forward flag that auto-enables fast forward for TUI conversations (just for the session where that flag was ran)
Collaborator
Author
There was a problem hiding this comment.
Added in be16142 — one naming note: the flag landed as --auto-approve (warpdotdev/warp#14483), matching the TUI's /auto-approve naming; there's no --fast-forward in TuiArgs on master. Documented with the session-scoped behavior: new conversations in that launch start with auto-approve on, still toggleable per conversation, saved settings unchanged.
|
|
||
| | Command | Argument | Description | | ||
| | --- | --- | --- | | ||
| | `/add-api-key` | `<openai\|anthropic\|google>` | Securely store a model-provider API key | |
Contributor
There was a problem hiding this comment.
this is now just /api-keys (per the comment above)
Collaborator
Author
There was a problem hiding this comment.
Fixed in be16142: the table now lists /api-keys (no argument) in place of /add-api-key, and the BYOK section in models-and-usage documents the new menu.
| | `/agent` | `[prompt]` | Start a new conversation | | ||
| | `/auto-approve` | | Toggle auto-approve for agent actions | | ||
| | `/clear` | `[prompt]` | Clear the transcript and start a new conversation | | ||
| | `/clear-provider-api-key` | `<openai\|anthropic\|google>` | Remove a stored model-provider API key | |
Contributor
There was a problem hiding this comment.
This no longer exists (per the comment above)
Collaborator
Author
There was a problem hiding this comment.
Removed in be16142. The --clear-provider-api-key command-line flag stays documented since it remains supported (the CODE-1930 spec lists removing the flags as a non-goal) — only the slash command is gone.
…flag Address review feedback on the API key flow change (warpdotdev/warp#14472), which replaced /add-api-key and /clear-provider-api-key with a single inline /api-keys menu: - models-and-usage: rewrite the BYOK section around the /api-keys menu — set/replace/clear provider keys with masked entry, connect or disconnect X Premium/SuperGrok via browser sign-in, and toggle Warp credit fallback. The --set-provider-api-key/--clear-provider-api-key flags stay documented for scripting (they remain supported per the CODE-1930 spec). - reference: swap the /add-api-key and /clear-provider-api-key slash-command rows for /api-keys, and point --set-provider-api-key at the in-session menu. - reference: document the new --auto-approve flag (warpdotdev/warp#14483), which starts new conversations in that launch with auto-approve enabled. Co-Authored-By: Oz <oz-agent@warp.dev>
Remove redundant clauses: drop the repeated launch-default sentence in --auto-approve, the doubled keys-over-credits statement in the fallback bullet, the repeated browser-sign-in rationale in the scripting paragraph, and tighten the /api-keys table row to match the terse row pattern. Co-Authored-By: Oz <oz-agent@warp.dev>
hongyi-chen
added a commit
that referenced
this pull request
Jul 31, 2026
PR #405 consolidated troubleshooting into cli/reference.mdx (its Troubleshooting section) and reset cli/troubleshooting.mdx back to the skeleton stub, leaving the stub published in the sidebar with no sub-PR left to fill it. Remove the stub and its sidebar entry, matching the treatment #423 gives the conversations stub. No inbound links exist to /cli/troubleshooting/ (checked all merged and open cli sub-PR content), so no repoints are needed. Advances the 'delete 4 orphaned stubs' item on the #411 integration checklist. Validation: npm run build green; internal link check 0 broken. Co-authored-by: Oz <oz-agent@warp.dev>
hongyi-chen
added a commit
that referenced
this pull request
Aug 4, 2026
* Add Warp CLI launch docs skeleton and internal plan - New 'Warp CLI' sidebar topic with 13 stub pages under src/content/docs/cli/ - drafts/warp-cli-launch-plan.md: internal feature->page->reviewer analysis - New WARP_CLI content var (distinct from WARP_AGENT_CLI, reserved for the Oz CLI rename) Co-Authored-By: Oz <oz-agent@warp.dev> * Rename product to Warp Agent CLI - WARP_CLI var value -> "Warp Agent CLI" (body prose updates site-wide) - Sidebar topic label updated - Frontmatter literals fixed in the four stubs pending deletion - drafts doc: naming confirmed; WARP_AGENT_CLI key collision flagged Co-Authored-By: Oz <oz-agent@warp.dev> * docs(cli): models and usage + reference with troubleshooting (#405) * docs(cli): draft reference, models & usage, and troubleshooting pages Fill in the three cli-reference pages from the Warp CLI launch skeleton: - cli/reference: command-line flags with examples, environment variables, full slash-command table (25 commands verified against the CLI command registry), and default keyboard shortcuts sourced from the CLI keybinding definitions. - cli/models-and-usage: /model picker and footer model entry, BYOK via /add-api-key + provider flags (OpenAI/Anthropic/Google), custom model routers in the picker, and cost transparency (footer credits toggle, /cost per-response summary). - cli/troubleshooting: /view-logs bundling and log locations, login troubleshooting, autoupdate behavior with /version and --version, and support links. Co-Authored-By: Oz <oz-agent@warp.dev> * docs(cli): use literal Warp CLI in frontmatter title/description Frontmatter {{WARP_CLI}} tokens are not substituted by the build (Astro's content layer parses frontmatter outside Vite), so built titles showed the raw token. Body prose keeps {VARS.WARP_CLI}. Co-Authored-By: Oz <oz-agent@warp.dev> * docs(cli): fold troubleshooting into the reference page Consolidation: the standalone troubleshooting page merges into cli/reference.mdx as a final Troubleshooting section with problem-oriented H3 subsections. Existing H2 anchors (#slash-commands, #keyboard-shortcuts) are unchanged; internal links now point at #updating and #command-line-flags. troubleshooting.mdx is restored to the base-branch stub (the orchestrator removes it at integration). Co-Authored-By: Oz <oz-agent@warp.dev> * docs(cli): rename literal Warp CLI to Warp Agent CLI in frontmatter Follows the base-branch WARP_CLI var value change; body prose picks up the new name automatically via {VARS.WARP_CLI}. Co-Authored-By: Oz <oz-agent@warp.dev> * docs(cli): security fixes for API key examples Address review feedback: - Make WARP_API_KEY=... warp the primary non-interactive auth example and document --api-key secondarily with a caution that command-line arguments can be captured in shell history and process listings. - Replace the persistent key.txt stdin example with a tool-agnostic secret-manager pipe and a note against staging keys in plaintext files. Co-Authored-By: Oz <oz-agent@warp.dev> * docs(cli): editorial polish pass Reduce product-name density after each page's intro (prefer "the CLI"), vary repeated trailing "See [X]" sentences, and fold two cross-links into their sentences. No structural, factual, heading, or link-target changes. Co-Authored-By: Oz <oz-agent@warp.dev> * docs(cli): trim menu-mechanics narration Cut the type-to-filter/arrows/Enter sentence from the model picker prose and the keep-typing-to-filter clause from the slash-command intro, per the editorial bar against narrating self-evident UI mechanics. Defaults, exceptions, and lookup tables are unchanged. Co-Authored-By: Oz <oz-agent@warp.dev> * docs(cli): note macOS Option-as-Alt requirement for Alt shortcuts Platform audit: every keybinding registration is identical on macOS and Linux (the only platform-conditional binding is a Windows-only Alt+V paste, which is not documented since no Windows build ships). Input arrives as terminal key events, so Alt shortcuts depend on the host terminal delivering Option as Alt on macOS; add one note to the keyboard shortcuts section instead of per-row annotations. Co-Authored-By: Oz <oz-agent@warp.dev> * docs(cli): tighten disabled-models sentence in model picker prose Co-Authored-By: Oz <oz-agent@warp.dev> * docs(cli): update API key docs for /api-keys menu and --auto-approve flag Address review feedback on the API key flow change (warpdotdev/warp#14472), which replaced /add-api-key and /clear-provider-api-key with a single inline /api-keys menu: - models-and-usage: rewrite the BYOK section around the /api-keys menu — set/replace/clear provider keys with masked entry, connect or disconnect X Premium/SuperGrok via browser sign-in, and toggle Warp credit fallback. The --set-provider-api-key/--clear-provider-api-key flags stay documented for scripting (they remain supported per the CODE-1930 spec). - reference: swap the /add-api-key and /clear-provider-api-key slash-command rows for /api-keys, and point --set-provider-api-key at the in-session menu. - reference: document the new --auto-approve flag (warpdotdev/warp#14483), which starts new conversations in that launch with auto-approve enabled. Co-Authored-By: Oz <oz-agent@warp.dev> * docs(cli): editorial trim pass on API key and auto-approve additions Remove redundant clauses: drop the repeated launch-default sentence in --auto-approve, the doubled keys-over-credits statement in the fallback bullet, the repeated browser-sign-in rationale in the scripting paragraph, and tighten the /api-keys table row to match the terse row pattern. Co-Authored-By: Oz <oz-agent@warp.dev> --------- Co-authored-by: Oz <oz-agent@warp.dev> * docs(cli): permissions and profiles (#404) Replaces the `cli/permissions-and-profiles.mdx` stub with a full draft covering the permission model, permission cards, auto-approve, and settings-file execution profiles. Verified against `warp` master: - Per-action-type permission values and CLI defaults (`AIExecutionProfile::default_profile_for_tui`) - `warp --auto-approve` launch flag (warpdotdev/warp#14483) - `auto_approve_bypasses_command_denylist` defaults to true, so auto-approve bypasses the user command denylist; team-enforced Admin Panel rules are never bypassed (`can_autoexecute_command`) Follow-ups tracked, not included here: - `--auto-approve` needs adding to the flags table on `cli/reference.mdx` (separate stub PR on this stack) - `agent-platform/capabilities/agent-profiles-permissions.mdx` has two now-stale denylist statements given the new bypass default Reviewed by @harryalbert. Co-Authored-By: Oz <oz-agent@warp.dev> * docs(cli): cloud handoff and orchestration (#402) Replaces the cli/cloud-and-orchestration stub with the full draft: /handoff flow and guardrails, resuming cloud runs (browser-first), multi-agent orchestration approval card and permission, child-agent tab bar management, and Ctrl+C kill paths. Includes review feedback from harryalbert and a final editorial pass. Co-Authored-By: Oz <oz-agent@warp.dev> * docs(cli): agent conversations and conversation management (#399) * docs(cli): draft agent conversations page Covers the streaming transcript, Markdown/Mermaid rendering, tool-call rows, file-edit diffs, thinking blocks, interactive agent questions, task lists, /plan flow, and transcript selection/copy for the Warp CLI. Co-Authored-By: Oz <oz-agent@warp.dev> * docs(cli): use literal Warp CLI in frontmatter {{WARP_CLI}} tokens are not substituted in MDX frontmatter by the content layer, so built titles/descriptions showed the raw token. Body prose keeps {VARS.WARP_CLI}. Co-Authored-By: Oz <oz-agent@warp.dev> * docs(cli): absorb conversation management into agent conversations page Adds a Managing conversations section group (persistence/restore, /new /agent /clear, /conversations menu + left-arrow shortcut, /compact, exit summary + --resume) from the standalone conversations page, which is being removed in the consolidation. Updates the intro, description, and related pages accordingly. Co-Authored-By: Oz <oz-agent@warp.dev> * docs(cli): rename to Warp Agent CLI in frontmatter Follows the launch-name change; body prose picks up the new name via the WARP_CLI var from the base branch merge. Co-Authored-By: Oz <oz-agent@warp.dev> * docs(cli): editorial polish on agent conversations page Reduces product-name repetition after the intro, links bold lead terms in the tool-call list instead of trailing See-X sentences, swaps 'unfolds' for 'appears', fixes 'just', and de-metas the intro's managing-conversations pointer. No factual, heading, or link-target changes. Co-Authored-By: Oz <oz-agent@warp.dev> * docs(cli): trim self-evident UI narration per review Per PR review: cut transcript scrolling narration, collapse the markdown-features list to its non-obvious caveats (folding the H3), drop the tool-call glyph state-machine detail, and sweep the rest of the page with the same lens (menu how-tos, click-to-collapse, and double/triple-click narration removed). Feature facts, caveats, shortcuts, and cross-links are unchanged. Co-Authored-By: Oz <oz-agent@warp.dev> * docs(cli): apply editorial audit cuts Seven targeted trims: intro filler sentence, diff-header bullet detail, multi-question tail, bold header adjective, copy-confirmation footer mention, managing-conversations enumeration, and history restore phrasing. Co-Authored-By: Oz <oz-agent@warp.dev> * docs(cli): address review feedback on agent conversations - Trim styling narration from the transcript intro (prompt row marker, elapsed-time progress indicator) that would go stale with small UI changes; keep the durable behavior (streaming, Ctrl+C to stop). - Color the task-list status glyphs to match the TUI: yellow in-progress dot and green completed check, via mode-aware Starlight hue tokens so they stay legible in dark and light mode. - Lead "Resuming conversations" with the conversation menu, the primary way to resume in the CLI, and note type-to-filter in the menu. Co-Authored-By: Oz <oz-agent@warp.dev> * docs(cli): editorial pass for redundancy and flow - Collapse three separate "restores the full transcript" statements into one, in Conversation persistence, where the detail belongs. - Replace the duplicated "saved automatically" claim with the account vs. local-machine distinction, which sets up the menu contents and the offline caution that follow. - Move Resuming conversations next to Conversation history so the two cross-referencing sections are adjacent instead of split by Compacting context. - Point the intro's resume link at #resuming-conversations directly, and fix a dangling modifier in the tool-call description. Co-Authored-By: Oz <oz-agent@warp.dev> --------- Co-authored-by: Oz <oz-agent@warp.dev> * docs(cli): remove orphaned conversations stub, repoint its links (#423) PR #397 (hyc/launch-cli-cli-conversations) was closed unmerged when #399 absorbed its content into cli/agent-conversations.mdx, but the stub it was meant to fill survived on the launch branch. The sidebar listed it as "Managing conversations" four lines below the real "Agent conversations" page, so the launch would have shipped a nav entry leading to a page that reads "documentation for this page is in progress". - Delete src/content/docs/cli/conversations.mdx. - Drop its sidebar entry in src/sidebar.ts. - Repoint the four inbound links from cloud-and-orchestration.mdx and reference.mdx to the corresponding anchors on cli/agent-conversations. No redirect needed: /cli/conversations has never been published (404 live, and src/content/docs/cli/ does not exist on main). Co-authored-by: Oz <oz-agent@warp.dev> * docs(cli): remove orphaned troubleshooting stub (#425) PR #405 consolidated troubleshooting into cli/reference.mdx (its Troubleshooting section) and reset cli/troubleshooting.mdx back to the skeleton stub, leaving the stub published in the sidebar with no sub-PR left to fill it. Remove the stub and its sidebar entry, matching the treatment #423 gives the conversations stub. No inbound links exist to /cli/troubleshooting/ (checked all merged and open cli sub-PR content), so no repoints are needed. Advances the 'delete 4 orphaned stubs' item on the #411 integration checklist. Validation: npm run build green; internal link check 0 broken. Co-authored-by: Oz <oz-agent@warp.dev> * docs(cli): customization (settings, themes, statusline, rules, skills, MCP) (#401) * docs(cli): draft the Warp CLI configuration page Cover the local TOML settings file (per-platform locations, hot reload, error fallback, local-only/no cloud sync), editing settings by asking the agent, /theme with terminal background detection, and the statusline with /statusline customization. Drop the keybindings section: custom keybinding overrides are not loaded by the CLI yet. Co-Authored-By: Oz <oz-agent@warp.dev> * docs(cli): use literal Warp CLI in configuration frontmatter {{WARP_CLI}} tokens are not substituted in MDX frontmatter by the build pipeline, so the built title/description showed the raw token. Body prose keeps {VARS.WARP_CLI}. Co-Authored-By: Oz <oz-agent@warp.dev> * docs(cli): absorb agent context content into the customization page Consolidate the CLI docs: fold the context page's rules, skills, bundled skills, and MCP sections into configuration.mdx, retitled "Customizing the Warp CLI". Dedupe the modify-settings bundled skill treatment and switch cross-links to in-page anchors. The context.mdx file itself is removed at integration. Co-Authored-By: Oz <oz-agent@warp.dev> * docs(cli): rename Warp CLI to Warp Agent CLI in customization frontmatter Follows the site-wide WARP_CLI var update on the base branch; body prose picks up the new name via the var automatically. Co-Authored-By: Oz <oz-agent@warp.dev> * docs(cli): qualify settings hot reload for theme edits Address review on PR #401: settings values hot-reload from disk, but the rendered theme only re-applies via /theme or at the next startup, so the settings-file and agent-edit sections no longer promise immediate effect for theme changes. Also scope the Themes section's immediate-apply claim to /theme. Windows path verified to render with single backslashes in source and built HTML; no change needed. Co-Authored-By: Oz <oz-agent@warp.dev> * docs(cli): reduce product-name density on the customization page Editorial polish pass: after the intro's first mention, refer to the product as "the CLI" instead of repeating the full name in every section. The full name stays in the frontmatter, the intro, and the reference link. No structural, factual, heading, or link-target changes. Co-Authored-By: Oz <oz-agent@warp.dev> * docs(cli): trim obvious menu-mechanics narration Per editorial direction: collapse the skills-menu step list into the non-obvious behaviors (selection inserts /skill-name for editing, argument passing, direct invocation) and drop the arrow-select narration in the /mcp view. Keep the statusline config steps since its keys are surprising (Esc saves, arrows reorder). No headings, facts, or link targets changed. Co-Authored-By: Oz <oz-agent@warp.dev> * docs(cli): compress statusline catalog and tighten context and /mcp prose Apply orchestrator audit: keep only statusline items with non-obvious behavior as bullets and fold the self-explanatory ones into one sentence, shorten the working-directory context paragraph, and replace the four per-state /mcp bullets with two lines. Co-Authored-By: Oz <oz-agent@warp.dev> * docs(cli): re-verify statusline items against latest master Master's statusline catalog changed (moira's #14257/#14458): the auto-queue item was removed, and Vim mode indicator and GitHub pull request items were added. Auto-approve and Vim mode indicator are now on by default. Update the item list, defaults, and the auto-approve and git diff descriptions accordingly. Themes, settings paths, and the /statusline config flow re-verified against master and unchanged. Co-Authored-By: Oz <oz-agent@warp.dev> --------- Co-authored-by: Oz <oz-agent@warp.dev> * Post-merge coherence pass on cli docs - Remove orphaned context stub (content lives in configuration.mdx via #401) and its sidebar entry; repoint the reference page link - Fix stale auto-approve statusline claim in permissions page (the indicator is default-on since the statusline catalog update) Co-Authored-By: Oz <oz-agent@warp.dev> * docs: address review feedback on agent-conversations.mdx Applies suggested edits and resolves open questions from PR review: - Applies wording/phrasing suggestions from inline suggestion comments - Reworks the tool-call and code-diff bullet lists for consistent bold-term + dash + description formatting - Clarifies multi-file diff nesting based on TuiFileEditsView source - Clarifies the plan toggle shortcut per the CLI reference page (Ctrl+Shift+P expands/collapses the latest plan) - Reorders the copy/export paragraph before the clipboard note - Simplifies the /new, /agent, /clear list since the intro sentence already explains their behavior - Formats YOUR_CONVERSATION_TOKEN as inline code Co-Authored-By: Oz <oz-agent@warp.dev> * docs: address review feedback on cloud-and-orchestration.mdx Applies suggested edits and resolves open questions from PR review: - Applies wording/phrasing suggestions from inline suggestion comments - Rewords the intro to avoid the ambiguous "Oz Platform" phrase pending a vars.ts decision - Reworks the handoff steps and card-action bullets for consistent bold-term + dash + description formatting; moves the pre-confirm Ctrl+C cancel note to its correct chronological position - Clarifies the handoff card's model-preselection wording - Restructures 'Resume cloud conversations' into a clear two-option (browser / CLI) + constraints layout - Splits the dense orchestration-start paragraph and the tab-bar navigation bullet for scannability - Clarifies 'read-only status views' wording for cloud child sessions - Fixes non-em-dash usage flagged in the kill-agent paragraph - Adds a real screenshot of the Agents: tab bar, captured liv- Adds a real screenshot of the Agents: tab bar, captured liv- Adds a real screenshot of the Agents: tab bar, captured liv- Adds in warpdotdev/warp Co-Authored-By: Oz <oz-agent@warp.dev> * docs: address review feedback on models-and-usage.mdx - Applies suggestion comments: intro rewording, model-picker/profile wording, semicolon and colon cleanup, usage bullet rewording - Clarifies the ambiguous "footer" reference by naming and linking to the statusline section in configuration.mdx (applied consistently to both occurrences on the page) Co-Authored-By: Oz <oz-agent@warp.dev> * docs: fix statusline default-items accuracy and add screenshot Verified against warpdotdev/warp origin/master (crates/warp_tui/src/ terminal_session_view/statusline.rs, app/src/settings/ai.rs): - Adds the missing 'Working directory' bullet; it's a default item, not one you 'also add' - Clarifies that enabling Git branch status replaces the plain Git branch chip rather than adding a second one (should_render_plain_git_branch requires branch status disabled) - Adds a real screenshot of the statusline with credit usage, context window usage, and task-list chips enabled, captured live via the tui-verify-change skill in warpdotdev/warp Co-Authored-By: Oz <oz-agent@warp.dev> * docs: address review feedback on permissions-and-profiles.mdx and reference.mdx permissions-and-profiles.mdx: - Applies suggestion comments: description/intro trims, colon removal - Clarifies the vague "letting file reads through" example - Converts the dense default-permissions paragraph into a scannable bulleted list - Removes semicolons from the approval-card bullets and tightens wording - Links the settings-file bypass instructions to configuration.mdx reference.mdx: - Applies the intro suggestion, removing the mid-sentence colon Co-Authored-By: Oz <oz-agent@warp.dev> * docs: holistic style pass across Warp Agent CLI docs Applies the same rubric from earlier review rounds (unclear language, wordy passages, unnecessary UI detail, colons/semicolons) to the rest of the PR: - reference.mdx: fixes a grammar issue in the flags intro, removes mid-sentence colons/semicolons in the slash commands, keyboard shortcuts, and troubleshooting sections (only line 9 had been reviewed directly) - Re-scanned all previously-edited files (agent-conversations, cloud-and-orchestration, configuration, models-and-usage) for remaining semicolons joining independent clauses and split them into separate sentences for consistency index.mdx, quickstart.mdx, input-and-editing.mdx, and shell-commands.mdx are still TODO-only placeholder stubs (no drafted prose yet), so there was nothing to style-review there. Co-Authored-By: Oz <oz-agent@warp.dev> * docs: crop and highlight the CLI screenshots for clarity Both screenshots previously showed the full 120x40 terminal window, making it unclear which part was the actual subject. Cropped each to the relevant region and added a highlighted border around the exact row being documented: - tui-agents-tab-bar.png: cropped to the top strip (bar + one line of context below); highlighted the Agents: tab bar row - tui-statusline.png: cropped to the bottom strip (last transcript line, input box, statusline); highlighted the statusline row Co-Authored-By: Oz <oz-agent@warp.dev> * docs(cli): overview and quickstart (#398) * docs(cli): draft Warp CLI overview and quickstart pages Fill in cli/index.mdx (what the CLI is, key features, relationship to the Warp app and Oz, supported platforms, login/logout, automatic updates, migration from the Warp app, open source) and cli/quickstart.mdx (install placeholder, device-auth login, first prompt, shell command, exit and resume). Co-Authored-By: Oz <oz-agent@warp.dev> * docs(cli): use literal Warp CLI in frontmatter titles and descriptions Frontmatter {{WARP_CLI}} tokens are not substituted by the build pipeline, so built titles showed the raw token. Body prose keeps {VARS.WARP_CLI}. Co-Authored-By: Oz <oz-agent@warp.dev> * docs(cli): rename to Warp Agent CLI in frontmatter and intro Update literal frontmatter titles/descriptions for the confirmed launch name and rework the overview intro now that Warp Agent CLI is the primary name (positioning: the Warp Agent from the Warp app, in any terminal). Body {VARS.WARP_CLI} usages pick up the new name from the merged var change. Co-Authored-By: Oz <oz-agent@warp.dev> * docs(cli): address PR #398 review comments Add a visible interim note to the quickstart install section so it no longer renders empty alongside the pending-instructions comment, and make the WARP_API_KEY environment variable the primary non-interactive auth recommendation with a caution about --api-key appearing in shell history and process listings. Co-Authored-By: Oz <oz-agent@warp.dev> * docs(cli): editorial polish on overview and quickstart Link the bold feature names in the overview's key features list and drop the trailing See-X sentences, prefer "the CLI" over the full product name after first mention, and fold the trailing conversations link in the quickstart into its sentence. Co-Authored-By: Oz <oz-agent@warp.dev> * docs(cli): address owner review on overview page Remove named third-party terminals from the intro, reference the platform name through the content variable in body prose (heading and frontmatter keep the literal name), and drop the Open source section. Co-Authored-By: Oz <oz-agent@warp.dev> * docs(cli): trim narration of obvious mechanics from quickstart Cut the section-enumerating intro sentence, the press-Enter and output-appears step narration, and the placeholder restatement in the resume step. Overview page needed no cuts. Co-Authored-By: Oz <oz-agent@warp.dev> * docs(cli): correct Warp Drive claim to saved prompts only Verified against the Warp repo: the CLI's slash menu wires only the saved-prompts data source (plus static commands and skills); workflows, notebooks, and environment variables have no CLI surface. Co-Authored-By: Oz <oz-agent@warp.dev> * docs(cli): repoint links after context and conversations pages merged The context and conversations pages were consolidated on the base branch. Point the overview and quickstart links at their new homes: project context -> configuration#project-context-and-rules, and persistence/history -> agent-conversations sections. Merge the duplicate quickstart next-step into a single Configuration bullet. Co-Authored-By: Oz <oz-agent@warp.dev> * docs(cli): update overview and installation Co-Authored-By: Oz <oz-agent@warp.dev> * docs(cli): clarify zero-state customization Co-Authored-By: Oz <oz-agent@warp.dev> * docs(cli): fix renamed agent docs links Co-Authored-By: Oz <oz-agent@warp.dev> --------- Co-authored-by: Oz <oz-agent@warp.dev> Co-authored-by: Yunfan Yang <kevin@warp.dev> * docs(cli): input and shell commands (#406) * 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 <oz-agent@warp.dev> * 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 <title> now reads "Input and editing in the Warp CLI". Co-Authored-By: Oz <oz-agent@warp.dev> * 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> * 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 (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> * 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> * 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> * 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> * 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> * 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> * docs(cli): clarify keyboard and voice support Co-Authored-By: Oz <oz-agent@warp.dev> * docs(cli): clarify Linux voice packaging Co-Authored-By: Oz <oz-agent@warp.dev> * docs(cli): fix renamed agent docs links Co-Authored-By: Oz <oz-agent@warp.dev> --------- Co-authored-by: Oz <oz-agent@warp.dev> Co-authored-by: Yunfan Yang <kevin@warp.dev> * docs(cli): final holistic pass before launch - Remove the leftover shell-commands stub; its content ships in the combined input page, now at cli/input-and-shell-commands (slug matches the title). Repoint all inbound links and update the sidebar entry. - Document start-screen customization (appearance.zero_state: object/ASCII art, rotation period, section toggles) on the customization page, and trim the overview's Key features bullet to match; keys verified in warp master. - Remove keybinding-customization claims (loading keybindings.yaml overrides in the CLI is still a follow-up per crates/warp_tui/src/keybindings.rs). - Cover Windows in the reference's platform bindings note (incl. the Windows-only Alt+V paste alias). - Apply the established style rubric (no semicolon-joined clauses or mid-sentence colon narration) to the three pages that merged after the style pass, plus two stragglers in the reference. - Dedupe the quickstart's natural-language-detection explanation and fix an 'Agent Mode' capitalization. - Add a Warp Agent CLI llms.txt custom set; delete the internal drafts/warp-cli-launch-plan.md planning doc so it doesn't ship to main. Co-Authored-By: Oz <oz-agent@warp.dev> * docs: keep local pricing drafts out of the launch branch Untracked local drafts were swept into the previous commit by git add -A; remove them from tracking (files remain on disk). Co-Authored-By: Oz <oz-agent@warp.dev> * docs(cli): fix TOC-visible VARS tokens in headings, shorten nav label Starlight's on-this-page TOC renders heading text without evaluating MDX expressions, so two headings showed a literal VARS.WARP_CLI token. Use the literal product name in headings. Also shorten the top-nav topic label from 'Warp Agent CLI' to 'Agent CLI'. Co-Authored-By: Oz <oz-agent@warp.dev> * docs(cli): use right-caret prompt chevron for the Agent CLI nav icon Co-Authored-By: Oz <oz-agent@warp.dev> --------- Co-authored-by: Oz <oz-agent@warp.dev> Co-authored-by: Rachael Rose Renk <91027132+rachaelrenk@users.noreply.github.com> Co-authored-by: Yunfan Yang <kevin@warp.dev>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Pages changed
src/content/docs/cli/reference.mdx(now includes the Troubleshooting section)src/content/docs/cli/models-and-usage.mdxsrc/content/docs/cli/troubleshooting.mdxis restored to the base-branch stub per the page consolidation (13 → 9); the orchestrator removes that page at integration.Features covered
reference
--resume,--api-key(+WARP_API_KEY),--set-provider-api-key,--clear-provider-api-key,--version,--help(verified against the CLI arg parser)WARP_API_KEY,WARP_TUI_DISABLE_AUTOUPDATE/skill-name/view-logszip bundling + macOS log location~/Library/Logs/warp-cli/; login issues (browser-less device-auth URL + code, "Login failed", wrong account via/logoutincl. web sign-out,--resumerestore failure); updating (background autoupdate applied on next launch,/version+warp --version, env/setting opt-out); getting-help links#slash-commandsand#keyboard-shortcutspreserved for sibling-page links; new#troubleshootinganchor availablemodels-and-usage
/modelpicker + footer model entry (click toggles the same picker); selection persists to the active profile's base model/add-api-key,/clear-provider-api-key+ CLI flags; providers enumerated from code (openai, anthropic, google); masked input; Auto-models-consume-credits note; cross-links to inference/BYOK docs~/.warp/custom_model_routers/definitions as the app (feature ships in default/stable flag set)/costper-response duration + credits summaryThe launch blog claims these two capabilities for the Warp Agent CLI. I verified both against warp master and could not find a shipped CLI path; eng should reconcile before launch. Neither is documented on the page:
ApiKeys.custom_endpointswere populated, but there is no CLI surface to configure an endpoint (the add/edit flow exists only in the app's settings UI), the CLI key commands accept only openai|anthropic|google (no openrouter slug), and the CLI intentionally uses a separate secure-storage namespace from the app (LaunchMode::secure_storage_service_name), so endpoints configured in the Warp app are not visible to the CLI process.If eng lands either capability (or a shared-keychain/import path) before launch, I can add them to models-and-usage with cross-links to agent-platform/inference/custom-inference-endpoint and agent-platform/inference/grok-subscription.
Dropped/unconfirmed
/add-api-keyaccept only openai|anthropic|google; xAI is excluded from the API-key provider list in code./status: dropped — no such command exists in the slash-command registry./copy-debugging-link: dropped — not in the registry; no CLI implementation found on master./fast-forward: dropped — no such slash command in the registry (auto-approve is the shipped toggle; documented under permissions page's scope)./pr-commentsdisplay: dropped — no such slash command in the registry.--list-models/ headless runs: excluded per plan — absent from the CLI arg parser.Notes for reviewers
Ctrl+Palso toggles plans in terminals without keyboard-enhancement support; I documented onlyCtrl+Shift+Pto avoid over-qualifying. Flag if you want both.Suggested reviewer(s): harry, ian (moira for custom routing)
Co-Authored-By: Oz oz-agent@warp.dev