warpdotdev · hongyi-chen · Jul 28, 2026 · Jul 28, 2026 · Jul 28, 2026 · Jul 28, 2026
diff --git a/src/content/docs/cli/models-and-usage.mdx b/src/content/docs/cli/models-and-usage.mdx
@@ -1,27 +1,57 @@
 ---
-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';
 
-{/* 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.
+
+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.
 
 ## 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 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. [Authoring a router as a file](/agent-platform/inference/custom-routers/#author-a-router-as-a-file) documents the file format.
 
 ## Usage and cost
 
-{/* TODO(cli-reference): footer credits entry, /cost toggle, last-response duration and credits. */}
+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.
+
+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
@@ -1,27 +1,274 @@
 ---
-title: "{{WARP_CLI}} reference"
+title: "Warp Agent CLI reference"
 description: >-
-  Reference for the {{WARP_CLI}}: command-line flags, environment variables,
-  slash commands, and keyboard shortcuts.
+  Reference for the Warp Agent CLI: command-line flags, environment variables,
+  slash commands, keyboard shortcuts, and troubleshooting.
 ---
 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, the default keyboard shortcuts, and fixes for common issues.
 
 ## 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 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.
+
+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
+```
+
+:::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`
+
+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, so you can pass it straight from a secret manager without writing it to disk:
+
+```bash
+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.
+
+[Models and usage](/cli/models-and-usage/) covers 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](#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. 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` | `<openai\|anthropic\|google>` | 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` | `<openai\|anthropic\|google>` | 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` | `<description>` | 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` | `<auto\|light\|dark>` | 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`. [Context in the CLI](/cli/context/) covers 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.
+
+:::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 |
+| --- | --- |
+| `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; [permissions and profiles](/cli/permissions-and-profiles/) explains the approval flow.
+
+| 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; [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 |
+
+### 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/).
+
+## Troubleshooting
+
+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).
+:::
+
+### 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, 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 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 the `WARP_API_KEY` environment variable or the `--api-key` flag. 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 from the [conversation list](/cli/conversations/) with `/conversations` instead.
+
+### 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.
+
+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.