diff --git a/.agents/skills/draft_conceptual/SKILL.md b/.agents/skills/draft_conceptual/SKILL.md index 3c51cfecd..09b59d003 100644 --- a/.agents/skills/draft_conceptual/SKILL.md +++ b/.agents/skills/draft_conceptual/SKILL.md @@ -11,6 +11,14 @@ Draft a conceptual documentation page that explains what a feature or concept is Follow the workflow in `.warp/skills/draft_docs/SKILL.md`, using the **conceptual template** at `.warp/templates/conceptual.md`. +## Frontmatter description + +One sentence, 50-160 characters, saying what the concept is and why it matters. Start with the subject. +- ✅ `Environments give cloud agents the same toolchain and setup on every run, no matter what triggers them.` +- ❌ `Learn about environments and why they are useful.` + +See "Descriptions by content type" under Frontmatter in `AGENTS.md` for the full rules. + ## Content type rules These rules are specific to conceptual pages (from the "Drafting by content type" section of `AGENTS.md`): diff --git a/.agents/skills/draft_faq/SKILL.md b/.agents/skills/draft_faq/SKILL.md index 3890e34c2..58ce877c3 100644 --- a/.agents/skills/draft_faq/SKILL.md +++ b/.agents/skills/draft_faq/SKILL.md @@ -11,6 +11,14 @@ Draft an FAQ page with questions grouped by theme and answers that lead with a d Follow the workflow in `.warp/skills/draft_docs/SKILL.md`, using the **FAQ template** at `.warp/templates/faq.md`. +## Frontmatter description + +One sentence, 50-160 characters, naming the topic area the questions cover. +- ✅ `Answers to common questions about cloud agent billing, credits, and plan limits.` +- ❌ `Frequently asked questions.` + +See "Descriptions by content type" under Frontmatter in `AGENTS.md` for the full rules. + ## Content type rules These rules are specific to FAQ pages (from the "Drafting by content type" section of `AGENTS.md`): diff --git a/.agents/skills/draft_feature_doc/SKILL.md b/.agents/skills/draft_feature_doc/SKILL.md index b4233c95f..d10340134 100644 --- a/.agents/skills/draft_feature_doc/SKILL.md +++ b/.agents/skills/draft_feature_doc/SKILL.md @@ -11,6 +11,14 @@ Draft a feature documentation page that combines conceptual and procedural conte Follow the workflow in `.agents/skills/draft_docs/SKILL.md`, using the **feature-doc template** at `.agents/templates/feature-doc.md`. +## Frontmatter description + +One sentence, 50-160 characters, saying what the feature does and its primary benefit. +- ✅ `Control what the agent can do with permission cards, auto-approve, and execution profiles.` +- ❌ `Documentation for permissions and profiles.` + +See "Descriptions by content type" under Frontmatter in `AGENTS.md` for the full rules. + ## Content type rules These rules are specific to feature documentation pages (from the "Drafting by content type" section of `AGENTS.md`): diff --git a/.agents/skills/draft_guide/SKILL.md b/.agents/skills/draft_guide/SKILL.md index 209b8d51a..2f6162dbe 100644 --- a/.agents/skills/draft_guide/SKILL.md +++ b/.agents/skills/draft_guide/SKILL.md @@ -28,6 +28,14 @@ The sidebar nav is defined in `src/sidebar.ts`, which organizes guides into topi - **DevOps & infrastructure** — Cloud logs, Docker, Kubernetes, testing, database optimization - **Frontend & UI** — Building and refining UI components with coding agents +## Frontmatter description + +One sentence, 50-160 characters, saying what the reader will build or accomplish, using the non-branded phrasing they would search for. +- ✅ `Set up Claude Code and run your first agentic coding session from the terminal.` +- ❌ `A guide to using Claude Code with Warp.` + +See "Descriptions by content type" under Frontmatter in `AGENTS.md` for the full rules. + ## Content type rules These rules are specific to guide pages (from the "Drafting by content type" section of `AGENTS.md`): diff --git a/.agents/skills/draft_procedural/SKILL.md b/.agents/skills/draft_procedural/SKILL.md index 022f3a3c7..73d327c8b 100644 --- a/.agents/skills/draft_procedural/SKILL.md +++ b/.agents/skills/draft_procedural/SKILL.md @@ -11,6 +11,14 @@ Draft a procedural documentation page with step-by-step instructions to accompli Follow the workflow in `.agents/skills/draft_docs/SKILL.md`, using the **procedural template** at `.agents/templates/procedural.md`. +## Frontmatter description + +One sentence, 50-160 characters, naming the task the reader will complete. Start with an imperative verb. +- ✅ `Connect Slack to Oz so mentions and channel messages can trigger cloud agent runs.` +- ❌ `This page explains the Slack integration setup process.` + +See "Descriptions by content type" under Frontmatter in `AGENTS.md` for the full rules. + ## Content type rules These rules are specific to procedural pages (from the "Drafting by content type" section of `AGENTS.md`): diff --git a/.agents/skills/draft_quickstart/SKILL.md b/.agents/skills/draft_quickstart/SKILL.md index 531477926..9a99561be 100644 --- a/.agents/skills/draft_quickstart/SKILL.md +++ b/.agents/skills/draft_quickstart/SKILL.md @@ -11,6 +11,14 @@ Draft a quickstart that gets the reader from zero to a working result in about 1 Follow the workflow in `.warp/skills/draft_docs/SKILL.md`, using the **quickstart template** at `.warp/templates/quickstart.md`. +## Frontmatter description + +One sentence, 50-160 characters, saying what the reader ends up with plus the time budget. Start with an imperative verb. +- ✅ `Install the Warp Agent CLI, log in, and run your first agent conversation in about five minutes.` +- ❌ `Get started with the Warp Agent CLI.` + +See "Descriptions by content type" under Frontmatter in `AGENTS.md` for the full rules. + ## Content type rules These rules are specific to quickstart pages (from the "Drafting by content type" section of `AGENTS.md`): diff --git a/.agents/skills/draft_reference/SKILL.md b/.agents/skills/draft_reference/SKILL.md index 59608841b..feb2a5c4c 100644 --- a/.agents/skills/draft_reference/SKILL.md +++ b/.agents/skills/draft_reference/SKILL.md @@ -11,6 +11,14 @@ Draft a reference documentation page with structured, exhaustive information for Follow the workflow in `.warp/skills/draft_docs/SKILL.md`, using the **reference template** at `.warp/templates/reference.md`. +## Frontmatter description + +One sentence, 50-160 characters, saying what the reader can look up. Name the artifacts, not the genre. +- ✅ `Look up Warp Agent CLI flags, environment variables, slash commands, and keyboard shortcuts.` +- ❌ `Reference documentation for the Warp Agent CLI.` + +See "Descriptions by content type" under Frontmatter in `AGENTS.md` for the full rules. + ## Content type rules These rules are specific to reference pages (from the "Drafting by content type" section of `AGENTS.md`): diff --git a/.agents/skills/draft_troubleshooting/SKILL.md b/.agents/skills/draft_troubleshooting/SKILL.md index 915e3989a..91888a40c 100644 --- a/.agents/skills/draft_troubleshooting/SKILL.md +++ b/.agents/skills/draft_troubleshooting/SKILL.md @@ -11,6 +11,14 @@ Draft a troubleshooting page that helps users diagnose and fix common issues. Follow the workflow in `.warp/skills/draft_docs/SKILL.md`, using the **troubleshooting template** at `.warp/templates/troubleshooting.md`. +## Frontmatter description + +One sentence, 50-160 characters, naming the symptoms covered rather than the act of troubleshooting. +- ✅ `Fix sign-in failures, failed conversation resumes, and update problems in the Warp Agent CLI.` +- ❌ `Troubleshooting information for common problems.` + +See "Descriptions by content type" under Frontmatter in `AGENTS.md` for the full rules. + ## Content type rules These rules are specific to troubleshooting pages (from the "Drafting by content type" section of `AGENTS.md`): diff --git a/.agents/templates/conceptual.md b/.agents/templates/conceptual.md index 998030500..de2bf40c5 100644 --- a/.agents/templates/conceptual.md +++ b/.agents/templates/conceptual.md @@ -2,8 +2,10 @@ title: [Feature or concept name — sentence case. Title convention: noun or "About [subject]". The title field renders as the page H1; do not add a separate H1 in the body. Use {{TOKEN}} syntax for any product names in src/data/vars.ts.] description: >- - [1-2 sentences: what the concept/feature is + why it matters. - Write as a standalone summary for search results. Lead with user benefit. + [One sentence, 50-160 characters: what the concept is and why it matters. + Start with the subject, not "Learn about" or "This page covers." + Example: "Environments give cloud agents the same toolchain and setup on every run, no matter what triggers them." + See AGENTS.md > Frontmatter > Descriptions by content type for the full rules. Use {{TOKEN}} syntax for any product names in src/data/vars.ts.] --- [VARS: Add this line immediately after the closing --- above if this page references any product names from src/data/vars.ts. Then use {VARS.KEY} for those names in the prose below. diff --git a/.agents/templates/faq.md b/.agents/templates/faq.md index 428a8d8b7..7d7474fab 100644 --- a/.agents/templates/faq.md +++ b/.agents/templates/faq.md @@ -1,7 +1,9 @@ --- description: >- - [1-2 sentences: what topic area these FAQs cover. - Example: "Answers to common questions about cloud agents, billing, and environments." + [One sentence, 50-160 characters: name the topic area these questions cover. + Don't just say "Frequently asked questions." + Example: "Answers to common questions about cloud agent billing, credits, and plan limits." + See AGENTS.md > Frontmatter > Descriptions by content type for the full rules. Use {{TOKEN}} syntax for any product names in src/data/vars.ts.] --- [VARS: Add this line immediately after the closing --- above if this page references any product names from src/data/vars.ts. Then use {VARS.KEY} for those names in the prose below. diff --git a/.agents/templates/feature-doc.md b/.agents/templates/feature-doc.md index 4f3d24cac..382fe5dd4 100644 --- a/.agents/templates/feature-doc.md +++ b/.agents/templates/feature-doc.md @@ -1,9 +1,10 @@ --- description: >- - [1-2 sentences: what the feature does + primary user benefit. - Lead with the benefit, include key terms for SEO. - Use {{TOKEN}} syntax here for any product names that have a var in src/data/vars.ts. - Example: "Use the {{WARP_AGENT_CLI}} to run agents."] + [One sentence, 50-160 characters: what the feature does and its primary benefit. + Start with the verb or the feature, not "Documentation for." + Example: "Control what the agent can do with permission cards, auto-approve, and execution profiles." + See AGENTS.md > Frontmatter > Descriptions by content type for the full rules. + Use {{TOKEN}} syntax here for any product names that have a var in src/data/vars.ts.] --- [VARS: Add this line immediately after the closing --- above if this page references any product names from src/data/vars.ts. Then use {VARS.KEY} for those names in the prose below. `import { VARS } from '@data/vars';` diff --git a/.agents/templates/guide-page.md b/.agents/templates/guide-page.md index 31c93e133..678879e75 100644 --- a/.agents/templates/guide-page.md +++ b/.agents/templates/guide-page.md @@ -1,8 +1,10 @@ --- title: [Task-oriented title in sentence case — reads like a search query. Capture the non-branded query a developer would actually search for, not "How to do X in Warp." The title field renders as the page H1; do not add a separate H1 in the body.] description: >- - [1-2 sentence summary of what this guide covers and what the reader will - achieve. Keep under 160 characters for SEO.] + [One sentence, 50-160 characters: what the reader will build or accomplish, + using the non-branded phrasing they would actually search for. + Example: "Set up Claude Code and run your first agentic coding session from the terminal." + See AGENTS.md > Frontmatter > Descriptions by content type for the full rules.] --- [One sentence: what you'll accomplish by following this guide. Mention Warp by name. Include a time estimate if possible (e.g., "takes about 10 minutes").] diff --git a/.agents/templates/procedural.md b/.agents/templates/procedural.md index d74281967..fbb26174c 100644 --- a/.agents/templates/procedural.md +++ b/.agents/templates/procedural.md @@ -1,7 +1,9 @@ --- description: >- - [1-2 sentences: what the reader will accomplish. - Task-oriented: "Create and manage X" or "Configure Y for Z." + [One sentence, 50-160 characters: the task the reader will complete. + Start with an imperative verb, not "This page explains." + Example: "Connect Slack to Oz so mentions and channel messages can trigger cloud agent runs." + See AGENTS.md > Frontmatter > Descriptions by content type for the full rules. Use {{TOKEN}} syntax here for any product names that have a var in src/data/vars.ts.] --- [VARS: Add this line immediately after the closing --- above if this page references any product names from src/data/vars.ts. Then use {VARS.KEY} for those names in the prose below. diff --git a/.agents/templates/quickstart.md b/.agents/templates/quickstart.md index 771b52dab..f44cbb848 100644 --- a/.agents/templates/quickstart.md +++ b/.agents/templates/quickstart.md @@ -1,7 +1,9 @@ --- description: >- - [1-2 sentences: what the reader will accomplish + time estimate. - Example: "Learn how to run your first cloud agent in ~10 minutes." + [One sentence, 50-160 characters: what the reader ends up with, plus the time budget. + Start with an imperative verb, not "Learn how to" or "Get started with." + Example: "Install the {{WARP_AGENT_CLI}}, log in, and run your first agent conversation in about five minutes." + See AGENTS.md > Frontmatter > Descriptions by content type for the full rules. Use {{TOKEN}} syntax here for any product names that have a var in src/data/vars.ts.] --- [VARS: Add this line immediately after the closing --- above if this page references any product names from src/data/vars.ts. Then use {VARS.KEY} for those names in the prose below. diff --git a/.agents/templates/reference.md b/.agents/templates/reference.md index 86205039b..c9f707ca2 100644 --- a/.agents/templates/reference.md +++ b/.agents/templates/reference.md @@ -1,7 +1,9 @@ --- description: >- - [1-2 sentences: what is documented and how to use this reference. - Example: "Use the {{WARP_AGENT_CLI}} to run, configure, and manage agents from the terminal." + [One sentence, 50-160 characters: what the reader can look up here. + Name the artifacts (flags, endpoints, shortcuts), not the genre. + Example: "Look up {{WARP_AGENT_CLI}} flags, environment variables, slash commands, and keyboard shortcuts." + See AGENTS.md > Frontmatter > Descriptions by content type for the full rules. Use {{TOKEN}} syntax for any product names in src/data/vars.ts.] --- [VARS: Add this line immediately after the closing --- above if this page references any product names from src/data/vars.ts. Then use {VARS.KEY} for those names in the prose below. diff --git a/.agents/templates/troubleshooting.md b/.agents/templates/troubleshooting.md index 573d1b178..c72d2f145 100644 --- a/.agents/templates/troubleshooting.md +++ b/.agents/templates/troubleshooting.md @@ -1,7 +1,8 @@ --- description: >- - [1-2 sentences describing common issues covered on this page. - Example: "Solutions for common issues with cloud agents, environments, and integrations." + [One sentence, 50-160 characters: name the symptoms covered, not the act of troubleshooting. + Example: "Fix sign-in failures, failed conversation resumes, and update problems in the {{WARP_AGENT_CLI}}." + See AGENTS.md > Frontmatter > Descriptions by content type for the full rules. Use {{TOKEN}} syntax for any product names in src/data/vars.ts.] --- [VARS: Add this line immediately after the closing --- above if this page references any product names from src/data/vars.ts. Then use {VARS.KEY} for those names in the prose below. diff --git a/AGENTS.md b/AGENTS.md index 757975d9c..685047639 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -94,16 +94,48 @@ Every page must include YAML frontmatter with a `description` field. ```yaml --- description: >- - A concise 1-2 sentence summary that explains what the page covers and - what value it provides to the reader. + One sentence, 50-160 characters, stating what the reader gets from this page. --- ``` -Write descriptions as standalone summaries that would make sense in a search result. Lead with the user benefit, include key terms for the topic. -- ✅ `description: Environments ensure your cloud agents run with consistent toolchains across all triggers. Learn when to use environments and how to configure them.` +The `description` field is the meta description in search results and the snippet AI engines read before deciding whether to cite the page. Write it as a standalone summary for someone who has never seen the page. +- ✅ `description: Environments give cloud agents the same toolchain and setup on every run, no matter what triggers them.` - ❌ `description: This page describes environments.` -The `description` field is used as the meta description in search results — write it as a summary that would make someone click. +#### Description rules +These apply to every page, regardless of content type. +- **One sentence, 50-160 characters.** Search engines truncate past roughly 160. Two sentences almost always overshoot the budget, so prefer one that earns its length. +- **Cut filler openers.** "Learn about," "This page covers," "A guide to," and "Documentation for" spend characters without adding meaning. Start with the verb or the subject instead. +- **Describe what the reader gets, not what the page is.** "This page explains X" is always weaker than explaining X. +- **Lead with the primary keyword** when it reads naturally, ideally within the first few words. +- **Match the page's actual scope.** A description that promises more than the page delivers reads as a bait-and-switch in search results. + +#### Descriptions by content type +Every description answers "what will I get from this page?" The shape of that answer depends on the type. +- **Conceptual** - Say what the thing is and why it matters. Start with the subject. + - ✅ `Environments give cloud agents the same toolchain and setup on every run, no matter what triggers them.` + - ❌ `Learn about environments and why they are useful.` +- **Procedural** - Say what task the reader will complete. Start with an imperative verb. + - ✅ `Connect Slack to Oz so mentions and channel messages can trigger cloud agent runs.` + - ❌ `This page explains the Slack integration setup process.` +- **Quickstart** - Say what the reader ends up with, plus the time budget. Start with an imperative verb. + - ✅ `Install the Warp Agent CLI, log in, and run your first agent conversation in about five minutes.` + - ❌ `Get started with the Warp Agent CLI.` +- **Reference** - Say what the reader can look up. Name the artifacts rather than the genre. + - ✅ `Look up Warp Agent CLI flags, environment variables, slash commands, and keyboard shortcuts.` + - ❌ `Reference documentation for the Warp Agent CLI.` +- **Troubleshooting** - Name the symptoms covered, not the act of troubleshooting. + - ✅ `Fix sign-in failures, failed conversation resumes, and update problems in the Warp Agent CLI.` + - ❌ `Troubleshooting information for common problems.` +- **FAQ** - Name the topic area the questions cover. + - ✅ `Answers to common questions about cloud agent billing, credits, and plan limits.` + - ❌ `Frequently asked questions.` +- **Feature documentation** - Say what the feature does and its primary benefit. + - ✅ `Control what the agent can do with permission cards, auto-approve, and execution profiles.` + - ❌ `Documentation for permissions and profiles.` +- **Guide** - Say what the reader will build or accomplish, using the non-branded phrasing they would search for. + - ✅ `Set up Claude Code and run your first agentic coding session from the terminal.` + - ❌ `A guide to using Claude Code with Warp.` ### Headers - Use sentence case for all headers (not title case) @@ -715,8 +747,9 @@ Add the key-value pair to `src/data/vars.ts` only. Both Option A (TypeScript imp All documentation should be written with search discoverability in mind — both for traditional search engines (Google) and AI engines (ChatGPT, Gemini, Perplexity, Copilot). ### Frontmatter descriptions -- Every page must have a `description` in frontmatter. Write it as a standalone summary (50-160 characters) that includes the primary keyword naturally. +- Every page must have a `description` in frontmatter. Write it as a standalone summary (one sentence, 50-160 characters) that includes the primary keyword naturally. - Descriptions appear in search results and AI citations. Write for humans, but include the key terms a developer would search for. +- For the full rules and per-content-type patterns with examples, see [Frontmatter](#frontmatter) under Content structure. That section is the source of truth. ### Title framing - For guides and educational content: capture the **non-branded query** when possible. Write the title a developer would actually search for. @@ -731,7 +764,7 @@ When creating or updating content, use SEO and AEO data to inform titles, descri Before publishing any documentation, verify: -- [ ] Frontmatter includes a clear, 1-2 sentence description written as a standalone summary +- [ ] Frontmatter includes a one-sentence description (50-160 chars) written as a standalone summary, with no filler opener - [ ] Content type is identified and the page follows the structure for that type (see `.warp/templates/`) - [ ] Headers use sentence case (with proper feature name capitalization) - [ ] Lists use bold term + dash + explanation format diff --git a/src/content/docs/cli/agent-conversations.mdx b/src/content/docs/cli/agent-conversations.mdx index b7341cad1..e227b0e66 100644 --- a/src/content/docs/cli/agent-conversations.mdx +++ b/src/content/docs/cli/agent-conversations.mdx @@ -1,8 +1,8 @@ --- title: "Agent conversations in the Warp Agent CLI" description: >- - Learn about agent conversations in the Warp Agent CLI, including streamed responses, tool - calls, diffs, task lists, plans, plus how to manage and resume conversations. + Work with the Warp Agent CLI transcript, including streamed responses, tool calls, + file diffs, plans, and task lists, then manage and resume conversations. --- import { VARS } from '@data/vars'; @@ -34,7 +34,7 @@ When the agent edits files, the edit renders as a diff in the transcript: * **Per-file sections** - Each edited file gets its own header showing the action taken and the lines added or removed. * **Multi-file edits** - Each file's section nests, indented, under one collapsible summary header (for example, `Edited 3 files`). -Diffs are fully expanded while the agent waits for your approval, then collapse to their headers once the edits are applied. Press `e` while the approval card is active to expand or collapse all diffs at once. +Diffs are fully expanded while the agent waits for your approval, then collapse to their headers once the edits are applied. Press `E` while the approval card is active to expand or collapse all diffs at once. ## Thinking blocks @@ -138,9 +138,9 @@ After compaction, a collapsed **Conversation summary** block appears in the tran ## Related pages -* **[Permissions and profiles](/cli/permissions-and-profiles/)** - Approve, reject, or auto-approve the agent's tool calls. -* **[Input and shell commands](/cli/input-and-shell-commands/)** - How commands the agent (or you) run appear in the transcript. -* **[Cloud handoff and orchestration](/cli/cloud-and-orchestration/)** - Hand off conversations to cloud agents and resume cloud runs. -* **[{VARS.WARP_CLI} reference](/cli/reference/)** - Command-line flags, slash commands, and keyboard shortcuts. -* **[Planning](/agents/capabilities/planning/)** - The full planning workflow. -* **[Task lists](/agents/capabilities/task-lists/)** - How agents create and update task lists. +* [Permissions and profiles](/cli/permissions-and-profiles/) - Approve, reject, or auto-approve the agent's tool calls. +* [Input and shell commands](/cli/input-and-shell-commands/) - How commands the agent (or you) run appear in the transcript. +* [Cloud handoff and orchestration](/cli/cloud-and-orchestration/) - Hand off conversations to cloud agents and resume cloud runs. +* [{VARS.WARP_CLI} reference](/cli/reference/) - Command-line flags, slash commands, and keyboard shortcuts. +* [Planning](/agents/capabilities/planning/) - The full planning workflow. +* [Task lists](/agents/capabilities/task-lists/) - How agents create and update task lists. diff --git a/src/content/docs/cli/cloud-and-orchestration.mdx b/src/content/docs/cli/cloud-and-orchestration.mdx index a29386fc9..d6948da6e 100644 --- a/src/content/docs/cli/cloud-and-orchestration.mdx +++ b/src/content/docs/cli/cloud-and-orchestration.mdx @@ -103,7 +103,7 @@ A focused local child behaves like a regular conversation. You can send it follo ### Kill a child agent -`Ctrl+C` kills a child agent: it stops the child's work — for a cloud child, cancelling its cloud run — and removes the child's tab and conversation, returning you to the orchestrator. +`Ctrl+C` kills a child agent. It stops the child's work, cancels the cloud run if the child is a cloud agent, and removes the child's tab and conversation, returning you to the orchestrator. * **From the tab bar** - With the tab bar focused and a child tab selected, a single `Ctrl+C` kills the selected child. The footer shows `Ctrl+C to kill sub-agent` as a reminder. * **While viewing a child** - Press `Ctrl+C` twice. The first press arms a short confirmation window and the footer shows `ctrl-c again to kill child agent`. A second press within the window kills the child. diff --git a/src/content/docs/cli/configuration.mdx b/src/content/docs/cli/configuration.mdx index 7da7bb846..b9091b554 100644 --- a/src/content/docs/cli/configuration.mdx +++ b/src/content/docs/cli/configuration.mdx @@ -1,8 +1,12 @@ --- +# REVIEW: This page title is "Customizing the Warp Agent CLI", but its sidebar label in +# src/sidebar.ts is "Configuration". Cross-references also call it "Customization", +# "Configuration", "Customizing the CLI", and "Configuring the Warp Agent CLI". +# Confirm whether the title/label mismatch is intentional before standardizing. title: "Customizing the Warp Agent CLI" description: >- - Customize the Warp Agent CLI's settings file, themes, statusline, start - screen, and agent context with project rules, skills, and MCP servers. + Configure Warp Agent CLI themes, the statusline, and the start screen, and give the + agent context from project rules, skills, and MCP servers. --- import { VARS } from '@data/vars'; @@ -155,8 +159,8 @@ Press `Enter` on a server to start, stop, or retry it depending on its state. Fa ## Related pages -* [Rules](/agents/capabilities/rules/) - Full guide to project and global rules -* [Skills](/agents/capabilities/skills/) - Authoring skills, skill arguments, and skill locations -* [MCP servers](/agents/capabilities/mcp/) - Config format, server examples, and authentication -* [Codebase Context](/agents/capabilities/codebase-context/) - Codebase indexing in the Warp app -* [{VARS.WARP_CLI} reference](/cli/reference/) - Command-line flags, slash commands, and keyboard shortcuts +* [Rules](/agents/capabilities/rules/) - Full guide to project and global rules. +* [Skills](/agents/capabilities/skills/) - Authoring skills, skill arguments, and skill locations. +* [MCP servers](/agents/capabilities/mcp/) - Config format, server examples, and authentication. +* [Codebase Context](/agents/capabilities/codebase-context/) - Codebase indexing in the Warp app. +* [{VARS.WARP_CLI} reference](/cli/reference/) - Command-line flags, slash commands, and keyboard shortcuts. diff --git a/src/content/docs/cli/index.mdx b/src/content/docs/cli/index.mdx index 4a3d8c2f2..b79aef138 100644 --- a/src/content/docs/cli/index.mdx +++ b/src/content/docs/cli/index.mdx @@ -1,8 +1,8 @@ --- title: "Warp Agent CLI overview" description: >- - 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. + Run Warp's agent in any terminal with the Warp Agent CLI, prompting the agent, + running shell commands, and handing work off to cloud agents. --- import { VARS } from '@data/vars'; @@ -18,12 +18,12 @@ To get a working setup in a few minutes, follow the [quickstart](/cli/quickstart ## Key features -* **[Agent conversations](/cli/agent-conversations/)** - Streaming responses with markdown rendering, file-edit diffs, tool calls, plans, and task lists. -* **[Shell commands](/cli/input-and-shell-commands/#shell-mode)** - Run shell commands from the same input as agent prompts, including long-running and interactive commands. -* **[Permissions you control](/cli/permissions-and-profiles/)** - Approve commands and file edits from inline request cards, or configure execution profiles and auto-approve. -* **[Persistent conversations](/cli/agent-conversations/#managing-conversations)** - Saved to your Warp account, so you can exit and resume later or switch between them. -* **[Cloud handoff and orchestration](/cli/cloud-and-orchestration/)** - Hand a conversation off to a cloud agent, continue cloud runs in the CLI, and coordinate multiple agents. -* **[Project context](/cli/configuration/#project-context-and-rules)** - The agent picks up your project's rules (like `AGENTS.md`), skills, and MCP servers automatically. +* **[Agent conversations](/cli/agent-conversations/)** - Follow the agent's work in a scrollable transcript with streamed responses, Markdown formatting, file-edit diffs, tool calls, plans, and task lists. +* **[Shell commands](/cli/input-and-shell-commands/#shell-mode)** - Run shell commands from the same input you use to prompt the agent, including long-running and interactive ones. +* **[Permissions and profiles](/cli/permissions-and-profiles/)** - Approve commands and file edits from inline request cards, or configure execution profiles and auto-approve. +* **[Persistent conversations](/cli/agent-conversations/#managing-conversations)** - Conversations save to your Warp account, so you can exit and resume later or switch between them. +* **[Cloud handoff and orchestration](/cli/cloud-and-orchestration/)** - Hand off a conversation to a cloud agent, continue cloud runs in the CLI, and coordinate multiple agents. +* **[Project context](/cli/configuration/#project-context-and-rules)** - The agent automatically picks up your project's rules (like `AGENTS.md`), skills, and MCP servers. * **[Model choice](/cli/models-and-usage/)** - Pick a model per conversation, bring your own provider API keys, and track credit usage. * **[Customization](/cli/configuration/)** - Configure themes, the statusline, and the start screen through a local settings file. @@ -42,13 +42,17 @@ The CLI runs on: ## Logging in and out -The first time you run `warp`, the CLI signs you in with a device authorization flow. It shows a verification link and code, opens your browser, and unlocks automatically once you approve the login. For non-interactive environments such as CI, authenticate with a Warp API key instead, using the `WARP_API_KEY` environment variable or the `--api-key` flag. See [logging in](/cli/quickstart/#log-in) in the quickstart for the full flow. +You sign in once, and the CLI stays signed in across sessions. -To sign out, run `/logout`. The CLI returns to its login screen and opens Warp's web sign-out page so your browser session is signed out too. +* **Sign in through your browser** - The first time you run `warp`, the CLI shows a verification link and code and opens the link in your browser. It unlocks automatically once you approve the login. See [logging in](/cli/quickstart/#2-log-in) for the full walkthrough. +* **Sign in with an API key** - In non-interactive environments such as CI, authenticate with a Warp API key through the `WARP_API_KEY` environment variable or the `--api-key` flag. See [command-line flags](/cli/reference/#command-line-flags). +* **Sign out** - Run `/logout`. The CLI returns to its login screen and opens Warp's web sign-out page, so your browser session is signed out too. ## Automatic updates -The CLI keeps itself up to date. While it runs, it periodically checks for a newer version, downloads it in the background, and stages it without interrupting your session. The staged version takes effect the next time you launch `warp`. When an update is ready, the start screen shows an "update installed, restart to apply" notice next to the version. To turn background updates off, set `general.autoupdate_enabled` to `false` in the [settings file](/cli/configuration/). +The CLI updates automatically. While it runs, it periodically checks for a newer version, downloads it in the background, and stages it without interrupting your session. The staged version takes effect the next time you launch `warp`. When an update is ready, the start screen shows an "update installed, restart to apply" notice next to the version. + +To turn off background updates, set `general.autoupdate_enabled` to `false` in the [settings file](/cli/configuration/#the-settings-file). To turn them off for a single launch, set the `WARP_TUI_DISABLE_AUTOUPDATE` environment variable to any value. ## Coming from the Warp app diff --git a/src/content/docs/cli/input-and-shell-commands.mdx b/src/content/docs/cli/input-and-shell-commands.mdx index 3c5bd773b..fbecc41a3 100644 --- a/src/content/docs/cli/input-and-shell-commands.mdx +++ b/src/content/docs/cli/input-and-shell-commands.mdx @@ -112,9 +112,9 @@ Running a shell command cancels the agent's in-progress response, if there is on Out of the box, the CLI never guesses what your input is: everything goes to the agent unless you enter shell mode. To type commands directly without the `!` prefix, turn on natural language detection: -- **Toggle detection** - Run `/natural-language-detection` to turn detection on or off. The statusline confirms the change, and the setting persists across sessions. -- **Automatic classification** - With detection on, the CLI classifies your input as you type. When the input looks like a shell command (for example, `git status`), the input switches to shell mode, and `Enter` runs it as a command. Everything else is sent to the agent. -- **Ambiguous input** - Short or ambiguous input stays in agent mode, and a single word switches to shell mode only when it matches a command available in your shell. +* **Toggle detection** - Run `/natural-language-detection` to turn detection on or off. The statusline confirms the change, and the setting persists across sessions. +* **Automatic classification** - With detection on, the CLI classifies your input as you type. When the input looks like a shell command (for example, `git status`), the input switches to shell mode, and `Enter` runs it as a command. Everything else is sent to the agent. +* **Ambiguous input** - Short or ambiguous input stays in agent mode, and a single word switches to shell mode only when it matches a command available in your shell. The prompt marker and statusline always show the current mode before you press `Enter`. If detection classifies input differently than you intended, press `Esc` to switch back to agent mode, or press `!` at the start of the input to force shell mode. @@ -122,8 +122,8 @@ The prompt marker and statusline always show the current mode before you press ` When a command keeps running, such as a dev server, a package install, or an interactive prompt, the CLI hands input over to it: -- **Input passthrough** - Keystrokes and pasted text are forwarded to the running process, so password requests, confirmation prompts, and other interactive programs work as they do in a plain terminal. -- **Type ahead** - If you start typing your next command before the current one finishes, the typed characters are carried into the input when the command completes, with the cursor at the end. This matches type-ahead behavior in shells like zsh and bash. +* **Input passthrough** - Keystrokes and pasted text are forwarded to the running process, so password requests, confirmation prompts, and other interactive programs work as they do in a plain terminal. +* **Type ahead** - If you start typing your next command before the current one finishes, the typed characters are carried into the input when the command completes, with the cursor at the end. This matches type-ahead behavior in shells like zsh and bash. One command runs in the session at a time. If the terminal is already busy, for example while the agent is running a command of its own, submitting a shell command shows a notice in the statusline and keeps your text in the input. @@ -131,23 +131,23 @@ One command runs in the session at a time. If the terminal is already busy, for Commands that switch the terminal to the alternate screen, such as `vim`, `htop`, or `less`, take over the whole CLI view: -- The app renders full-screen and receives keyboard, paste, scroll, and mouse input, so editors and other terminal UIs are fully usable inside the CLI. -- When the app exits, the transcript returns with your conversation intact. +* The app renders full-screen and receives keyboard, paste, scroll, and mouse input, so editors and other terminal UIs are fully usable inside the CLI. +* When the app exits, the transcript returns with your conversation intact. ## Stopping commands and exiting `Ctrl+C` performs one contextual action per press: -- **While a command is running** - `Ctrl+C` interrupts the running command, as in a plain terminal. It doesn't exit the CLI. -- **While the agent is responding** - `Ctrl+C` cancels the in-progress response. Text in the input is preserved. -- **At an idle prompt** - `Ctrl+C` clears the input if it has text. +* **While a command is running** - `Ctrl+C` interrupts the running command, as in a plain terminal. It doesn't exit the CLI. +* **While the agent is responding** - `Ctrl+C` cancels the in-progress response. Text in the input is preserved. +* **At an idle prompt** - `Ctrl+C` clears the input if it has text. After a press at the prompt, the statusline shows `ctrl-c again to exit` for about one second. Press `Ctrl+C` a second time within that window to exit the CLI. This works even while the agent is responding. While a shell command is running, `Ctrl+C` keeps interrupting the command instead. There are two other ways to exit: -- **`Ctrl+D`** - Exits immediately when the input is empty. -- **`/exit`** - Exits from the slash command menu. +* **`Ctrl+D`** - Exits immediately when the input is empty. +* **`/exit`** - Exits from the slash command menu. When you exit, the CLI prints a command you can use to pick the conversation back up later. See [Managing conversations](/cli/agent-conversations/#managing-conversations) for resuming and switching conversations. diff --git a/src/content/docs/cli/quickstart.mdx b/src/content/docs/cli/quickstart.mdx index ec77367d2..7da904cb9 100644 --- a/src/content/docs/cli/quickstart.mdx +++ b/src/content/docs/cli/quickstart.mdx @@ -5,27 +5,33 @@ description: >- in your own terminal in a few minutes. --- import { VARS } from '@data/vars'; +import { Tabs, TabItem } from '@astrojs/starlight/components'; This guide takes you from installing the {VARS.WARP_CLI} to your first agent conversation in about five minutes. ## Prerequisites -* **A Warp account** - The login step opens your browser, where you can sign in or create an account. The CLI uses the same account as the Warp app. +* **A Warp account** - The login step opens your browser, where you can sign in or [create an account](https://app.warp.dev/signup). The CLI uses the same account as the Warp app, but doesn't require the app to be installed. * **A supported platform** - macOS, Linux, or Windows. See [supported platforms](/cli/#supported-platforms). -## Install the Warp Agent CLI +## 1. Install the Warp Agent CLI -In a terminal on macOS or Linux, run: +Install the CLI with the command for your operating system. -```bash -curl -fsSL https://app.warp.dev/download/agent-cli | bash -``` - -In PowerShell on Windows, run: + + + ```bash + curl -fsSL https://app.warp.dev/download/agent-cli | bash + ``` + + + Run this command in PowerShell: -```powershell -Invoke-RestMethod "https://app.warp.dev/download/agent-cli.ps1" | Invoke-Expression -``` + ```powershell + Invoke-RestMethod "https://app.warp.dev/download/agent-cli.ps1" | Invoke-Expression + ``` + + After installing, verify that the `warp` command is available: @@ -33,57 +39,59 @@ After installing, verify that the `warp` command is available: warp --version ``` -The command prints the installed version. The CLI keeps itself up to date automatically after this. See [automatic updates](/cli/#automatic-updates). +The command prints the installed version. From here on, the CLI updates automatically. See [automatic updates](/cli/#automatic-updates). -## Log in +## 2. Log in -Log in once so the CLI can access your Warp account, models, and saved context. +Log in once so the CLI can access your Warp account, models, and saved context. Start the CLI: -1. Run `warp`. -2. The CLI shows a verification link and a device code, and opens the link in your browser. If the browser doesn't open, visit the link shown in the CLI and enter the code. -3. Approve the login in your browser. The CLI unlocks automatically, so you don't need to restart it. +```bash +warp +``` -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. +The CLI shows a verification link and a device code, and opens the link in your browser. Approve the login there and the CLI unlocks automatically, so you don't need to restart it. If the browser doesn't open, visit the link shown in the CLI and enter the code. + +When login completes, the CLI shows its start screen with 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 by setting the `WARP_API_KEY` environment variable: +**Running in CI or a headless environment?** Authenticate with a Warp API key instead by setting the `WARP_API_KEY` environment variable: ```bash WARP_API_KEY=YOUR_API_KEY warp ``` -You can also pass the `--api-key` flag, but prefer the environment variable. Command-line arguments can be captured in shell history and process listings. See [API keys](/reference/cli/api-keys/) for how to create one. +You can also pass the `--api-key` flag, but prefer the environment variable. Command-line arguments can be captured in shell history and process listings. See [API keys](/reference/cli/api-keys/) to learn how to create one. ::: -## Run your first prompt +## 3. Run your first prompt + +Type a prompt in plain language, such as `What does this project do?`, and press `Enter`. -1. Type a prompt in plain language, for example: `What does this project do?` -2. If the agent wants to run a command or edit a file, it shows a permission request. Choose an option to approve or reject the action. +If the agent wants to run a command or edit a file, it shows a permission request. Choose an option to approve or reject the action. Learn more about the transcript, diffs, and approvals in [Agent conversations](/cli/agent-conversations/) and [Permissions and profiles](/cli/permissions-and-profiles/). -## Run a shell command +## 4. Run a shell command You can run shell commands directly without leaving the CLI. -1. Type `!` at the start of an empty input to switch to shell mode. The footer shows **Shell mode**. -2. Type a command, such as `git status`, and press `Enter`. -3. Press `Backspace` on the empty input to switch back to prompting the agent. +Type `!` at the start of an empty input to switch to shell mode. The footer shows **Shell mode**. Type a command, such as `git status`, and press `Enter`. To go back to prompting the agent, press `Backspace` on the empty input. To run recognized shell commands without the `!` prefix, run `/natural-language-detection` to turn on natural language detection. The CLI then classifies input as you type: recognized commands switch to shell mode, while natural-language prompts stay in agent mode. The prompt marker and statusline show the active mode before you press `Enter`. See [Input and shell commands](/cli/input-and-shell-commands/) for long-running commands, interactive programs, and full-screen apps. -## Exit and resume +## 5. Exit and resume + +Press `Ctrl+C` twice in a row to exit, or run `/exit`. A single `Ctrl+C` press stops the agent's current response, or clears the input when nothing is running. -1. Press `Ctrl+C` twice in a row to exit, or run `/exit`. A single `Ctrl+C` press stops the agent's current response, or clears the input when nothing is running. -2. On exit, the CLI prints a resume command for the conversation: +On exit, the CLI prints a resume command for the conversation: - ```bash - warp --resume CONVERSATION_TOKEN - ``` +```bash +warp --resume CONVERSATION_TOKEN +``` -3. Run the printed command later to pick up where you left off. +Run the printed command later to pick up where you left off. To browse and reopen past conversations from inside the CLI, see [Agent conversations](/cli/agent-conversations/#conversation-history). diff --git a/src/content/docs/cli/reference.mdx b/src/content/docs/cli/reference.mdx index 2ad276cf8..91c0d653f 100644 --- a/src/content/docs/cli/reference.mdx +++ b/src/content/docs/cli/reference.mdx @@ -1,8 +1,8 @@ --- title: "Warp Agent CLI reference" description: >- - Reference for the Warp Agent CLI: command-line flags, environment variables, - slash commands, keyboard shortcuts, and troubleshooting. + Look up Warp Agent CLI command-line flags, environment variables, slash commands, + keyboard shortcuts, and fixes for common issues. --- import { VARS } from '@data/vars'; @@ -10,17 +10,29 @@ This page is a lookup reference for the {VARS.WARP_CLI}, covering the flags and ## Command-line flags -Running `warp` with no flags starts an interactive session in the current directory. The following flags change how the CLI starts, or make it perform a one-off action and exit. +Running `warp` with no flags starts an interactive session in the current directory. The following flags change how the CLI starts, or make it perform a one-off action and exit. They are listed alphabetically. -### `--resume` +### `--api-key` -Resumes a previous conversation by its conversation token. +Authenticates with a Warp API key instead of the interactive browser login. Use it on machines that can't open a browser, such as CI runners and remote servers. + +Prefer supplying the key through the `WARP_API_KEY` environment variable: ```bash -warp --resume CONVERSATION_TOKEN +WARP_API_KEY=YOUR_API_KEY warp ``` -`CONVERSATION_TOKEN` is the token the CLI prints when you exit a session ("To continue this conversation, run: `warp --resume ...`"). You can also reopen past conversations from inside a session with `/conversations`. See [agent conversations in the CLI](/cli/agent-conversations/#managing-conversations) for how persistence and resuming work. +The `--api-key` flag accepts the same value directly: + +```bash +warp --api-key YOUR_API_KEY +``` + +:::caution +Command-line arguments can be captured in shell history and process listings. Prefer the `WARP_API_KEY` environment variable, ideally populated from a secret manager. +::: + +Create a key in the Warp app under **Settings** > **Platform**. See the [API keys reference](/reference/cli/api-keys/) for details. ### `--auto-approve` @@ -30,33 +42,49 @@ Starts new conversations with auto-approve enabled, so the agent runs actions wi warp --auto-approve ``` -The default applies only to that launch and doesn't change your saved settings. You can still toggle auto-approve per conversation with `/auto-approve` or `Ctrl+Shift+I`. See [permissions and profiles](/cli/permissions-and-profiles/) for how approvals work. +This flag applies only to the session you launch with it and doesn't change your saved settings. You can still toggle auto-approve per conversation with `/auto-approve` or `Ctrl+Shift+I`. See [permissions and profiles](/cli/permissions-and-profiles/) for how approvals work. -### `--api-key` +### `--clear-provider-api-key` -Authenticates with a Warp API key instead of the interactive browser login. Useful on hosts where a browser sign-in is inconvenient. +Deletes a stored model-provider API key from your device's secure storage, then exits. -Prefer supplying the key through the `WARP_API_KEY` environment variable: +```bash +warp --clear-provider-api-key +``` + +`` is `openai`, `anthropic`, or `google`. For example: ```bash -WARP_API_KEY=YOUR_API_KEY warp +warp --clear-provider-api-key anthropic ``` -The `--api-key` flag accepts the same value directly: +### `--help` + +Prints usage information for all flags and exits. ```bash -warp --api-key YOUR_API_KEY +warp --help ``` -:::caution -Command-line arguments can be captured in shell history and process listings. Prefer the `WARP_API_KEY` environment variable, ideally populated from a secret manager. -::: +### `--resume` -Create a key in the Warp app under **Settings** > **Platform**. See the [API keys reference](/reference/cli/api-keys/) for details. +Reopens a previous conversation from your shell as the CLI starts. + +```bash +warp --resume CONVERSATION_TOKEN +``` + +`CONVERSATION_TOKEN` is the token the CLI prints when you exit a session ("To continue this conversation, run: `warp --resume ...`"). You can also reopen past conversations from inside a session with `/conversations`. See [agent conversations in the CLI](/cli/agent-conversations/#managing-conversations) for how persistence and resuming work. ### `--set-provider-api-key` -Securely stores a model-provider API key for [Bring Your Own API Key (BYOK)](/agents/inference/bring-your-own-api-key/), then exits. The provider is one of `openai`, `anthropic`, or `google`. +Stores a model-provider API key for [Bring Your Own API Key (BYOK)](/agents/inference/bring-your-own-api-key/) in your device's secure storage, then exits. Warp never stores provider keys on its servers. + +```bash +warp --set-provider-api-key +``` + +`` is `openai`, `anthropic`, or `google`. For example: ```bash warp --set-provider-api-key anthropic @@ -70,15 +98,7 @@ your-secret-manager read anthropic-api-key | warp --set-provider-api-key anthrop Avoid staging keys in plaintext files. If you must use a temporary file, delete it immediately afterward. -Inside a session, manage the same keys with the `/api-keys` menu; see [models and usage](/cli/models-and-usage/#bring-your-own-api-key) for how stored keys affect billing. - -### `--clear-provider-api-key` - -Removes a stored model-provider API key, then exits. The provider is one of `openai`, `anthropic`, or `google`. - -```bash -warp --clear-provider-api-key anthropic -``` +Inside a session, manage the same keys with the `/api-keys` menu. See [models and usage](/cli/models-and-usage/#bring-your-own-api-key) for how stored keys affect billing. ### `--version` @@ -88,18 +108,10 @@ Prints the installed version and exits. warp --version ``` -### `--help` - -Prints usage information for all flags and exits. - -```bash -warp --help -``` - ## Environment variables -* `WARP_API_KEY` - Warp API key for non-interactive authentication. Equivalent to passing `--api-key`. -* `WARP_TUI_DISABLE_AUTOUPDATE` - Set to any value to disable background auto-updates for that launch. See [Updating](#updating) for how updates work. +* **`WARP_API_KEY`** - A Warp API key for non-interactive authentication. Equivalent to passing `--api-key`. +* **`WARP_TUI_DISABLE_AUTOUPDATE`** - Set it to any value to turn off background updates for a single launch. See [Updating](#updating) for how updates work. ## Slash commands @@ -125,12 +137,12 @@ Type `/` at the start of the input to open the slash command menu. Commands that | `/natural-language-detection` | | Toggle natural language detection for shell input | | `/new` | `[prompt]` | Start a new conversation (alias for `/agent`) | | `/plan` | `[task]` | Ask the agent to research and create a plan for a task | -| `/skills` | | Invoke a skill | +| `/skills` | | Browse skills in scope and insert one into the input | | `/statusline` | | Configure the statusline | | `/theme` | `` | Set the color theme | | `/version` | | Show the installed version | | `/view-logs` | | Bundle your logs into a zip archive | -| `/voice` | | Start voice input (`Ctrl+S`) | +| `/voice` | | Start voice input | Skills also appear in the same menu under their own names, so you can invoke a skill directly as `/skill-name`. [Customizing the CLI](/cli/configuration/) covers how skills are discovered. @@ -139,7 +151,7 @@ Skills also appear in the same menu under their own names, so you can invoke a s Press `?` on an empty input to open the contextual shortcuts panel inside the CLI. The tables below list the default bindings. :::note -Bindings are identical on macOS, Linux, and Windows, and Windows also accepts `Alt+V` for paste. For shortcuts that use `Alt`, some macOS terminals deliver `Option` as `Alt` only when their Option-as-Alt (Meta) setting is enabled. +Bindings are the same on macOS, Linux, and Windows, except that Windows also accepts `Alt+V` for paste. For shortcuts that use `Alt`, some macOS terminals deliver `Option` as `Alt` only when their Option-as-Alt (Meta) setting is enabled. The macOS Command shortcuts described in [input and shell commands](/cli/input-and-shell-commands/#editing-basics) require a terminal with the Kitty keyboard protocol enabled. ::: ### Session @@ -166,34 +178,36 @@ These bindings apply while the agent is waiting for you to approve an action. [P | Shortcut | Action | | --- | --- | -| `Enter` | Confirm the selected response | +| `Enter` | Confirm the selected option on the approval card | | `Esc` | Reject or cancel the request | -| `e` | Edit the proposed action, or expand and collapse all diffs in a file-edit approval | -| `Ctrl+Enter` | Approve a blocked terminal-use action | +| `E` | Edit the proposed command, or expand and collapse all diffs in a file-edit approval | +| `Ctrl+Enter` | Approve a request to type into a running command | ### Terminal control -While the agent is running an interactive terminal command, or you have taken control of one: +These bindings apply while an interactive terminal command is running. | Shortcut | Action | | --- | --- | -| `Ctrl+C` | Interrupt the running command, or take control from the agent | -| `Ctrl+G` | Hand control back to the agent | +| `Ctrl+C` | Interrupt a command you started, or take control of a command the agent is running | +| `Ctrl+G` | Hand control of the command back to the agent | ### Multi-agent tabs -When you run multiple agents, a tab bar appears above the session. [Cloud and orchestration](/cli/cloud-and-orchestration/) covers the workflow. +When an orchestration launches child agents, an **Agents:** tab bar appears above the session. [Cloud and orchestration](/cli/cloud-and-orchestration/) covers the workflow. | Shortcut | Action | | --- | --- | | `Shift+↑` | Focus the agent tab bar | -| `←` / `→` or `Tab` / `Shift+Tab` | Switch between agents | -| `↓` | Return focus to the input | -| `Esc` | Return to the main agent | +| `←` / `→` or `Tab` / `Shift+Tab` | Select the previous or next agent | +| `Shift+←` / `Shift+→` | Select the first or last child agent | +| `↓` | Return focus to the current session's input | +| `Esc` | Return to the orchestrator | +| `Ctrl+C` | Kill the selected child agent (press twice when viewing a child) | ### Text editing -The input supports familiar readline-style editing: +The input supports readline-style editing. | Shortcut | Action | | --- | --- | @@ -206,7 +220,7 @@ The input supports familiar readline-style editing: | `Alt+D` or `Alt+Delete` | Delete the next word | | `Ctrl+K` | Delete to the end of the line | | `Ctrl+U` | Delete to the start of the line | -| `Ctrl+Y` | Paste the last deleted text | +| `Ctrl+Y` | Reinsert the last deleted text | | `Ctrl+Z` / `Ctrl+Shift+Z` | Undo / redo | | `Shift+←` / `Shift+→` / `Shift+↑` / `Shift+↓` | Extend the selection | | `Ctrl+Shift+A` | Select all | @@ -229,7 +243,7 @@ When something goes wrong, logs are the fastest way to help the Warp team diagno Run `/view-logs` in a session to bundle the current session's log and recent previous sessions into a timestamped zip archive. The CLI reveals the archive in your file manager and shows the saved path in the footer, so you can attach it to a bug report or share it with support. -On macOS, CLI logs are stored in `~/Library/Logs/warp-cli/`. Logs rotate per session, and only a limited number of recent sessions are kept. The `/view-logs` archive is written to the same directory. +On macOS, CLI logs are stored in `~/Library/Logs/warp-cli/`. Logs rotate per session, and older session logs are rotated out over time. The `/view-logs` archive is written to the same directory. ### The browser doesn't open during sign-in @@ -243,7 +257,7 @@ For machines where the browser flow isn't practical, authenticate non-interactiv ### "Login failed" -The sign-in attempt was rejected or timed out. The message shows the underlying cause. +The sign-in attempt was rejected or timed out. The error message in the CLI names the underlying cause. 1. Press `Ctrl+C` to exit. 2. Run `warp` again to restart the sign-in flow. @@ -264,7 +278,7 @@ The sign-in attempt was rejected or timed out. The message shows the underlying ### Updating -The CLI keeps itself up to date. Installed builds check for updates in the background, download new versions, and apply them the next time you launch `warp`. A running session is never interrupted. +The CLI updates automatically. Installed builds check for updates in the background, download new versions, and apply them the next time you launch `warp`. A running session is never interrupted. To check which version you're running, use `/version` in a session, or run: @@ -272,7 +286,7 @@ To check which version you're running, use `/version` in a session, or run: warp --version ``` -To disable background updates for a single launch, set the `WARP_TUI_DISABLE_AUTOUPDATE` environment variable to any value. To disable them persistently, turn off the autoupdate setting in the settings file. See [configuration](/cli/configuration/). +To turn off background updates for a single launch, set the `WARP_TUI_DISABLE_AUTOUPDATE` environment variable to any value. To turn them off persistently, set `general.autoupdate_enabled` to `false` in the [CLI settings file](/cli/configuration/#the-settings-file). If an install becomes corrupted, re-running the install command from the [quickstart](/cli/quickstart/) replaces it with the latest version.