docs: consolidate the Warp Agent CLI docs into the Agents section - #486
docs: consolidate the Warp Agent CLI docs into the Agents section#486rachaelrenk wants to merge 18 commits into
Conversation
The Warp Agent CLI had its own top-level docs tab at /cli, which framed it as a separate product area rather than another entry point to the Warp Agent. Nothing outside src/content/docs/cli/ linked into it, so the section was effectively orphaned from the rest of the docs. Move the nine CLI pages to src/content/docs/agents/cli/ and surface them as a "Warp Agent CLI" group inside the Agents tab, between "Warp Agents" and "Third-Party CLI Agents". - Move content and assets with git mv so history follows; rewrite 68 absolute self-links and both relative image paths. - Remove the standalone Agent CLI sidebar topic and add the new group, preserving the original ordering and labels. - Add nine 308 redirects so every /cli/* URL still resolves. - Repoint the llms.txt custom set at agents/cli/**. - Reference the CLI as an entry point from agents/index, agents-in-warp, local-agents/overview, and cli-agents/overview, which previously had no path to it. The path /agents/cli/ is deliberately generic: the Oz CLI is retired and wrapped into the Warp Agent CLI at the next launch (~2026-08-18), so the Oz CLI reference is expected to fold in here later. Recorded that decision in the terminology glossary and the vars.ts comment that previously flagged the WARP_AGENT_CLI / WARP_CLI collision as unresolved. Neither var changes in this commit. Also cropped the two CLI screenshots to their subject (the tab-bar capture included a cut-off prompt below the bar) and included a cut-off prompt below the bar) and included a cut-off proBy: Warp Agent <agent@warp.dev>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
|
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 |
There was a problem hiding this comment.
Overview
This PR consolidates the Warp Agent CLI documentation under the Agents section, updates the sidebar and llms.txt custom set, rewrites moved-page self-links, and adds redirects for the old /cli/* URLs. I did not find correctness, docs-structure, security, or spec-alignment issues in the annotated diff.
Concerns
- None.
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
…oute limit The Vercel deployment for this PR failed. Vercel caps "Routes created per Deployment" at 2048, and counts every redirect, rewrite, and header in vercel.json as a route. main sits at 2033; the nine per-page /cli redirects pushed this branch to 2042, and the Astro Vercel adapter contributes further routes on top of the config, tipping the deployment over the ceiling. Replace the nine per-page entries with two wildcard entries, bringing the total to 2035 (+2 over main instead of +9). The wildcard also covers deep links and any page added under the old path, which the enumerated list would not have. Co-Authored-By: Warp Agent <agent@warp.dev>
The previous wildcard used ':path*', which did not match the trailing-slash URLs this site serves. Verified against the preview deployment: /cli/ redirected correctly but /cli/quickstart/ and /cli/reference/ both returned 404, so eight of the nine original URLs were broken. Use a regex capture ':path(.*)' instead, which captures the remainder of the path including its trailing slash. Keeps the route count at +2 over main. Co-Authored-By: Warp Agent <agent@warp.dev>
The Warp Agent CLI statusline is content-bound: it clips rather than reflows, and showing every chip its alt text promises needs ~111 columns. Re-capturing at a narrower terminal cannot shrink it, so at 563px the text renders at roughly 48% of source and reads small. The existing standard had no width above 563px, leaving no correct option for a screenshot like this. Add 736px as a full-content-width tier. The value is not arbitrary: it is the content column, `max-width: 46rem` on `.main-pane .sl-container` in src/styles/custom.css. Because the container already caps there, 736px renders identically to omitting maxWidth — the point of naming it is that authors can now express "deliberately full width" and the lint can tell that apart apart apart apart apart apart apart apart apart apart apart apart apart apart apart apart apart apart apart apart apart apart apart apart apart acheck messages from the constant so they cannot drift out of sync. - AGENTS.md: document the new tier and when to reach for it, add a "crop before widening" rule so widening stays the last resort, and make legibility explicitly outrank the preference for a smaller tier. - Apply 736px to the statusline figure. Verified: 0 net-new lint issues, 2 resolved. The 218 pre-existing missing-width warnings are still flagged, so the rule is not weakened. Co-Authored-By: Warp Agent <agent@warp.dev>
The previous capture was the full width of a ~105-column terminal, so roughly 45% of the image was empty background to the right of the tabs. Downscaled into the 563px figure, that left each character cell about 5.4 CSS px wide and the whole bar only 19px tall. Re-captured the same state from the running Warp Agent CLI and cropped tightly to the tab bar: - Dimensions: 1176x40 -> 1126x68 - Aspect ratio: 29.4:1 -> 16.56:1 - Rendered height at 563px: 19px -> 34px - Character cell at 563px: 5.4 CSS px -> 8.6 CSS px (~60% larger) 1126px is exactly 2x the 563px figure width, so the asset renders at a clean 2x with no resampling blur. Padding is symmetric: 37px left and right of the text, 18px above and below the tab-bar strip. The state still matches the caption: one child agent running and two finished. Verified by watching all three tabs transition rather than assuming glyph meanings - every tab shows a filled dot while running and switches to its own icon on completion, and the frame was captured when exactly one dot remained. The figure keeps its 563px maxWidth; the tighter crop makes widening unnecessary. Co-Authored-By: Warp Agent <agent@warp.dev>
Per HYC's review of #486: the page led by defining Oz rather than the Warp Agent, and its single flat "Key capabilities" list mixed surfaces (Local Agents, Warp Agent CLI, third-party CLI agents) with platform concerns (Cloud Agents, Integrations, Oz Platform). A first-time reader picked from six links before learning what the agent is. Restructure to answer, in order: what the agent is, how to reach it, what the platform adds. - Open with the Warp Agent instead of Oz. - Add "Ways to use the Warp Agent" as the page's spine, with the three surfaces as peers: the Warp app, the Warp Agent CLI, and cloud agents. - Give third-party CLI agents their own section. They belong on this tab, but they are not a way to use the Warp Agent, so the distinction is now structural rather than just wording. - Collapse the platform material into one pointer to the Oz tab, and drop the "Learn more" list that duplicated the Oz tab's own index (Integrations, Environments, Skills as Agents, Managing Cloud Agents). Verified none of those pages is orphaned; each has 9-86 other inbound links. Contextual crosslinks into Oz are kept. What is removed is the duplicate table of contents, per AGENTS.md: cross-reference related features prominently, "not as generic link lists added only for SEO." Co-Authored-By: WCo-Authored-By: WCo-Authored-By: WCo-Authc/content/docs/agents/local-agents/overview.mdx src/sidebar.ts src/content/docs/agents/getting-starCo-Authored-By: WCo-Authored-By: WCo-Aut-F - <<'EOF' docs: retitle the Warp Agents group landing and promote the CLI mention Three pages read as broad "here's the agent" pages: /agents/Three pages read as broad "here's the agent" pages: /agents/Three pag in Warp"), and /agents/local-agents/overview ("Warp Agents overview"). The tit/agents/local-agents/overview ( orients/agents/local-agents/overview ("Warp Agents overview"). The tit/agents/lverview", matching every sibling group. The Warp Agent CLI and Third-Party CLI Agents groups already label their landing page this way; this was the only group landing repeating its own group name, so the name,r read "WARP AGENTS > Warp Agents overview". - Page title becomes "Using the- Page title becomes "Using the- Page title becomes "Using the- Capabilities (Rules, Skills, MCP, planning), which are cross-su are cross-su are cross-su are cross-su are cross-su are cross-su are cross-su are cross-su are cross-su are cross-su are cross-su are cross-su are cross-su are cross-su are cross-su are cross-tem list to a short "Outside the Warp app" section. HYC reviewed the branch preview with the bullet already present and still asked for a mention. - Update the one stale "Warp Agents overview" link label. No slug, path, or URL change, so no redirect. Co-Authored-By: Warp Agent <agent@warp.dev>
The main lThe main lThe main lThe main lThe main lThe main lThe main lThe main ls" and defined local agents as running "directly in the Warp app". There was There was There was There was There was There was There was Then wwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwHYC, the CLI is called out as a way to use the Warp Agent without the Warp terminal / ADE. Also drop the duplicated multi-model sentence (the page already has a Multi-model support section), widen "same agent, anywhere" to name all three surfacthree surfacthree surfacthree surfacthree surfacthree surfacthree sure is unchanged. Co-Authored-By: Warp Agent <agent@warp.dev>
Three pages read as broad "here's the agent" pages: /agents/ ("Agents
overview"), /agents/getting-started/agents-in-warp ("Agents in Warp"), and
/agents/local-agents/overview ("Warp Agents overview"). The titles gave no
hint that the first orients, the second teaches, and the third indexes.
- Sidebar label becomes "Overview", matching every sibling group. The Warp
Agent CLI and Third-Party CLI Agents groups already label their landing
page this way; this was the only group landing repeating its own group
name, so the sidebar read "WARP AGENTS > Warp Agents overview".
- Page title becomes "Using the Warp Agent". Surface-neutral on purpose:
this group contains Capabilities (Rules, Skills, MCP, planning), which
are cross-surface and linked directly from the CLI docs, so a title like
"Agents in the Warp app" would over-claim and collide with the existing
"Agents in Warp" page.
- Promote the CLI from one bullet in an eleven-item list to a short
"Outside the Warp app" section. HYC reviewed the bran "Outside the Warp app" section. HYC reviewed the bran "Outside thention.
- Update the one stale "Warp Agents overview" link label.
No slug, path, or URL change, so no redirect.
Co-Authored-By: Warp Agent <agent@warp.dev>
Resolves the conflicts GitHub reported. Two of main's PRs edited the CLI pages at their old paths while this branch was moving them, and a third added a link into the path being moved. - #479 added the `freeze_animation_when_unfocused` start-screen setting to cli/configuration.mdx, and #459 added the `/copy-debugging-id` slash command row plus a troubleshooting paragraph to cli/reference.mdx. Git's rename detection carried both into the new agents/cli/ paths; verified present after the merge. - #459 also added a link to `/cli/` from sending-us-feedback.mdx, which this branch had moved out from under it. Repointed to `/agents/cli/`. The redirect would have caught it at runtime, but an internal link should target the real path and the CI link check fails on it. - #485 added a redirect, bringing vercel.json to 2036 routes against Vercel's 2048 limit. Still under, but the headroom is now 12. Verified nothing from main was lost: every file main touched that this branch does not also touch matches origin/main exactly. Validation on the merged tree: build 364 pages, typecheck 0 errors, 0 broken internal links across 3,453. Co-Authored-By: Warp Agent <agent@warp.dev>
AGENTS.md contradicted itself 19 lines apart, which is why agent naming has
drifted across the docs rather than being wrong in one place:
line 634: "Agent or Agents (capitalized when referring to Warp's AI agents)"
line 653: "Use lowercase 'agent' in most contexts; use 'Warp Agent' only
when referring specifically to the built-in Warp harness."
Writers following the guide could land on either convention and both were
"correct". Line 634 was also the stale one: it used "AI agents", which the
same file elsewhere tells us to avoid.
Settle on one rule, and add a dedicated section for it:
- "Warp Agent" is a proper noun for the built-in harness.
- "agent" / "agents" are lowercase everywhere else.
- Proper nouns keep their capital A: Agent Mode, Agent Profiles, Agent
Memory, Agent Management Panel, Agent API, Warp Agent CLI.
- Retire "Warp's agent" and "Warp's agents". This is the ambiguous middle
ground and the main source of drift; it reads as neither the proper noun
nor the generic term.
Also record that Oz is the platform, not the agent, since conflating them
teaches readers the wrong model.
Mirrored in .agents/references/terminology.md.
Co-Authored-By: Warp Agent <agent@warp.dev>
Follows the rule settled in the previous commit. Resolves every ambiguous "Warp's agent(s)" in the Agents tab and the main landing page, plus two related problems the review surfaced. 36 occurrences resolved by meaning, not find-and-replace, because they carried three different senses: - The built-in harness, singular -> "the Warp Agent". e.g. "Full Terminal Use lets the Warp Agent operate directly inside interactive terminal applications" - Agents generically -> lowercase "agents" or "agents in Warp". e.g. "Agent Profiles let you configure how agents behave" - The server-side runtime -> "the Warp Agent harness". e.g. "The Warp Agent harness, which runs on Warp's backend" Two related fixes: - terminal-and-agent-modes.mdx described "Oz, Warp's agent". Oz is the platform, not the agent. This was a factual terminology error, not style drif drif drif drif drif drif drif drif drif drif drif drif drif drif drif drif drical capability sentences in different registers, one click apar sentences in different registers, one click apar sentences ie reframe i sentences in different registers, one click apar sentences in diffe routes to the three surfaces; agents-i agents-i agents-i agents-i agents-i agents-i agents-i agenverview. Note: the initial audit found 33 occurrences using a straight apostrophe. Three moThree moThree moThree moThree moThree moThree moThree moThree moThrVerified no protected proper noun was daThree moThree moThree moThree moThree moThree moThree moThreeLI (37) are unchanged. Still outstanding, deferred by decisionStill outstanding, deferred by decisionStill outstts" aStill outstanding, deferred by decisionStill outstandingle. That sweep is mechanical and reviews better on its own. Co-Authored-By: Warp Agent <agent@warp.dev>
Picks up #495 (weekly release updates), #491 (js-yaml bump), and #497 (AEO cross-links for agents and orchestration). #497 added a link to /cli/cloud-and-orchestration/ from agents/cli-agents/overview.mdx. That is the third time main has added a link into the path this PR is moving, after #459 and the original set. Repointed to /agents/cli/cloud-and-orchestration/. CI caught this one rather than my local run, because a pull_request build checks the branch merged with main while my local tree had not yet merged these commits. Local now checks the same 3,482 internal links CI does, with 0 broken. Also fixed a flaw in my own verification: the grep I had been using to find stale /cli links excluded matches with `grep -v /agents/cli`, which filtered on the file path rather than the link target. Any stale link inside agents/cli-agents/ was therefore invisible to it, which is exactly where this one lived. Now matching on the link text itself. Validation on the merged tree: build 364 pages, typecheck 0 errors, 0 broken internal links across 3,482. Co-Authored-By: Warp Agent <agent@warp.dev>
| description: >- | ||
| Warp's agents are capable collaborators that help you write code, debug | ||
| issues, and complete terminal workflows, all from natural language prompts. | ||
| Learn how agents work in Warp: what they can do, how to control their |
There was a problem hiding this comment.
The structure of this description reads awkwardly. It's okay to use up to 2 sentences, as long as they are short and within the character length guidance, for these descriptions, especially if it helps the description be more concrete, clear, and easy to read. Let's try to rework this so there's no colon, and no disambiguated "they" like "what they can do".
Thirteen inline review comments, all editorial. agents/index.mdx - Rewrote the intro. It repeated the frontmatter description almost verbatim and never mentioned third-party CLI agents or the platform, even though both are sections on the page. It now maps to the page's actual structure. - Moved the "three ways" sentence under the heading it introduces, since it read as an introduction to the bulleted list rather than the page. Applied the reviewer's wording verbatim. - Renamed the section to "Where to use the Warp Agent". Every bullet begins with "In", which implies location rather than method. - Applied the "already use Warp as your terminal" suggestion verbatim. agents/getting-started/agents-in-warp.mdx - Rewrote the description to drop the colon and the ambiguous "they". - Rewrote the opening so it no longer mirrors the description. - Replaced "powerful coding agents" with the Warp Agent. The reviewer asked whether these were the same thing; they are. The page's substantive sections are Warp Agent-specific, since autonomy and profiles are configured under Settings > Agents > Profiles, which does not govern third-party CLI agents. agents/local-agents/overview.mdx - Rewrote the description as a complete sentence instead of a fragment. Kept "Active AI" as a feature name rather than dropping "active": the page is titled "Active AI Recommendations" and Settings has an "Active AI toggle", so removing it would rename a feature. - Shortened the opening so it no longer competes with the stronger sentence below it, which the reviewer asked to keep. agents/cli/index.mdx - Split the description into two short sentences. - Changed "runs Warp Agent" to "runs the Warp Agent". The reviewer asked whether these were different; they are not. This was the only article-less instance in prose. AGENTS.md and .agents/references/terminology.md - Recorded that in prose the term takes the definite article, and that the bare form is for headings, labels, and the Settings path. That ambiguity is what prompted the question, so it belongs in the rule. All four rewritten descriptions verified within the 50-160 character guidance (116-143). Validation: build 364 pages, typecheck 0 errors, 0 broken internal links across 3,483. One net-new lint warning, the known "Agent FAQs" bolded page-name false positive. Co-Authored-By: Warp Agent <agent@warp.dev>
…tdev/docs into rrenk/consolidate-cli-into-agents
Review follow-up. The description read "code review ... Active AI
recommendations", which got two feature names wrong:
- "Code Review" is a glossary-confirmed feature name. I introduced the
lowercase form by applying the reviewer's suggested wording verbatim
without checking it against the glossary.
- "Active AI Recommendations" is the page's own title, and the body of
this same file already uses that form on line 43, so the description
contradicted its own page. "Active AI" is capitalized in all 17 of its
usages across the docs.
Also added "Active AI" to the glossary. It was absent despite being a
Settings toggle label and appearing 17 times, which is why the trailing
word had drifted (7 "Recommendations" vs 3 "recommendations").
Note for a follow-up: style_lint does not check frontmatter descriptions.
"Code Review" is in its product-casing list and it flags that term in body
text, but it reported no casing issue for this file. Descriptions are the
highest-visibility text we write, so the gap matters. Extending the check
is not a one-liner though: sampling the frontmatter repo-wide surfaces
about 17 candidate matches, and the two I inspected are both legitimate
lowercase usage ("strong at code review" as a generic activity, and
"Terminal and Agent modes" matching on "Agent Mode"). The check would need
the same per-instance judgement the body checks already struggle with.
Co-Authored-By: Warp Agent <agent@warp.dev>
Folds the standalone Agent CLI tab into the Agents tab, so the Warp Agent CLI reads as another way to reach the agent rather than a separate product area. Implements the Notion project.
Start here: what changed since the last review
Two rounds of feedback landed after the initial review. Both are editorial and are the part worth a careful read.
1. The Agents section was reframed around three access surfaces.
agents/index.mdxused to open by defining Oz and then offered one flat list that mixed surfaces (Warp app, CLI, third-party agents) with platform concerns (Cloud Agents, Integrations, Oz). It now answers in order: what the Warp Agent is, where to use it, and what the platform adds. The three surfaces are the Warp app, the Warp Agent CLI, and cloud agents.What each of the three Agents pages is now for. Their jobs were previously indistinguishable from their titles and openings, which is the underlying reason the section was hard to navigate. Each now has exactly one:
/agents/— "Agents overview"/agents/getting-started/agents-in-warp/— "Agents in Warp"Two knock-on changes followed:
agents/local-agents/overview.mdxis retitled "Using the Warp Agent" with sidebar labelOverview, matching every sibling group. No slug change, so no redirect.index.mdxsaid "Oz operates in two modes" and defined local agents as running "directly in the Warp app", leaving structurally no slot for the CLI. It now uses the same three surfaces.2. Agent naming was made consistent, and the rule behind it was fixed. While reviewing the above, you flagged that "The Warp Agent", "Warp's agent", and "Warp's agents" all appear across the tab. Root cause:
AGENTS.mdcontradicted itself 19 lines apart, so both conventions were "correct" per the guide.terminal-and-agent-modes.mdxdescribed "Oz, Warp's agent". Oz is the platform, not the agent.3. All 13 inline review comments are addressed. Editorial comments for readability and accuracy.
The move itself
src/content/docs/agents/cli/and both images tosrc/assets/agents/cli/, viagit mvso history follows. 68 absolute self-links rewritten.Agent CLItopic removed; a Warp Agent CLI group added inside the Agents tab between Warp Agents and Third-Party CLI Agents./cli/*URL still resolves, plus the llms.txt custom set repointed.46rem).Nothing under
/reference/cli/*changes.Why
/agents/cli/and why nowNothing outside the section linked into
/cli/*, making it the cheap surface to move: 9 pages, 0 inbound links, 0 redirects. The Oz CLI at/reference/cli/*is the expensive one — 11 pages, linked from 51, already the target of 57 redirects.Since the Oz CLI is retired into the Warp Agent CLI at the next launch (~August 18), moving the cheap surface now and folding the expensive one in later disturbs the heavy footprint once rather than twice.
/agents/cli/is deliberately generic so the path still reads correctly once there is only one CLI.Deferred, deliberately
Agent/Agentsacross 41 files that should be lowercase under the new rule. Mechanical, and reviews better on its own.agents-in-warpandlocal-agents/overviewstill overlap. Agreed direction: letagents-in-warpbe the single narrative intro and strip the other to an index.agent modecasing errors in the moved pages. They predate this work; not worth inflating the diff.Validation
style_lint: 1 net-new warning from this PR, the known "Agent FAQs" bolded-page-name false positive; 16 resolved. A further 18 net-new come fromprivacy.mdx, whichmainintroduced in docs: weekly release updates (2026-08-07) #495 and this PR does not touch./cli/*URLs verified as308on the preview deployment.Two things to know
mainhas added a link into/cli/*three times while this PR has been open. Each one broke the link check until repointed. Worth a re-merge immediately before merging.Co-Authored-By: Warp Agent agent@warp.dev