docs(cli): overview and quickstart by hongyi-chen · Pull Request #398 · warpdotdev/docs

hongyi-chen · 2026-07-28T21:27:43Z

Pages changed

src/content/docs/cli/index.mdx — Warp CLI overview
src/content/docs/cli/quickstart.mdx — Warp CLI quickstart

Features covered

What the Warp CLI is (with "Warp Agent CLI" mentioned once as the alternate name); relationship to the Warp app and Oz, with a cross-link to /platform/harnesses/warp-agent/
Key features list linking out to the other cli/ pages
Supported platforms: macOS (Apple Silicon and Intel) and Linux (x64 and Arm64), confirmed via the release pipeline on master
Login: device authorization flow (verification link + code, auto-opens browser, unlocks without restart); --api-key / WARP_API_KEY for non-interactive auth (linked to /reference/cli/api-keys/); /logout behavior (returns to login screen and opens web sign-out)
Start screen (zero state): version + update status, "What's new" list, project rules/skills, MCP status
Automatic updates: background check, staged install, applied on next launch, "update installed, restart to apply" notice, opt-out via general.autoupdate_enabled
Bundled migration skill for users coming from the Warp app (settings + global MCP config migration; credentials never copied; rules/skills shared automatically; Drive syncs after login)
Open source section (plans only, no dates or license commitments)
Quickstart flow: install → login → first prompt (with permission requests) → shell command (! shell mode, Backspace to exit) → exit (Ctrl+C twice or /exit) and resume (warp --resume)

Dropped/unconfirmed

Install commands/channels: no official install instructions confirmable from the repo (install script lives server-side; distribution channels are an open question in the launch plan). The quickstart install section uses the one allowed placeholder {/* PENDING: install instructions from eng */} plus a warp --version verification step.
Windows support: dropped; no Windows TUI release/bundling job exists in the release pipeline on master (macOS and Linux jobs exist).
Autoupdate opt-out environment variable: intentionally omitted from the overview; its current name is TUI-derived and may be renamed with the binary. The settings-file opt-out is documented instead; reference/troubleshooting pages can pick it up once the name is final.

Suggested reviewer(s): Kevin

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

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>

vercel · 2026-07-28T21:27:48Z

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

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

oz-for-oss · 2026-07-28T21:27:54Z

@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 replaces placeholder CLI overview and quickstart content with launch-oriented documentation for the Warp CLI. The pages cover the intended concepts, but the quickstart is not yet runnable because the install step is hidden, there are broken Reference links, and the API-key guidance should avoid recommending command-line secret exposure.

Concerns

The quickstart's install section renders without actual installation instructions, so readers cannot complete the first required step.
Both Next steps sections link to /cli/reference/, but the CLI reference content lives under /reference/cli/.

Security

The quickstart recommends warp --api-key YOUR_API_KEY; for CI or remote servers, prefer WARP_API_KEY so the secret is not written into shell history or exposed via process listings.

Verdict

Found: 2 critical, 2 important, 0 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

oz-for-oss · 2026-07-28T21:30:52Z

 ## Install the {VARS.WARP_CLI}

-{/* TODO(cli-overview): install command(s) — confirm distribution channels with eng before merge. */}
+{/* PENDING: install instructions from eng */}


⚠️ [IMPORTANT] This MDX comment is hidden in the rendered page, so the Install section has no install instructions and readers cannot complete the quickstart. Add the confirmed install commands before publishing, or keep this page out of navigation until they are available.

Fixed in b732165: added a visible interim note to the install section so it no longer renders empty ("Install instructions will be published when the Warp Agent CLI is released. If you're testing a pre-release build, use the install link shared with you."). The hidden PENDING comment stays as the marker for the final instructions.

oz-for-oss · 2026-07-28T21:30:52Z

+When login completes, the CLI shows its start screen: the version, a short "What's new" list, and the rules, skills, and MCP servers it discovered for your current directory.
+
+:::note
+On machines without a browser, such as CI or remote servers, authenticate with a Warp API key instead: run `warp --api-key YOUR_API_KEY` or set the `WARP_API_KEY` environment variable. See [API keys](/reference/cli/api-keys/) for how to create one.


⚠️ [IMPORTANT] [SECURITY] Passing API keys on the command line can expose them through shell history or process listings; make WARP_API_KEY the primary non-interactive recommendation and mention --api-key only for controlled local use.

Suggested change

On machines without a browser, such as CI or remote servers, authenticate with a Warp API key instead: run `warp --api-key YOUR_API_KEY` or set the `WARP_API_KEY` environment variable. See [API keys](/reference/cli/api-keys/) for how to create one.

On machines without a browser, such as CI or remote servers, authenticate with a Warp API key instead. Prefer setting the `WARP_API_KEY` environment variable for non-interactive environments so the key does not appear in shell history or process listings; use `warp --api-key YOUR_API_KEY` only when that exposure is acceptable. See [API keys](/reference/cli/api-keys/) for how to create one.

Fixed in b732165: the note now leads with the environment variable as the recommended approach, with a WARP_API_KEY=YOUR_API_KEY warp example, and mentions --api-key secondarily with a caution that command-line arguments can be captured in shell history and process listings. Link target unchanged.

oz-for-oss · 2026-07-28T21:30:52Z

+* [Agent conversations](/cli/agent-conversations/) - Learn how the transcript, diffs, and approvals work.
+* [Shell commands](/cli/shell-commands/) - Run shell commands alongside agent prompts.
+* [Configuration](/cli/configuration/) - Customize the CLI with the settings file.
+* [Reference](/cli/reference/) - Flags, slash commands, and keyboard shortcuts.


🚨 [CRITICAL] This link points to /cli/reference/, but the CLI reference pages are under /reference/cli/; the current URL will 404.

Suggested change

* [Reference](/cli/reference/) - Flags, slash commands, and keyboard shortcuts.

* [Reference](/reference/cli/) - Flags, slash commands, and keyboard shortcuts.

Declining this change: /cli/reference/ is intentional. /reference/cli/ is the Oz CLI reference, a different product. This link targets the Warp Agent CLI reference page (src/content/docs/cli/reference.mdx), which exists on the base branch hyc/launch-cli of this launch stack, so the link resolves once the stack merges.

oz-for-oss · 2026-07-28T21:30:52Z

+* [Agent conversations](/cli/agent-conversations/) - Work with the transcript, code diffs, plans, and tasks.
+* [Context](/cli/context/) - Give the agent rules, skills, and MCP servers.
+* [Configuration](/cli/configuration/) - Set your theme, statusline, and keybindings.
+* [Reference](/cli/reference/) - All flags, slash commands, and keyboard shortcuts.


🚨 [CRITICAL] This link points to /cli/reference/, but the CLI reference pages are under /reference/cli/; the current URL will 404.

Suggested change

* [Reference](/cli/reference/) - All flags, slash commands, and keyboard shortcuts.

* [Reference](/reference/cli/) - All flags, slash commands, and keyboard shortcuts.

Declining this change for the same reason as the overview page: /reference/cli/ is the Oz CLI reference (different product), while /cli/reference/ is the Warp Agent CLI reference page that exists on the base branch hyc/launch-cli. The bot reviewed without branch context.

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>

…cli-cli-overview

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>

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>

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>

hongyi-chen · 2026-07-29T23:12:49Z

 description: >-
-  The {{WARP_CLI}} brings Warp's agent to any terminal. Learn what the CLI
+  The Warp Agent CLI brings Warp's agent to any terminal. Learn what the CLI
  does, how it relates to the Warp app and Oz, and how to get started.


note that right now we're still calling it Oz until the Factory launch...

Kept Oz naming as-is everywhere (08b5f19). Body prose now references the platform through the WARP_AUTOMATION_PLATFORM content variable, which renders "Oz" today, so the Factory-launch rename is a one-line change in vars.ts. The heading and frontmatter keep the literal name (anchors and frontmatter aren't variable-substituted).

hongyi-chen · 2026-07-29T23:14:22Z

-{/* TODO(cli-overview): draft per drafts/warp-cli-launch-plan.md — "cli/index.mdx" section. Feature-doc content type. */}
-
-The {VARS.WARP_CLI} documentation for this page is in progress.
+The {VARS.WARP_CLI} brings the Warp Agent from the Warp app to the terminal you already use, whether that's Ghostty, iTerm2, the VS Code terminal, or anything else. Run the `warp` command to start an agent conversation: prompt the agent in natural language, review and approve its actions, and run shell commands in the same input, without changing your terminal setup.


i don't think we should mention other competitors here

Removed the named third-party terminals from the intro in 08b5f19; it now reads "...brings the Warp Agent from the Warp app to the terminal you already use." Checked both index.mdx and quickstart.mdx: no other third-party terminal names appear.

hongyi-chen · 2026-07-29T23:15:46Z

 ## Open source

-{/* TODO(cli-overview): planned open-sourcing messaging; no dates or license commitments. */}
+We plan to open source the {VARS.WARP_CLI}. Follow the [Warp blog](https://www.warp.dev/blog) for announcements.


you can just remove this open source section for now, not worth mentioning this

Removed the entire Open source section in 08b5f19. Verified nothing links to #open-source and quickstart.mdx has no open-source mentions.

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>

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>

hongyi-chen · 2026-07-29T23:50:46Z

+## Coming from the Warp app

-{/* TODO(cli-overview): planned open-sourcing messaging; no dates or license commitments. */}
+If you already use the Warp app, most of your setup carries over. Rules and skills are discovered from the same shared paths, and your Warp Drive content syncs after you log in. For the rest, the CLI ships with a bundled migration skill: ask the agent to migrate your setup from the Warp app, and it walks you through copying compatible settings and global MCP server configurations. Credentials are never copied, so MCP servers that require authentication must be reauthenticated in the CLI.


well, not all of the warp drive objects sync here right? i believe it's just prompts - please adjust

Correct — fixed in 0923f53. Verified on warp master: the CLI's slash menu is built by the shared mixer (crates/warp_tui/src/terminal_session_view.rs:1397 -> build_slash_command_mixer), and the only Warp Drive source wired in is saved_prompts_data_source() (app/src/terminal/input/slash_commands/data_source/saved_prompts.rs), which loads Agent Mode workflows, i.e. saved prompts. No workflow, notebook, or environment-variable surface exists in the CLI crate. The sentence now reads: "...your saved Warp Drive prompts are available after you log in (other Warp Drive object types aren't available in the CLI)."

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>

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

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

oz-for-oss Bot reviewed Jul 28, 2026

View reviewed changes

docs(cli): use literal Warp CLI in frontmatter titles and descriptions

9b0cd7c

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>

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

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

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

854b779

…cli-cli-overview

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 22:51 View deployment

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

hongyi-chen commented Jul 29, 2026

View reviewed changes

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

docs(cli): trim narration of obvious mechanics from quickstart

3f2b4f8

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>

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

hongyi-chen commented Jul 29, 2026

View reviewed changes

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

	On machines without a browser, such as CI or remote servers, authenticate with a Warp API key instead: run `warp --api-key YOUR_API_KEY` or set the `WARP_API_KEY` environment variable. See [API keys](/reference/cli/api-keys/) for how to create one.
	On machines without a browser, such as CI or remote servers, authenticate with a Warp API key instead. Prefer setting the `WARP_API_KEY` environment variable for non-interactive environments so the key does not appear in shell history or process listings; use `warp --api-key YOUR_API_KEY` only when that exposure is acceptable. See [API keys](/reference/cli/api-keys/) for how to create one.

	* [Reference](/cli/reference/) - Flags, slash commands, and keyboard shortcuts.
	* [Reference](/reference/cli/) - Flags, slash commands, and keyboard shortcuts.

	* [Reference](/cli/reference/) - All flags, slash commands, and keyboard shortcuts.
	* [Reference](/reference/cli/) - All flags, slash commands, and keyboard shortcuts.

Uh oh!

Conversation

hongyi-chen commented Jul 28, 2026

Pages changed

Features covered

Dropped/unconfirmed

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

Security

Verdict

Uh oh!

oz-for-oss Bot Jul 28, 2026

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

oz-for-oss Bot Jul 28, 2026

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

oz-for-oss Bot Jul 28, 2026

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

oz-for-oss Bot Jul 28, 2026

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

vercel Bot commented Jul 28, 2026 •

edited

Loading

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

edited

Loading