From 380e45ca0d61b84dd7c3ae986fbea03a22922557 Mon Sep 17 00:00:00 2001 From: Hong Yi Chen Date: Tue, 28 Jul 2026 14:32:08 -0700 Subject: [PATCH 01/10] docs(cli): draft reference, models & usage, and troubleshooting pages Fill in the three cli-reference pages from the Warp CLI launch skeleton: - cli/reference: command-line flags with examples, environment variables, full slash-command table (25 commands verified against the CLI command registry), and default keyboard shortcuts sourced from the CLI keybinding definitions. - cli/models-and-usage: /model picker and footer model entry, BYOK via /add-api-key + provider flags (OpenAI/Anthropic/Google), custom model routers in the picker, and cost transparency (footer credits toggle, /cost per-response summary). - cli/troubleshooting: /view-logs bundling and log locations, login troubleshooting, autoupdate behavior with /version and --version, and support links. Co-Authored-By: Oz --- src/content/docs/cli/models-and-usage.mdx | 44 +++++- src/content/docs/cli/reference.mdx | 176 +++++++++++++++++++++- src/content/docs/cli/troubleshooting.mdx | 62 +++++++- 3 files changed, 262 insertions(+), 20 deletions(-) diff --git a/src/content/docs/cli/models-and-usage.mdx b/src/content/docs/cli/models-and-usage.mdx index 0e0511a3..eaf3e209 100644 --- a/src/content/docs/cli/models-and-usage.mdx +++ b/src/content/docs/cli/models-and-usage.mdx @@ -6,22 +6,52 @@ description: >- --- import { VARS } from '@data/vars'; -{/* TODO(cli-reference): draft per drafts/warp-cli-launch-plan.md — "cli/models-and-usage.mdx" section. Feature-doc content type. */} - -The {VARS.WARP_CLI} documentation for this page is in progress. +The {VARS.WARP_CLI} gives you the same model options as the Warp app: pick the model that powers your conversations, bring your own provider API keys, route requests through custom model routers, and see what every response costs as you work. ## Choosing a model -{/* TODO(cli-reference): /model picker, footer model entry; cross-link agent-platform/inference/model-choice. */} +Run `/model` to open the model picker. You can also click the model name in the footer to open the same picker. + +The picker lists every model available to your account, with the active model preselected. Type to filter the list, press `↑` and `↓` to move through it, and press `Enter` to switch. Models that your plan or your team's settings don't allow appear in the list as disabled. + +Your choice is saved as the base model of your active profile, so it persists across sessions. See [permissions and profiles](/cli/permissions-and-profiles/) for how profiles work in the CLI, and [Model choice](/agent-platform/inference/model-choice/) for the full list of supported models and how Warp's Auto models pick one for you. ## Bring your own API key -{/* TODO(cli-reference): /add-api-key, /clear-provider-api-key, --set-provider-api-key, --clear-provider-api-key; supported providers; cross-link agent-platform/inference/bring-your-own-api-key. */} +The {VARS.WARP_CLI} supports [Bring Your Own API Key (BYOK)](/agent-platform/inference/bring-your-own-api-key/) for OpenAI, Anthropic, and Google models. When you select a model covered by one of your keys, requests are billed through your provider account and don't consume your Warp [credits](/support-and-community/plans-and-billing/credits/). + +To store a key, run `/add-api-key` with one of `openai`, `anthropic`, or `google`: + +```text +/add-api-key anthropic +``` + +The CLI prompts for the key with masked input, so the key never appears in your transcript or shell history, and saves it to your device's secure storage. Warp does not store provider keys on its servers. + +To remove a stored key, run `/clear-provider-api-key` with the same provider name. Both commands are also available outside a session as the `--set-provider-api-key` and `--clear-provider-api-key` flags; see the [{VARS.WARP_CLI} reference](/cli/reference/#command-line-flags). + +:::note +Warp's built-in Auto models always consume Warp credits, even with BYOK configured. To bill through your own account, select a specific provider model, or use a [custom router](/agent-platform/inference/custom-routers/#using-your-own-api-keys-byok) whose targets your keys cover. See [BYOK usage and billing behavior](/agent-platform/inference/bring-your-own-api-key/#byok-usage-and-billing-behavior) for the full rules. +::: ## Custom model routing -{/* TODO(cli-reference): custom routers in the CLI — confirm shipped before merge; cross-link agent-platform/inference/custom-routers. */} +[Custom routers](/agent-platform/inference/custom-routers/) appear in the `/model` picker alongside individual models. Select one and each prompt resolves to a concrete model using the routing logic you defined. + +The CLI loads the same router definitions as the Warp app: YAML files in `~/.warp/custom_model_routers/`, plus any team-synced routers your admin shares. See [authoring a router as a file](/agent-platform/inference/custom-routers/#author-a-router-as-a-file) for the file format. ## Usage and cost -{/* TODO(cli-reference): footer credits entry, /cost toggle, last-response duration and credits. */} +The {VARS.WARP_CLI} shows usage at two levels: a running total for the conversation, and a per-response breakdown. + +* **Conversation total** - Once a conversation has reported any usage, the footer shows its accumulated credits (for example, `2.5 credits`). Click the entry to switch between credits and the equivalent provider cost in dollars; the choice persists across sessions. +* **Per-response details** - Run `/cost` to toggle a summary row under the latest response showing how long it took and how many credits it spent (for example, `12s • 1.2 credits`). The summary appears once the response finishes. + +Credits are Warp's unit of usage for agent requests. For what credits cover and how plans differ, see [Credits](/support-and-community/plans-and-billing/credits/). + +## Related pages + +* [Model choice](/agent-platform/inference/model-choice/) - Supported models and how automatic model selection works. +* [Bring Your Own API Key](/agent-platform/inference/bring-your-own-api-key/) - How BYOK works, key storage, and billing behavior. +* [Custom routers](/agent-platform/inference/custom-routers/) - Define routing logic that picks a model per task. +* [{VARS.WARP_CLI} reference](/cli/reference/) - Flags and slash commands, including the API key commands. diff --git a/src/content/docs/cli/reference.mdx b/src/content/docs/cli/reference.mdx index b59d26d0..be709b2f 100644 --- a/src/content/docs/cli/reference.mdx +++ b/src/content/docs/cli/reference.mdx @@ -6,22 +6,184 @@ description: >- --- import { VARS } from '@data/vars'; -{/* TODO(cli-reference): draft per drafts/warp-cli-launch-plan.md — "cli/reference.mdx" section. Reference content type (exhaustive, lookup-oriented). */} - -The {VARS.WARP_CLI} documentation for this page is in progress. +This page is a lookup reference for the {VARS.WARP_CLI}: the flags and environment variables the `warp` command accepts, every slash command available in a session, and the default keyboard shortcuts. ## Command-line flags -{/* TODO(cli-reference): warp [flags] — --resume, --api-key, --set-provider-api-key, --clear-provider-api-key, --version, --help; one example per flag. */} +Running `warp` with no flags starts an interactive session in the current directory. The following flags change how the CLI starts or run a one-off action and exit. + +### `--resume` + +Resumes a previous conversation by its conversation token. + +```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 [conversations in the {VARS.WARP_CLI}](/cli/conversations/) for how persistence and resuming work. + +### `--api-key` + +Authenticates with a Warp API key instead of the interactive browser login. Useful on hosts where a browser sign-in is inconvenient. + +```bash +warp --api-key YOUR_API_KEY +``` + +The key can also be supplied through the `WARP_API_KEY` environment variable. Create a key in the Warp app under **Settings** > **Platform**; see the [API keys reference](/reference/cli/api-keys/) for details. + +### `--set-provider-api-key` + +Securely stores a model-provider API key for [Bring Your Own API Key (BYOK)](/agent-platform/inference/bring-your-own-api-key/), then exits. The provider is one of `openai`, `anthropic`, or `google`. + +```bash +warp --set-provider-api-key anthropic +``` + +The CLI prompts for the key with masked input, so the key never appears in your shell history. When stdin is piped, the key is read from stdin instead: + +```bash +warp --set-provider-api-key anthropic < key.txt +``` + +See [models and usage](/cli/models-and-usage/) 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 +``` + +### `--version` + +Prints the installed version and exits. + +```bash +warp --version +``` + +### `--help` + +Prints usage information for all flags and exits. + +```bash +warp --help +``` ## Environment variables -{/* TODO(cli-reference): WARP_API_KEY and any other public env vars. */} +* `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 the {VARS.WARP_CLI}](/cli/troubleshooting/#updating) for how updates work. ## Slash commands -{/* TODO(cli-reference): full table of slash commands available in the CLI with descriptions and arguments. */} +Type `/` at the start of the input to open the slash command menu, then keep typing to filter it. Commands that take an argument show a hint after the command name. Angle brackets mark required arguments; square brackets mark optional ones. + +| Command | Argument | Description | +| --- | --- | --- | +| `/add-api-key` | `` | Securely store a model-provider API key | +| `/agent` | `[prompt]` | Start a new conversation | +| `/auto-approve` | | Toggle auto-approve for agent actions | +| `/clear` | `[prompt]` | Clear the transcript and start a new conversation | +| `/clear-provider-api-key` | `` | Remove a stored model-provider API key | +| `/compact` | `[instructions]` | Free up context by summarizing the conversation history | +| `/conversations` | | Open conversation history | +| `/cost` | | Toggle per-response credit usage details | +| `/create-new-project` | `` | Have the agent walk you through creating a new coding project | +| `/exit` | | Exit the CLI | +| `/export-to-clipboard` | | Export the current conversation to the clipboard as Markdown | +| `/export-to-file` | `[filename]` | Export the current conversation to a Markdown file | +| `/handoff` | `[prompt]` | Hand off this conversation to a cloud agent | +| `/logout` | | Log out of Warp | +| `/mcp` | | View and manage MCP servers | +| `/model` | | Switch the base agent model | +| `/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 | +| `/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`) | + +Skills also appear in the same menu under their own names, so you can invoke a skill directly as `/skill-name`. See [context in the {VARS.WARP_CLI}](/cli/context/) for how skills are discovered. ## Keyboard shortcuts -{/* TODO(cli-reference): default shortcuts (source: the in-app shortcuts menu). */} +Press `?` on an empty input to open the contextual shortcuts panel inside the CLI. The tables below list the default bindings. + +### Session + +| Shortcut | Action | +| --- | --- | +| `Ctrl+C` | Stop the current response, or clear the input; press again within a second to exit | +| `Ctrl+D` | Exit when the input is empty (deletes the next character otherwise) | +| `?` | Show the shortcuts panel (on an empty input) | +| `/` | Open the slash command menu | +| `!` | Enter shell mode (`Esc` returns to agent input) | +| `←` | Open the conversation list (on an empty input) | +| `↑` | Browse prompt and command history | +| `Esc` | Dismiss the open menu, or leave shell mode | +| `Ctrl+Shift+I` | Toggle auto-approve | +| `Ctrl+Shift+P` | Expand or collapse the latest plan | +| `Ctrl+S` | Start voice input | +| `Ctrl+V` / `Ctrl+Shift+V` | Paste from the clipboard, including images | +| `Tab` | Focus attached images when present; complete shell commands in shell mode | + +### Approvals + +These bindings apply while the agent is waiting for you to approve an action. See [permissions and profiles](/cli/permissions-and-profiles/) for how approvals work. + +| Shortcut | Action | +| --- | --- | +| `Enter` | Confirm the selected response | +| `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 | + +### Terminal control + +While the agent is running an interactive terminal command, or you have taken control of one: + +| Shortcut | Action | +| --- | --- | +| `Ctrl+C` | Interrupt the running command, or take control from the agent | +| `Ctrl+G` | Hand control back to the agent | + +### Multi-agent tabs + +When you run multiple agents, a tab bar appears above the session. See [cloud and orchestration](/cli/cloud-and-orchestration/) for details. + +| 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 | + +### Text editing + +The input supports familiar readline-style editing: + +| Shortcut | Action | +| --- | --- | +| `Shift+Enter`, `Ctrl+J`, or `Alt+Enter` | Insert a newline | +| `Ctrl+A` / `Home` | Move to the start of the line | +| `Ctrl+E` / `End` | Move to the end of the line | +| `Ctrl+B` / `Ctrl+F` | Move left / right | +| `Alt+B` / `Alt+F` (or `Alt+←` / `Alt+→`) | Move one word left / right | +| `Ctrl+W` or `Alt+Backspace` | Delete the previous word | +| `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+Z` / `Ctrl+Shift+Z` | Undo / redo | +| `Shift+←` / `Shift+→` / `Shift+↑` / `Shift+↓` | Extend the selection | +| `Ctrl+Shift+A` | Select all | +| `Ctrl+Shift+C` | Copy the selection | +| `Ctrl+X` | Cut the selection | + +For mouse support, completions, and other input behavior, see [input and editing](/cli/input-and-editing/). diff --git a/src/content/docs/cli/troubleshooting.mdx b/src/content/docs/cli/troubleshooting.mdx index 94c617e6..b8d992a2 100644 --- a/src/content/docs/cli/troubleshooting.mdx +++ b/src/content/docs/cli/troubleshooting.mdx @@ -6,22 +6,72 @@ description: >- --- import { VARS } from '@data/vars'; -{/* TODO(cli-reference): draft per drafts/warp-cli-launch-plan.md — "cli/troubleshooting.mdx" section. Troubleshooting content type (problem → cause → solution). */} +This page covers common {VARS.WARP_CLI} issues: gathering logs for a bug report, fixing sign-in problems, resuming conversations, and keeping the CLI up to date. -The {VARS.WARP_CLI} documentation for this page is in progress. +:::note +For known issues and feature requests across Warp, visit the [GitHub issues page](https://github.com/warpdotdev/Warp/issues). +::: ## Viewing and sharing logs -{/* TODO(cli-reference): /view-logs bundle, log file locations, sharing a debugging link if shipped. */} +When something goes wrong, logs are the fastest way to help the Warp team diagnose the problem. + +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, {VARS.WARP_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. ## Login issues -{/* TODO(cli-reference): device-auth problems and solutions; /logout and re-login. */} +The {VARS.WARP_CLI} signs you in with a browser-based flow: it opens a verification page (or shows you the URL and a code to enter) and continues once you approve the sign-in. See the [quickstart](/cli/quickstart/) for the full flow. + +### The browser doesn't open + +On a remote or browser-less machine, the CLI can't launch a browser. The sign-in screen still shows the verification URL and code. + +1. Open the displayed URL in a browser on any device, including another machine. +2. Enter the code shown in the CLI. +3. Return to the CLI; it proceeds automatically once the sign-in is approved. + +For machines where the browser flow isn't practical, authenticate non-interactively with an API key instead, using `warp --api-key` or the `WARP_API_KEY` environment variable. See the [{VARS.WARP_CLI} reference](/cli/reference/#command-line-flags). + +### "Login failed" + +The sign-in attempt was rejected or timed out; the message shows the underlying cause. + +1. Press `Ctrl+C` to exit. +2. Run `warp` again to restart the sign-in flow. +3. If the failure persists, check your network connection and any proxy or firewall that could block access to Warp's servers. + +### Signed in to the wrong account + +1. Run `/logout` in a session. The CLI signs you out, opens your browser to complete the sign-out on Warp's website, and returns to the sign-in screen. +2. Sign in with the account you want. + +### "Could not restore conversation" when resuming + +`warp --resume` failed to load the conversation for the given token, for example because the token is malformed or the conversation is no longer available. + +1. Press `Ctrl+C` to exit, then run `warp` to start normally. +2. Check the token against the resume command printed when you exited the original session. +3. If the conversation exists locally, open it with `/conversations` instead. See [conversations in the {VARS.WARP_CLI}](/cli/conversations/). ## Updating -{/* TODO(cli-reference): how autoupdate works, checking the version with /version and --version. */} +The {VARS.WARP_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. + +To check which version you're running, use `/version` in a session, or run: + +```bash +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/). + +If an install becomes corrupted, re-running the install command from the [quickstart](/cli/quickstart/) replaces it with the latest version. ## Getting help -{/* TODO(cli-reference): feedback and support channels; link to support-and-community pages. */} +* [Sending us feedback](/support-and-community/troubleshooting-and-support/sending-us-feedback/) - How to reach Warp support and share feedback. +* [Known issues](/support-and-community/troubleshooting-and-support/known-issues/) - Current known issues across Warp. +* [GitHub issues](https://github.com/warpdotdev/Warp/issues) - Search existing reports or file a new one; attach the `/view-logs` archive to bug reports. +* [{VARS.WARP_CLI} reference](/cli/reference/) - Flags, environment variables, slash commands, and keyboard shortcuts. From 68bd887c248c0f39a5221ae32bc84ef0ae64e6a9 Mon Sep 17 00:00:00 2001 From: Hong Yi Chen Date: Tue, 28 Jul 2026 14:44:01 -0700 Subject: [PATCH 02/10] docs(cli): use literal Warp CLI in frontmatter title/description Frontmatter {{WARP_CLI}} tokens are not substituted by the build (Astro's content layer parses frontmatter outside Vite), so built titles showed the raw token. Body prose keeps {VARS.WARP_CLI}. Co-Authored-By: Oz --- src/content/docs/cli/models-and-usage.mdx | 4 ++-- src/content/docs/cli/reference.mdx | 4 ++-- src/content/docs/cli/troubleshooting.mdx | 4 ++-- 3 files changed, 6 insertions(+), 6 deletions(-) diff --git a/src/content/docs/cli/models-and-usage.mdx b/src/content/docs/cli/models-and-usage.mdx index eaf3e209..214b46af 100644 --- a/src/content/docs/cli/models-and-usage.mdx +++ b/src/content/docs/cli/models-and-usage.mdx @@ -1,7 +1,7 @@ --- -title: "Models and usage in the {{WARP_CLI}}" +title: "Models and usage in the Warp CLI" description: >- - Choose models in the {{WARP_CLI}}, bring your own API key, and track credit + Choose models in the Warp CLI, bring your own API key, and track credit usage and per-response cost. --- import { VARS } from '@data/vars'; diff --git a/src/content/docs/cli/reference.mdx b/src/content/docs/cli/reference.mdx index be709b2f..2631edf0 100644 --- a/src/content/docs/cli/reference.mdx +++ b/src/content/docs/cli/reference.mdx @@ -1,7 +1,7 @@ --- -title: "{{WARP_CLI}} reference" +title: "Warp CLI reference" description: >- - Reference for the {{WARP_CLI}}: command-line flags, environment variables, + Reference for the Warp CLI: command-line flags, environment variables, slash commands, and keyboard shortcuts. --- import { VARS } from '@data/vars'; diff --git a/src/content/docs/cli/troubleshooting.mdx b/src/content/docs/cli/troubleshooting.mdx index b8d992a2..8e1b6af6 100644 --- a/src/content/docs/cli/troubleshooting.mdx +++ b/src/content/docs/cli/troubleshooting.mdx @@ -1,7 +1,7 @@ --- -title: "Troubleshooting the {{WARP_CLI}}" +title: "Troubleshooting the Warp CLI" description: >- - Fix common {{WARP_CLI}} issues: gather logs, resolve login problems, and + Fix common Warp CLI issues: gather logs, resolve login problems, and update to the latest version. --- import { VARS } from '@data/vars'; From a268f0d4d71fb861985989c90e9ccac73fdb4363 Mon Sep 17 00:00:00 2001 From: Hong Yi Chen Date: Tue, 28 Jul 2026 14:54:51 -0700 Subject: [PATCH 03/10] docs(cli): fold troubleshooting into the reference page Consolidation: the standalone troubleshooting page merges into cli/reference.mdx as a final Troubleshooting section with problem-oriented H3 subsections. Existing H2 anchors (#slash-commands, #keyboard-shortcuts) are unchanged; internal links now point at #updating and #command-line-flags. troubleshooting.mdx is restored to the base-branch stub (the orchestrator removes it at integration). Co-Authored-By: Oz --- src/content/docs/cli/reference.mdx | 75 ++++++++++++++++++++++-- src/content/docs/cli/troubleshooting.mdx | 66 +++------------------ 2 files changed, 79 insertions(+), 62 deletions(-) diff --git a/src/content/docs/cli/reference.mdx b/src/content/docs/cli/reference.mdx index 2631edf0..f3fdcc44 100644 --- a/src/content/docs/cli/reference.mdx +++ b/src/content/docs/cli/reference.mdx @@ -1,12 +1,12 @@ --- title: "Warp CLI reference" description: >- - Reference for the Warp CLI: command-line flags, environment variables, - slash commands, and keyboard shortcuts. + Reference for the Warp CLI: command-line flags, environment variables, slash + commands, keyboard shortcuts, and troubleshooting. --- import { VARS } from '@data/vars'; -This page is a lookup reference for the {VARS.WARP_CLI}: the flags and environment variables the `warp` command accepts, every slash command available in a session, and the default keyboard shortcuts. +This page is a lookup reference for the {VARS.WARP_CLI}: the flags and environment variables the `warp` command accepts, every slash command available in a session, the default keyboard shortcuts, and fixes for common issues. ## Command-line flags @@ -75,7 +75,7 @@ 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 the {VARS.WARP_CLI}](/cli/troubleshooting/#updating) for how updates work. +* `WARP_TUI_DISABLE_AUTOUPDATE` - Set to any value to disable background auto-updates for that launch. See [Updating](#updating) for how updates work. ## Slash commands @@ -187,3 +187,70 @@ The input supports familiar readline-style editing: | `Ctrl+X` | Cut the selection | For mouse support, completions, and other input behavior, see [input and editing](/cli/input-and-editing/). + +## Troubleshooting + +This section covers common {VARS.WARP_CLI} issues: gathering logs for a bug report, fixing sign-in problems, resuming conversations, and keeping the CLI up to date. + +:::note +For known issues and feature requests across Warp, visit the [GitHub issues page](https://github.com/warpdotdev/Warp/issues). +::: + +### Viewing and sharing logs + +When something goes wrong, logs are the fastest way to help the Warp team diagnose the problem. + +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, {VARS.WARP_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. + +### The browser doesn't open during sign-in + +The {VARS.WARP_CLI} signs you in with a browser-based flow: it opens a verification page (or shows you the URL and a code to enter) and continues once you approve the sign-in. On a remote or browser-less machine, the CLI can't launch a browser, but the sign-in screen still shows the verification URL and code. + +1. Open the displayed URL in a browser on any device, including another machine. +2. Enter the code shown in the CLI. +3. Return to the CLI; it proceeds automatically once the sign-in is approved. + +For machines where the browser flow isn't practical, authenticate non-interactively with an API key instead, using `warp --api-key` or the `WARP_API_KEY` environment variable. See [command-line flags](#command-line-flags). + +### "Login failed" + +The sign-in attempt was rejected or timed out; the message shows the underlying cause. + +1. Press `Ctrl+C` to exit. +2. Run `warp` again to restart the sign-in flow. +3. If the failure persists, check your network connection and any proxy or firewall that could block access to Warp's servers. + +### Signed in to the wrong account + +1. Run `/logout` in a session. The CLI signs you out, opens your browser to complete the sign-out on Warp's website, and returns to the sign-in screen. +2. Sign in with the account you want. + +### "Could not restore conversation" when resuming + +`warp --resume` failed to load the conversation for the given token, for example because the token is malformed or the conversation is no longer available. + +1. Press `Ctrl+C` to exit, then run `warp` to start normally. +2. Check the token against the resume command printed when you exited the original session. +3. If the conversation exists locally, open it with `/conversations` instead. See [conversations in the {VARS.WARP_CLI}](/cli/conversations/). + +### Updating + +The {VARS.WARP_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. + +To check which version you're running, use `/version` in a session, or run: + +```bash +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/). + +If an install becomes corrupted, re-running the install command from the [quickstart](/cli/quickstart/) replaces it with the latest version. + +### Getting help + +* [Sending us feedback](/support-and-community/troubleshooting-and-support/sending-us-feedback/) - How to reach Warp support and share feedback. +* [Known issues](/support-and-community/troubleshooting-and-support/known-issues/) - Current known issues across Warp. +* [GitHub issues](https://github.com/warpdotdev/Warp/issues) - Search existing reports or file a new one; attach the `/view-logs` archive to bug reports. diff --git a/src/content/docs/cli/troubleshooting.mdx b/src/content/docs/cli/troubleshooting.mdx index 8e1b6af6..94c617e6 100644 --- a/src/content/docs/cli/troubleshooting.mdx +++ b/src/content/docs/cli/troubleshooting.mdx @@ -1,77 +1,27 @@ --- -title: "Troubleshooting the Warp CLI" +title: "Troubleshooting the {{WARP_CLI}}" description: >- - Fix common Warp CLI issues: gather logs, resolve login problems, and + Fix common {{WARP_CLI}} issues: gather logs, resolve login problems, and update to the latest version. --- import { VARS } from '@data/vars'; -This page covers common {VARS.WARP_CLI} issues: gathering logs for a bug report, fixing sign-in problems, resuming conversations, and keeping the CLI up to date. +{/* TODO(cli-reference): draft per drafts/warp-cli-launch-plan.md — "cli/troubleshooting.mdx" section. Troubleshooting content type (problem → cause → solution). */} -:::note -For known issues and feature requests across Warp, visit the [GitHub issues page](https://github.com/warpdotdev/Warp/issues). -::: +The {VARS.WARP_CLI} documentation for this page is in progress. ## Viewing and sharing logs -When something goes wrong, logs are the fastest way to help the Warp team diagnose the problem. - -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, {VARS.WARP_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. +{/* TODO(cli-reference): /view-logs bundle, log file locations, sharing a debugging link if shipped. */} ## Login issues -The {VARS.WARP_CLI} signs you in with a browser-based flow: it opens a verification page (or shows you the URL and a code to enter) and continues once you approve the sign-in. See the [quickstart](/cli/quickstart/) for the full flow. - -### The browser doesn't open - -On a remote or browser-less machine, the CLI can't launch a browser. The sign-in screen still shows the verification URL and code. - -1. Open the displayed URL in a browser on any device, including another machine. -2. Enter the code shown in the CLI. -3. Return to the CLI; it proceeds automatically once the sign-in is approved. - -For machines where the browser flow isn't practical, authenticate non-interactively with an API key instead, using `warp --api-key` or the `WARP_API_KEY` environment variable. See the [{VARS.WARP_CLI} reference](/cli/reference/#command-line-flags). - -### "Login failed" - -The sign-in attempt was rejected or timed out; the message shows the underlying cause. - -1. Press `Ctrl+C` to exit. -2. Run `warp` again to restart the sign-in flow. -3. If the failure persists, check your network connection and any proxy or firewall that could block access to Warp's servers. - -### Signed in to the wrong account - -1. Run `/logout` in a session. The CLI signs you out, opens your browser to complete the sign-out on Warp's website, and returns to the sign-in screen. -2. Sign in with the account you want. - -### "Could not restore conversation" when resuming - -`warp --resume` failed to load the conversation for the given token, for example because the token is malformed or the conversation is no longer available. - -1. Press `Ctrl+C` to exit, then run `warp` to start normally. -2. Check the token against the resume command printed when you exited the original session. -3. If the conversation exists locally, open it with `/conversations` instead. See [conversations in the {VARS.WARP_CLI}](/cli/conversations/). +{/* TODO(cli-reference): device-auth problems and solutions; /logout and re-login. */} ## Updating -The {VARS.WARP_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. - -To check which version you're running, use `/version` in a session, or run: - -```bash -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/). - -If an install becomes corrupted, re-running the install command from the [quickstart](/cli/quickstart/) replaces it with the latest version. +{/* TODO(cli-reference): how autoupdate works, checking the version with /version and --version. */} ## Getting help -* [Sending us feedback](/support-and-community/troubleshooting-and-support/sending-us-feedback/) - How to reach Warp support and share feedback. -* [Known issues](/support-and-community/troubleshooting-and-support/known-issues/) - Current known issues across Warp. -* [GitHub issues](https://github.com/warpdotdev/Warp/issues) - Search existing reports or file a new one; attach the `/view-logs` archive to bug reports. -* [{VARS.WARP_CLI} reference](/cli/reference/) - Flags, environment variables, slash commands, and keyboard shortcuts. +{/* TODO(cli-reference): feedback and support channels; link to support-and-community pages. */} From 4bed38ab58a061643013f5328c517b1146b927ea Mon Sep 17 00:00:00 2001 From: Hong Yi Chen Date: Tue, 28 Jul 2026 15:08:46 -0700 Subject: [PATCH 04/10] docs(cli): rename literal Warp CLI to Warp Agent CLI in frontmatter Follows the base-branch WARP_CLI var value change; body prose picks up the new name automatically via {VARS.WARP_CLI}. Co-Authored-By: Oz --- src/content/docs/cli/models-and-usage.mdx | 6 +++--- src/content/docs/cli/reference.mdx | 6 +++--- 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/src/content/docs/cli/models-and-usage.mdx b/src/content/docs/cli/models-and-usage.mdx index 214b46af..a9fcecdc 100644 --- a/src/content/docs/cli/models-and-usage.mdx +++ b/src/content/docs/cli/models-and-usage.mdx @@ -1,8 +1,8 @@ --- -title: "Models and usage in the Warp CLI" +title: "Models and usage in the Warp Agent CLI" description: >- - Choose models in the Warp CLI, bring your own API key, and track credit - usage and per-response cost. + Choose models in the Warp Agent CLI, bring your own API key, and track + credit usage and per-response cost. --- import { VARS } from '@data/vars'; diff --git a/src/content/docs/cli/reference.mdx b/src/content/docs/cli/reference.mdx index f3fdcc44..ed642305 100644 --- a/src/content/docs/cli/reference.mdx +++ b/src/content/docs/cli/reference.mdx @@ -1,8 +1,8 @@ --- -title: "Warp CLI reference" +title: "Warp Agent CLI reference" description: >- - Reference for the Warp CLI: command-line flags, environment variables, slash - commands, keyboard shortcuts, and troubleshooting. + Reference for the Warp Agent CLI: command-line flags, environment variables, + slash commands, keyboard shortcuts, and troubleshooting. --- import { VARS } from '@data/vars'; From 1c6b6aea556bddf249bae61e0d99ec970ba0f766 Mon Sep 17 00:00:00 2001 From: Hong Yi Chen Date: Wed, 29 Jul 2026 15:49:13 -0700 Subject: [PATCH 05/10] docs(cli): security fixes for API key examples Address review feedback: - Make WARP_API_KEY=... warp the primary non-interactive auth example and document --api-key secondarily with a caution that command-line arguments can be captured in shell history and process listings. - Replace the persistent key.txt stdin example with a tool-agnostic secret-manager pipe and a note against staging keys in plaintext files. Co-Authored-By: Oz --- src/content/docs/cli/reference.mdx | 22 ++++++++++++++++++---- 1 file changed, 18 insertions(+), 4 deletions(-) diff --git a/src/content/docs/cli/reference.mdx b/src/content/docs/cli/reference.mdx index ed642305..d893e7dd 100644 --- a/src/content/docs/cli/reference.mdx +++ b/src/content/docs/cli/reference.mdx @@ -26,11 +26,23 @@ warp --resume CONVERSATION_TOKEN Authenticates with a Warp API key instead of the interactive browser login. Useful on hosts where a browser sign-in is inconvenient. +Prefer supplying the key through the `WARP_API_KEY` environment variable: + +```bash +WARP_API_KEY=YOUR_API_KEY warp +``` + +The `--api-key` flag accepts the same value directly: + ```bash warp --api-key YOUR_API_KEY ``` -The key can also be supplied through the `WARP_API_KEY` environment variable. Create a key in the Warp app under **Settings** > **Platform**; see the [API keys reference](/reference/cli/api-keys/) for details. +:::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. ### `--set-provider-api-key` @@ -40,12 +52,14 @@ Securely stores a model-provider API key for [Bring Your Own API Key (BYOK)](/ag warp --set-provider-api-key anthropic ``` -The CLI prompts for the key with masked input, so the key never appears in your shell history. When stdin is piped, the key is read from stdin instead: +The CLI prompts for the key with masked input, so the key never appears in your shell history. When stdin is piped, the key is read from stdin instead, so you can pass it straight from a secret manager without writing it to disk: ```bash -warp --set-provider-api-key anthropic < key.txt +your-secret-manager read anthropic-api-key | warp --set-provider-api-key anthropic ``` +Avoid staging keys in plaintext files; if you must use a temporary file, delete it immediately afterward. + See [models and usage](/cli/models-and-usage/) for how stored keys affect billing. ### `--clear-provider-api-key` @@ -212,7 +226,7 @@ The {VARS.WARP_CLI} signs you in with a browser-based flow: it opens a verificat 2. Enter the code shown in the CLI. 3. Return to the CLI; it proceeds automatically once the sign-in is approved. -For machines where the browser flow isn't practical, authenticate non-interactively with an API key instead, using `warp --api-key` or the `WARP_API_KEY` environment variable. See [command-line flags](#command-line-flags). +For machines where the browser flow isn't practical, authenticate non-interactively with an API key instead, using the `WARP_API_KEY` environment variable or the `--api-key` flag. See [command-line flags](#command-line-flags). ### "Login failed" From e01fc3765786469a8f4d7ed578af80e890a259f0 Mon Sep 17 00:00:00 2001 From: Hong Yi Chen Date: Wed, 29 Jul 2026 16:08:15 -0700 Subject: [PATCH 06/10] docs(cli): editorial polish pass Reduce product-name density after each page's intro (prefer "the CLI"), vary repeated trailing "See [X]" sentences, and fold two cross-links into their sentences. No structural, factual, heading, or link-target changes. Co-Authored-By: Oz --- src/content/docs/cli/models-and-usage.mdx | 6 +++--- src/content/docs/cli/reference.mdx | 20 ++++++++++---------- 2 files changed, 13 insertions(+), 13 deletions(-) diff --git a/src/content/docs/cli/models-and-usage.mdx b/src/content/docs/cli/models-and-usage.mdx index a9fcecdc..c255d74d 100644 --- a/src/content/docs/cli/models-and-usage.mdx +++ b/src/content/docs/cli/models-and-usage.mdx @@ -18,7 +18,7 @@ Your choice is saved as the base model of your active profile, so it persists ac ## Bring your own API key -The {VARS.WARP_CLI} supports [Bring Your Own API Key (BYOK)](/agent-platform/inference/bring-your-own-api-key/) for OpenAI, Anthropic, and Google models. When you select a model covered by one of your keys, requests are billed through your provider account and don't consume your Warp [credits](/support-and-community/plans-and-billing/credits/). +The CLI supports [Bring Your Own API Key (BYOK)](/agent-platform/inference/bring-your-own-api-key/) for OpenAI, Anthropic, and Google models. When you select a model covered by one of your keys, requests are billed through your provider account and don't consume your Warp [credits](/support-and-community/plans-and-billing/credits/). To store a key, run `/add-api-key` with one of `openai`, `anthropic`, or `google`: @@ -38,11 +38,11 @@ Warp's built-in Auto models always consume Warp credits, even with BYOK configur [Custom routers](/agent-platform/inference/custom-routers/) appear in the `/model` picker alongside individual models. Select one and each prompt resolves to a concrete model using the routing logic you defined. -The CLI loads the same router definitions as the Warp app: YAML files in `~/.warp/custom_model_routers/`, plus any team-synced routers your admin shares. See [authoring a router as a file](/agent-platform/inference/custom-routers/#author-a-router-as-a-file) for the file format. +The CLI loads the same router definitions as the Warp app: YAML files in `~/.warp/custom_model_routers/`, plus any team-synced routers your admin shares. [Authoring a router as a file](/agent-platform/inference/custom-routers/#author-a-router-as-a-file) documents the file format. ## Usage and cost -The {VARS.WARP_CLI} shows usage at two levels: a running total for the conversation, and a per-response breakdown. +The CLI shows usage at two levels: a running total for the conversation, and a per-response breakdown. * **Conversation total** - Once a conversation has reported any usage, the footer shows its accumulated credits (for example, `2.5 credits`). Click the entry to switch between credits and the equivalent provider cost in dollars; the choice persists across sessions. * **Per-response details** - Run `/cost` to toggle a summary row under the latest response showing how long it took and how many credits it spent (for example, `12s • 1.2 credits`). The summary appears once the response finishes. diff --git a/src/content/docs/cli/reference.mdx b/src/content/docs/cli/reference.mdx index d893e7dd..6669c107 100644 --- a/src/content/docs/cli/reference.mdx +++ b/src/content/docs/cli/reference.mdx @@ -20,7 +20,7 @@ Resumes a previous conversation by its conversation token. 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 [conversations in the {VARS.WARP_CLI}](/cli/conversations/) for how persistence and resuming work. +`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 [conversations in the CLI](/cli/conversations/) for how persistence and resuming work. ### `--api-key` @@ -60,7 +60,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. -See [models and usage](/cli/models-and-usage/) for how stored keys affect billing. +[Models and usage](/cli/models-and-usage/) covers how stored keys affect billing. ### `--clear-provider-api-key` @@ -123,7 +123,7 @@ Type `/` at the start of the input to open the slash command menu, then keep typ | `/view-logs` | | Bundle your logs into a zip archive | | `/voice` | | Start voice input (`Ctrl+S`) | -Skills also appear in the same menu under their own names, so you can invoke a skill directly as `/skill-name`. See [context in the {VARS.WARP_CLI}](/cli/context/) for how skills are discovered. +Skills also appear in the same menu under their own names, so you can invoke a skill directly as `/skill-name`. [Context in the CLI](/cli/context/) covers how skills are discovered. ## Keyboard shortcuts @@ -149,7 +149,7 @@ Press `?` on an empty input to open the contextual shortcuts panel inside the CL ### Approvals -These bindings apply while the agent is waiting for you to approve an action. See [permissions and profiles](/cli/permissions-and-profiles/) for how approvals work. +These bindings apply while the agent is waiting for you to approve an action; [permissions and profiles](/cli/permissions-and-profiles/) explains the approval flow. | Shortcut | Action | | --- | --- | @@ -169,7 +169,7 @@ While the agent is running an interactive terminal command, or you have taken co ### Multi-agent tabs -When you run multiple agents, a tab bar appears above the session. See [cloud and orchestration](/cli/cloud-and-orchestration/) for details. +When you run multiple agents, a tab bar appears above the session; [cloud and orchestration](/cli/cloud-and-orchestration/) covers the workflow. | Shortcut | Action | | --- | --- | @@ -204,7 +204,7 @@ For mouse support, completions, and other input behavior, see [input and editing ## Troubleshooting -This section covers common {VARS.WARP_CLI} issues: gathering logs for a bug report, fixing sign-in problems, resuming conversations, and keeping the CLI up to date. +This section covers common issues: gathering logs for a bug report, fixing sign-in problems, resuming conversations, and keeping the CLI up to date. :::note For known issues and feature requests across Warp, visit the [GitHub issues page](https://github.com/warpdotdev/Warp/issues). @@ -216,11 +216,11 @@ 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, {VARS.WARP_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 only a limited number of recent sessions are kept. The `/view-logs` archive is written to the same directory. ### The browser doesn't open during sign-in -The {VARS.WARP_CLI} signs you in with a browser-based flow: it opens a verification page (or shows you the URL and a code to enter) and continues once you approve the sign-in. On a remote or browser-less machine, the CLI can't launch a browser, but the sign-in screen still shows the verification URL and code. +The CLI signs you in with a browser-based flow: it opens a verification page (or shows you the URL and a code to enter) and continues once you approve the sign-in. On a remote or browser-less machine, the CLI can't launch a browser, but the sign-in screen still shows the verification URL and code. 1. Open the displayed URL in a browser on any device, including another machine. 2. Enter the code shown in the CLI. @@ -247,11 +247,11 @@ The sign-in attempt was rejected or timed out; the message shows the underlying 1. Press `Ctrl+C` to exit, then run `warp` to start normally. 2. Check the token against the resume command printed when you exited the original session. -3. If the conversation exists locally, open it with `/conversations` instead. See [conversations in the {VARS.WARP_CLI}](/cli/conversations/). +3. If the conversation exists locally, open it from the [conversation list](/cli/conversations/) with `/conversations` instead. ### Updating -The {VARS.WARP_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 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. To check which version you're running, use `/version` in a session, or run: From 1ff54b74ba82cd15f53593518bcf83ed604dfe56 Mon Sep 17 00:00:00 2001 From: Hong Yi Chen Date: Wed, 29 Jul 2026 16:24:55 -0700 Subject: [PATCH 07/10] docs(cli): trim menu-mechanics narration Cut the type-to-filter/arrows/Enter sentence from the model picker prose and the keep-typing-to-filter clause from the slash-command intro, per the editorial bar against narrating self-evident UI mechanics. Defaults, exceptions, and lookup tables are unchanged. Co-Authored-By: Oz --- src/content/docs/cli/models-and-usage.mdx | 2 +- src/content/docs/cli/reference.mdx | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/src/content/docs/cli/models-and-usage.mdx b/src/content/docs/cli/models-and-usage.mdx index c255d74d..bdf00d9c 100644 --- a/src/content/docs/cli/models-and-usage.mdx +++ b/src/content/docs/cli/models-and-usage.mdx @@ -12,7 +12,7 @@ The {VARS.WARP_CLI} gives you the same model options as the Warp app: pick the m Run `/model` to open the model picker. You can also click the model name in the footer to open the same picker. -The picker lists every model available to your account, with the active model preselected. Type to filter the list, press `↑` and `↓` to move through it, and press `Enter` to switch. Models that your plan or your team's settings don't allow appear in the list as disabled. +The picker lists every model available to your account, with the active model preselected. Models that your plan or your team's settings don't allow appear in the list as disabled. Your choice is saved as the base model of your active profile, so it persists across sessions. See [permissions and profiles](/cli/permissions-and-profiles/) for how profiles work in the CLI, and [Model choice](/agent-platform/inference/model-choice/) for the full list of supported models and how Warp's Auto models pick one for you. diff --git a/src/content/docs/cli/reference.mdx b/src/content/docs/cli/reference.mdx index 6669c107..289d4c2e 100644 --- a/src/content/docs/cli/reference.mdx +++ b/src/content/docs/cli/reference.mdx @@ -93,7 +93,7 @@ warp --help ## Slash commands -Type `/` at the start of the input to open the slash command menu, then keep typing to filter it. Commands that take an argument show a hint after the command name. Angle brackets mark required arguments; square brackets mark optional ones. +Type `/` at the start of the input to open the slash command menu. Commands that take an argument show a hint after the command name. Angle brackets mark required arguments; square brackets mark optional ones. | Command | Argument | Description | | --- | --- | --- | From 1823ff37008d8a051bfa00ea55a6968c50c17dca Mon Sep 17 00:00:00 2001 From: Hong Yi Chen Date: Wed, 29 Jul 2026 16:32:41 -0700 Subject: [PATCH 08/10] docs(cli): note macOS Option-as-Alt requirement for Alt shortcuts Platform audit: every keybinding registration is identical on macOS and Linux (the only platform-conditional binding is a Windows-only Alt+V paste, which is not documented since no Windows build ships). Input arrives as terminal key events, so Alt shortcuts depend on the host terminal delivering Option as Alt on macOS; add one note to the keyboard shortcuts section instead of per-row annotations. Co-Authored-By: Oz --- src/content/docs/cli/reference.mdx | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/src/content/docs/cli/reference.mdx b/src/content/docs/cli/reference.mdx index 289d4c2e..b2dfca77 100644 --- a/src/content/docs/cli/reference.mdx +++ b/src/content/docs/cli/reference.mdx @@ -129,6 +129,10 @@ 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 and Linux. For shortcuts that use `Alt`, some macOS terminals deliver `Option` as `Alt` only when their Option-as-Alt (Meta) setting is enabled. +::: + ### Session | Shortcut | Action | From 876172d31b03e51ef1ca70c425755a0b2e8e6441 Mon Sep 17 00:00:00 2001 From: Hong Yi Chen Date: Wed, 29 Jul 2026 16:37:56 -0700 Subject: [PATCH 09/10] docs(cli): tighten disabled-models sentence in model picker prose Co-Authored-By: Oz --- src/content/docs/cli/models-and-usage.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/cli/models-and-usage.mdx b/src/content/docs/cli/models-and-usage.mdx index bdf00d9c..f8d241c3 100644 --- a/src/content/docs/cli/models-and-usage.mdx +++ b/src/content/docs/cli/models-and-usage.mdx @@ -12,7 +12,7 @@ The {VARS.WARP_CLI} gives you the same model options as the Warp app: pick the m Run `/model` to open the model picker. You can also click the model name in the footer to open the same picker. -The picker lists every model available to your account, with the active model preselected. Models that your plan or your team's settings don't allow appear in the list as disabled. +Models that your plan or your team's settings don't allow appear disabled in the picker. Your choice is saved as the base model of your active profile, so it persists across sessions. See [permissions and profiles](/cli/permissions-and-profiles/) for how profiles work in the CLI, and [Model choice](/agent-platform/inference/model-choice/) for the full list of supported models and how Warp's Auto models pick one for you. From be1614256a6a0955734c0961e26d91f620985018 Mon Sep 17 00:00:00 2001 From: hongyi-chen Date: Thu, 30 Jul 2026 18:20:01 +0000 Subject: [PATCH 10/10] docs(cli): update API key docs for /api-keys menu and --auto-approve flag MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Address review feedback on the API key flow change (warpdotdev/warp#14472), which replaced /add-api-key and /clear-provider-api-key with a single inline /api-keys menu: - models-and-usage: rewrite the BYOK section around the /api-keys menu — set/replace/clear provider keys with masked entry, connect or disconnect X Premium/SuperGrok via browser sign-in, and toggle Warp credit fallback. The --set-provider-api-key/--clear-provider-api-key flags stay documented for scripting (they remain supported per the CODE-1930 spec). - reference: swap the /add-api-key and /clear-provider-api-key slash-command rows for /api-keys, and point --set-provider-api-key at the in-session menu. - reference: document the new --auto-approve flag (warpdotdev/warp#14483), which starts new conversations in that launch with auto-approve enabled. Co-Authored-By: Oz --- src/content/docs/cli/models-and-usage.mdx | 16 ++++++++-------- src/content/docs/cli/reference.mdx | 15 ++++++++++++--- 2 files changed, 20 insertions(+), 11 deletions(-) diff --git a/src/content/docs/cli/models-and-usage.mdx b/src/content/docs/cli/models-and-usage.mdx index f8d241c3..5fffd156 100644 --- a/src/content/docs/cli/models-and-usage.mdx +++ b/src/content/docs/cli/models-and-usage.mdx @@ -18,17 +18,16 @@ Your choice is saved as the base model of your active profile, so it persists ac ## Bring your own API key -The CLI supports [Bring Your Own API Key (BYOK)](/agent-platform/inference/bring-your-own-api-key/) for OpenAI, Anthropic, and Google models. When you select a model covered by one of your keys, requests are billed through your provider account and don't consume your Warp [credits](/support-and-community/plans-and-billing/credits/). +The CLI supports [Bring Your Own API Key (BYOK)](/agent-platform/inference/bring-your-own-api-key/) for OpenAI, Anthropic, and Google models, and can connect an [X Premium or SuperGrok subscription](/agent-platform/inference/grok-subscription/) for Grok models. When you select a model covered by one of your keys, requests are billed through your provider account and don't consume your Warp [credits](/support-and-community/plans-and-billing/credits/). -To store a key, run `/add-api-key` with one of `openai`, `anthropic`, or `google`: +Run `/api-keys` to open the key management menu. It lists each provider with its connection state, plus a Warp credit fallback toggle: -```text -/add-api-key anthropic -``` +* **Set a key** - Press `Enter` on OpenAI, Anthropic, or Google and enter the key. Input is masked, so the key never appears in your transcript or shell history, and it's saved to your device's secure storage. Warp does not store provider keys on its servers. +* **Replace or clear a key** - On a connected provider, `Enter` loads the stored key (still masked) for editing, and saving an empty field clears it. `Ctrl+X` clears the highlighted provider's key directly from the list. +* **Connect X Premium or SuperGrok** - Press `Enter` on the subscription row and the CLI opens your browser to sign in to your xAI account; `Ctrl+X` disconnects it. +* **Warp credit fallback** - Press `Enter` to toggle whether requests that fail through your key may be retried with Warp credits. Warp always prioritizes your API keys over Warp credits; see [failover and fallback behavior](/agent-platform/inference/bring-your-own-api-key/#failover-and-fallback-behavior). -The CLI prompts for the key with masked input, so the key never appears in your transcript or shell history, and saves it to your device's secure storage. Warp does not store provider keys on its servers. - -To remove a stored key, run `/clear-provider-api-key` with the same provider name. Both commands are also available outside a session as the `--set-provider-api-key` and `--clear-provider-api-key` flags; see the [{VARS.WARP_CLI} reference](/cli/reference/#command-line-flags). +For scripting, keys can also be stored or cleared outside a session with the `--set-provider-api-key` and `--clear-provider-api-key` flags; see the [{VARS.WARP_CLI} reference](/cli/reference/#command-line-flags). X Premium/SuperGrok connections require the browser sign-in, so they're managed only through `/api-keys`. :::note Warp's built-in Auto models always consume Warp credits, even with BYOK configured. To bill through your own account, select a specific provider model, or use a [custom router](/agent-platform/inference/custom-routers/#using-your-own-api-keys-byok) whose targets your keys cover. See [BYOK usage and billing behavior](/agent-platform/inference/bring-your-own-api-key/#byok-usage-and-billing-behavior) for the full rules. @@ -53,5 +52,6 @@ Credits are Warp's unit of usage for agent requests. For what credits cover and * [Model choice](/agent-platform/inference/model-choice/) - Supported models and how automatic model selection works. * [Bring Your Own API Key](/agent-platform/inference/bring-your-own-api-key/) - How BYOK works, key storage, and billing behavior. +* [SuperGrok subscription](/agent-platform/inference/grok-subscription/) - Use Grok models through your xAI account. * [Custom routers](/agent-platform/inference/custom-routers/) - Define routing logic that picks a model per task. * [{VARS.WARP_CLI} reference](/cli/reference/) - Flags and slash commands, including the API key commands. diff --git a/src/content/docs/cli/reference.mdx b/src/content/docs/cli/reference.mdx index b2dfca77..b33194e7 100644 --- a/src/content/docs/cli/reference.mdx +++ b/src/content/docs/cli/reference.mdx @@ -22,6 +22,16 @@ 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 [conversations in the CLI](/cli/conversations/) for how persistence and resuming work. +### `--auto-approve` + +Starts new conversations with auto-approve enabled, so the agent runs actions without asking for approval first. + +```bash +warp --auto-approve +``` + +The default applies only to that launch and doesn't change your saved settings: every conversation you start in the session begins with auto-approve on, and you can still toggle it per conversation with `/auto-approve` or `Ctrl+Shift+I`. See [permissions and profiles](/cli/permissions-and-profiles/) for how approvals work. + ### `--api-key` Authenticates with a Warp API key instead of the interactive browser login. Useful on hosts where a browser sign-in is inconvenient. @@ -60,7 +70,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. -[Models and usage](/cli/models-and-usage/) covers how stored keys affect billing. +Inside a session, manage the same keys with the `/api-keys` menu; [models and usage](/cli/models-and-usage/#bring-your-own-api-key) covers the menu and how stored keys affect billing. ### `--clear-provider-api-key` @@ -97,11 +107,10 @@ Type `/` at the start of the input to open the slash command menu. Commands that | Command | Argument | Description | | --- | --- | --- | -| `/add-api-key` | `` | Securely store a model-provider API key | | `/agent` | `[prompt]` | Start a new conversation | +| `/api-keys` | | View and manage API keys, including BYOK and Warp credit fallback | | `/auto-approve` | | Toggle auto-approve for agent actions | | `/clear` | `[prompt]` | Clear the transcript and start a new conversation | -| `/clear-provider-api-key` | `` | Remove a stored model-provider API key | | `/compact` | `[instructions]` | Free up context by summarizing the conversation history | | `/conversations` | | Open conversation history | | `/cost` | | Toggle per-response credit usage details |