docs: editorial review pass on Warp Agent CLI launch docs

[rachaelrenk]

Summary

A second, top-to-bottom editorial review of the Warp Agent CLI launch documentation that shipped in #411. The first review happened before the overview and quickstart were finished, and engineering changes were still landing, so this pass re-reads all nine pages holistically.

Four review rounds have landed so far: an initial pass over all nine pages, a quickstart restructure, a frontmatter description pass that also fixed the underlying guidance gap, and a clarity pass over the reference page. Further rounds will be committed here.

Changes

Overview (cli/index.mdx)

• Reworked the Key features descriptions. Several were sentence fragments or unclear about what the feature does:
  • Agent conversations had no verb and used lowercase "markdown" where every other page uses "Markdown".
  • Persistent conversations opened with a dangling participle ("Saved to your Warp account...") that left the subject implicit.
  • Permissions you control was renamed to Permissions and profiles so the link text names the destination page, like every other bullet.
  • Cloud handoff and orchestration now reads "Hand off a conversation to a cloud agent".
  • Tightened Shell commands (which used "commands" three times) and Project context.
• Restructured Logging in and out into three scannable bullets so the browser flow, the non-interactive API key flow, and signing out are visually distinct, with detail deferred to the quickstart and reference.
• Automatic updates now opens with "The CLI updates automatically", and the opt-out starts a new paragraph beginning "To turn off background updates". Added the WARP_TUI_DISABLE_AUTOUPDATE per-launch option, which the reference documented but the overview omitted.

Quickstart (cli/quickstart.mdx)

• Numbered the step headings (## 1. Install the Warp Agent CLI). Every other quickstart in the repo numbers its steps; ours was the only one using unnumbered sections with numbered lists inside. Converted those nested lists to prose so steps aren't double-numbered. This matches the sibling Oz CLI quickstart and the API/SDK quickstart.
• Moved the install commands into Tabs / TabItem for macOS and Linux vs. Windows, matching the pattern already used in getting-started/quickstart/installation-and-setup.mdx.
• Added a sign-up link to the account prerequisite. Developers new to Warp are a real audience for the CLI, since it works without the desktop app, and the prerequisite now says so explicitly.
• Tightened the login step, which read as a clunky three-item list for what is effectively one command plus a browser approval. It now follows the shape of the Oz CLI quickstart's authenticate step.
• Dropped the colon from the start-screen sentence and reworded the API key pointer to "See API keys to learn how to create one."

Renumbering the headings changed the login anchor, so the inbound /cli/quickstart/#log-in link in index.mdx was updated to #2-log-in.

Reference (cli/reference.mdx)

A top-to-bottom review for vague or unclear wording.

Concreteness:

• --api-key said it was "useful on hosts where a browser sign-in is inconvenient," which names no actual situation. It now names CI runners and remote servers.
• Both provider-key flags described their argument in prose. They now show <provider> syntax per the style guide, plus a concrete example.
• They also said "securely stores" without saying where. Both now say the device's secure storage, and that Warp never stores provider keys on its servers.
• --auto-approve said "The default applies only to that launch," where "the default" had no clear referent. Same problem with "for that launch" on WARP_TUI_DISABLE_AUTOUPDATE.
• The autoupdate paragraph used generic "configuration" link text and never named the setting. It now names general.autoupdate_enabled and deep-links to the settings file section.

Accuracy and consistency:

• The platform note claimed bindings are "identical" on all three platforms and then immediately listed a Windows-only binding. It now states the exception, and mentions the Kitty protocol requirement for the macOS Command shortcuts.
• Approvals: "Confirm the selected response" read as the agent's response rather than the option on the card. "Approve a blocked terminal-use action" used a term defined nowhere in the docs.
• Terminal control: Ctrl+C listed two behaviors without saying which applied when. It now distinguishes a command you started from one the agent is running.
• Multi-agent tabs referred to "the main agent" where the rest of the docs say orchestrator, and omitted Shift+← / Shift+→ and Ctrl+C, both documented on the orchestration page. Added.
• /skills said "Invoke a skill," but it opens a browser and inserts the skill into the input.
• Ctrl+Y said "Paste," which collides with clipboard paste. Now "Reinsert."
• Alphabetized the command-line flags, matching the slash command table and the reference drafting rules.
• Environment variables now use the bold + code list format used on the other CLI pages.

Other CLI pages

• agent-conversations.mdx was the only page bolding its Related pages links. The style guide says to avoid redundant bold prefixes when the link text already carries the context.
• cloud-and-orchestration.mdx had the only em dash in the nine pages, in instructional text where the style guide prohibits it, plus the British "cancelling" where the rest of the docs use US spelling. Both rewritten.
• configuration.mdx was the only Related pages list missing trailing periods. It also picked up a # REVIEW: frontmatter comment flagging that the page title is "Customizing the Warp Agent CLI" while the sidebar label is "Configuration," and that cross-references use four different names for the page. Flagged rather than changed, pending confirmation on whether the mismatch is intentional.
• input-and-shell-commands.mdx mixed - and * bullet markers across sections. All bullets now use *, matching the other eight pages and the style guide example.

Cross-page consistency

• "The CLI keeps itself up to date" appeared on three pages. All now say "The CLI updates automatically."
• The approval edit shortcut was E on the permissions page and e on two others. Standardized on uppercase E.

Authoring guidance for frontmatter descriptions

The CLI descriptions showed a pattern of filler openers and page-describing phrasing, so this round fixed the guidance gap that allowed it, then applied the result.

Guidance, in AGENTS.md, the templates, and the draft_* skills:

• AGENTS.md contradicted itself: the Frontmatter section said "1-2 sentences" while the SEO section said "50-160 characters." Two sentences almost always exceeds 160, which is likely why descriptions drifted. Standardized on one sentence, 50-160 characters.
• Added "Description rules" and "Descriptions by content type" to AGENTS.md as the source of truth, with correct and incorrect examples for all eight content types.
• The eight templates carried thin, inconsistent hints. Only guide-page mentioned the character budget, and conceptual and procedural had no example at all. All eight now give type-specific direction and point at AGENTS.md.
• The eight draft_* skills said essentially nothing about descriptions. Each now carries a short rule with examples and a pointer to AGENTS.md.

Applied to four CLI pages:

• agent-conversations.mdx opened with "Learn about" and was the only description over 160 characters.
• index.mdx had a strong first sentence followed by one that described the page rather than the product.
• configuration.mdx said you customize the settings file, when you customize the CLI using it.
• reference.mdx was a noun fragment rather than a verb-led summary of what you can look up.

The other five were already direct and were left alone. All nine now pass one sentence, 50-160 characters, no filler opener.

Notes for reviewers

Open items not addressed here:

• The style linter flags 7 instances of lowercase "agent mode" as needing to be "Agent Mode". In the CLI this is the counterpart to "shell mode", not the Warp app's Agent Mode feature, so we kept it lowercase. These will keep surfacing as linter warnings unless we add a glossary exception.
• The figures in cloud-and-orchestration.mdx and configuration.mdx have no standard maxWidth, which the linter flags. Both are wide UI strips where default content width is plausibly correct, but worth a look.
• The logs section documents only the macOS path (~/Library/Logs/warp-cli/). The Linux and Windows paths are missing, unlike the settings-file section which covers all three. Left as-is rather than guessing at them.
• Log retention was described as "only a limited number of recent sessions are kept." Softened to "older session logs are rotated out" rather than inventing a number. If someone knows the real retention count, it's worth stating.
• Left an inline question on the diff about whether CLI keybindings are customizable. The reference calls them "the default bindings," which implies they are, but nothing in the docs describes how.
• Screenshots are deferred and tracked internally. Only two of the nine CLI pages have figures, and permissions-and-profiles.mdx and agent-conversations.mdx describe visual surfaces with none at all. Four are worth adding: the permission card, a conversation transcript, the start screen, and the slash command menu. Every candidate needs an authenticated CLI session, which is why none are in this PR.

Validation

• npm run build passes: 364 pages, no new warnings.
• All anchors touched by these edits verified to resolve to real heading IDs in the built HTML, including the renumbered quickstart headings and the reordered flag headings.
• Verified the quickstart's OS tabs render as Starlight tab components with the expected labels.
• Confirmed the frontmatter comment is stripped from both the rendered page and the markdown export.
• Internal link check: 3,444 links across 363 files, 0 broken.
• Style lint unchanged at 23 pre-existing findings for cli/; no new violations introduced.

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

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
docs	Ready	Preview	Aug 4, 2026 11:03pm

[oz-for-oss]

@rachaelrenk

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 makes an editorial consistency pass across the Warp Agent CLI documentation, tightening key feature descriptions, login/update wording, related-page formatting, and bullet markers. I did not find correctness, security, link, or spec-alignment issues in the annotated diff.

Concerns

• No blocking concerns found. No approved or repository spec context was provided, so there was no material spec contract to enforce.

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

[rachaelrenk]

Question for the CLI engineers: this says "the default bindings," which implies keybindings are customizable. I couldn't find anything in the CLI docs describing how to customize them, and configuration.mdx doesn't cover a keymap setting.

If they aren't customizable, we should drop "default" so we don't imply a feature that doesn't exist. If they are, let's document where to configure them and link it from here.

Leaving as-is pending confirmation.