Warp Agent CLI: The Warp Agent CLI: agent conversations, shell commands, permissions, and configuration in any terminal. # Warp Agent CLI overview Canonical page: [/agents/cli/](https://docs.warp.dev/agents/cli/) > Run the Warp Agent in any terminal with the Warp Agent CLI. Prompt the agent, run shell commands, and hand work off to cloud agents. The Warp Agent CLI brings the Warp Agent from the Warp app to the terminal you already use. Run the `warp` command to start an agent conversation. You can prompt the agent in natural language, review and approve its actions, and run shell commands in the same input, without changing your terminal setup. ## What is the Warp Agent CLI? [Section titled “What is the Warp Agent CLI?”](#what-is-the-warp-agent-cli) The Warp Agent CLI is a standalone terminal program that runs [the Warp Agent](/platform/harnesses/warp-agent/), the same agent that powers the Warp app. It renders conversations as a scrolling transcript in your terminal, with streaming responses, code diffs, tool calls, and permission requests you approve inline. The CLI is also a native terminal multiplexer. It creates and maintains its own pseudoterminal (PTY), which lets you and the agent execute commands and interact with running processes through the same terminal, including prompts and full-screen terminal apps. Because it’s a regular command-line program, it works in any terminal emulator, including over SSH. To get a working setup in a few minutes, follow the [quickstart](/agents/cli/quickstart/). ## Key features [Section titled “Key features”](#key-features) * **[Agent conversations](/agents/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](/agents/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](/agents/cli/permissions-and-profiles/)** - Approve commands and file edits from inline request cards, or configure execution profiles and auto-approve. * **[Persistent conversations](/agents/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](/agents/cli/cloud-and-orchestration/)** - Hand off a conversation to a cloud agent, continue cloud runs in the CLI, and coordinate multiple agents. * **[Project context](/agents/cli/configuration/#project-context-and-rules)** - The agent automatically picks up your project’s rules (like `AGENTS.md`), skills, and MCP servers. * **[Model choice](/agents/cli/models-and-usage/)** - Pick a model per conversation, bring your own provider API keys, and track credit usage. * **[Customization](/agents/cli/configuration/)** - Configure themes, the statusline, and the start screen through a local settings file. ## How it relates to the Warp app and cloud agents [Section titled “How it relates to the Warp app and cloud agents”](#how-it-relates-to-the-warp-app-and-cloud-agents) * **The Warp app** - The CLI runs the same [Warp Agent](/platform/harnesses/warp-agent/) harness as the Warp app, so your account, plan, model access, rules, and skills work the same in both. The CLI doesn’t require the Warp app to be installed. * **Automation Platform** - The Automation Platform is Warp’s programmable platform for running and coordinating agents at scale. The CLI connects to the same platform. Conversations sync to your Warp account, and you can hand work off to [cloud agents](/agents/cli/cloud-and-orchestration/) or continue a cloud run from your terminal. ## Checking your account, plan, and billing [Section titled “Checking your account, plan, and billing”](#checking-your-account-plan-and-billing) The CLI has slash commands for the account details you’d otherwise look up in the Warp app or the Oz web app. * **Session and account status** - Run `/status` to open a read-only panel with the installed version, the current conversation’s name and ID, the working directory, and the organization and email you’re signed in as. Press `Esc` to close it. Include these details when you report a problem. * **Upgrade your plan** - Run `/upgrade` to open Warp’s upgrade page in your browser. * **Manage team billing** - Run `/manage-billing` to open your team’s billing page in your browser. The command is listed only when you administer billing for your team. For how usage is metered as you work, see [models and usage](/agents/cli/models-and-usage/#usage-and-cost). ## Coming from the Warp app [Section titled “Coming from the Warp app”](#coming-from-the-warp-app) If you already use the Warp app, most of your setup carries over. Rules and skills are discovered from the same shared paths, and your saved Warp Drive prompts are available after you log in (other Warp Drive object types aren’t available in the CLI). To copy compatible settings and global MCP server configurations, run the bundled `/tui-migrate-setup` skill and follow the agent’s instructions. Credentials are never copied, so MCP servers that require authentication must be reauthenticated in the CLI. ## Next steps [Section titled “Next steps”](#next-steps) * [Quickstart](/agents/cli/quickstart/) - Install the CLI, log in, run your first prompt, and see the supported platforms. * [Agent conversations](/agents/cli/agent-conversations/) - Learn how the transcript, diffs, and approvals work. * [Input and shell commands](/agents/cli/input-and-shell-commands/) - Compose prompts and run shell commands from the same input. * [Configuration](/agents/cli/configuration/) - Customize the CLI with the settings file. * [Reference](/agents/cli/reference/) - Flags, slash commands, and keyboard shortcuts. # Agent conversations in the Warp Agent CLI Canonical page: [/agents/cli/agent-conversations/](https://docs.warp.dev/agents/cli/agent-conversations/) > Read, manage, and resume agent conversations in the Warp Agent CLI, including streamed responses, tool calls, file diffs, plans, and task lists. When you send the agent a prompt in the Warp Agent CLI, the conversation appears as a scrollable transcript directly in your terminal. Responses stream in as they’re generated, and everything the agent does renders inline: tool calls, file diffs, questions, task lists, and plans. Conversations persist as you work. You can start a new conversation, browse history, compact context, and [resume after exiting](#resuming-conversations). ## The conversation transcript [Section titled “The conversation transcript”](#the-conversation-transcript) The agent’s response streams into the transcript below your prompt as it’s generated. Press `Ctrl+C` once to stop a response that’s still in progress. Responses render as formatted Markdown, including syntax-highlighted code blocks and tables. Be aware of a few terminal-specific caveats: Mermaid diagrams appear as their source in a code block, images show their alt text instead of rendering inline, and very long code blocks are truncated to keep the transcript responsive. ## Tool calls [Section titled “Tool calls”](#tool-calls) Every tool call the agent makes appears inline in the transcript, in the order it happens. Most render as a one-line status row with a state glyph and a label describing the action, like “reading a file” or “searching your codebase”. Some tool calls render richer, interactive content: * **[Shell commands](/agents/cli/input-and-shell-commands/#shell-mode)** - Commands run in your session, with output streamed into the transcript. * **[File edits](#code-diffs)** - Expandable diffs with per-file headers. * **[Questions](#agent-questions)** - Interactive option prompts. * **[Plans](#planning)** - Inline plan documents. When a tool call needs your approval before it runs, an approval card appears in place of the input. See [permissions in the CLI](/agents/cli/permissions-and-profiles/) to learn how approvals work. ## Code diffs [Section titled “Code diffs”](#code-diffs) 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. The CLI renders diffs inline rather than in a separate editor. For how agent-generated changes work in the Warp app, including refining a diff in natural language, see [Agent code diffs and review](/agents/local-agents/code-diffs/). ## Thinking blocks [Section titled “Thinking blocks”](#thinking-blocks) For models that expose their reasoning, the agent’s thinking streams into a collapsible section with the header `Thinking...`, which collapses to a single `Thought for` row once it finishes. ## Agent questions [Section titled “Agent questions”](#agent-questions) When the agent needs a decision from you mid-task, it asks a question with an interactive option list that temporarily replaces the input. Use the arrow keys to navigate between options, or press an option’s number on your keyboard to select it. **Other…** accepts a free-form answer when the listed options don’t fit. Options the agent suggests as the best fit are labeled `(recommended)`. For multi-select questions, chosen options are marked with a check mark so you can select more than one. When the agent asks several questions at once, the card advances through them. To control whether the agent pauses to ask questions, see [Agent questions](/agents/local-agents/interacting-with-agents/agent-questions/). ## Task lists [Section titled “Task lists”](#task-lists) For multi-step work, the agent tracks its progress with a task list rendered directly in the transcript under a `≡ Tasks` header. Each task row starts with a status glyph: * `◌` - Pending * `●` - In progress * `✓` - Completed Canceled tasks appear struck through. As the agent finishes tasks, compact confirmation rows (e.g., `✓ Completed (2/5)`) track progress without repeating the whole list. Task lists in the CLI reflect the same agent behavior as in the Warp app. Learn more about [how task lists work](/agents/capabilities/task-lists/). ## Planning [Section titled “Planning”](#planning) To have the agent first research and produce a plan before making changes, use the `/plan` slash command followed by a description of your task. You can also ask for a plan in natural language. The plan renders inline in the transcript as a formatted document with its own header row showing the plan’s status. An `Updated plan` entry appears when the agent revises it. Press `Ctrl+Shift+P` to expand or collapse the latest plan. Planning in the CLI follows the same workflow as the Warp app. See [Planning](/agents/capabilities/planning/) to learn how to create, review, and execute plans. ## Selecting and copying output [Section titled “Selecting and copying output”](#selecting-and-copying-output) Select text anywhere in the transcript by clicking and dragging with the mouse. Releasing the mouse button copies the selection automatically. To copy an entire conversation as Markdown, use the `/export-to-clipboard` slash command, or use `/export-to-file` to save it to a file. ## Managing conversations [Section titled “Managing conversations”](#managing-conversations) The CLI saves every agent conversation as you work, so closing your terminal won’t lose your progress. ### Conversation persistence [Section titled “Conversation persistence”](#conversation-persistence) The CLI shows one conversation at a time. Opening a past conversation replaces the current transcript, and the previous one remains available in history. You can’t switch conversations while the current conversation is responding or a command is running. Finish or stop it with `Ctrl+C` first. Conversations sync to your Warp account, so the same history is available in the Warp app and on your other devices. See [Cloud-synced conversations](/agents/local-agents/cloud-conversations/) for details about syncing, restoring, and sharing work. ### Starting a new conversation [Section titled “Starting a new conversation”](#starting-a-new-conversation) Use any of these slash commands to clear the transcript and start a fresh conversation: * `/new` * `/agent` * `/clear` Each command accepts an optional prompt. For example, `/new write tests for the parser` starts a new conversation and immediately sends that prompt to the agent. To keep the history but reduce its size instead, use [`/compact`](#compacting-context). For guidance on when to start fresh rather than follow up, see [Interacting with agents](/agents/local-agents/interacting-with-agents/). ### Conversation history [Section titled “Conversation history”](#conversation-history) To browse and reopen past conversations, you can open the conversation menu in two ways: * **`/conversations`** - Run the slash command from the input. * **`←`** - Press the left arrow key when the input is empty and the cursor is at the start. The menu lists your Warp Agent conversations, including conversations started in the Warp app and completed cloud agent runs tied to your account. Start typing to filter the list by title. Caution If the CLI can’t load conversation data from Warp’s servers, the menu shows conversations from your local device only and displays a warning. Conversations from other devices reappear once the connection recovers. To continue a cloud agent run from the CLI, or to hand the current conversation off to a cloud agent, see [cloud handoff and orchestration](/agents/cli/cloud-and-orchestration/). ### Resuming conversations [Section titled “Resuming conversations”](#resuming-conversations) There are two ways to pick a past conversation back up: * **The [conversation menu](#conversation-history)** `(recommended)` - From a running session, press `←` or run `/conversations`, then filter to the conversation you want. * **`warp --resume`** - Reopens a specific conversation from your shell as the CLI starts, without going through the menu. When you exit the CLI with a non-empty conversation, it prints the `--resume` command for that conversation: ```bash To continue this conversation, run: warp --resume YOUR_CONVERSATION_TOKEN ``` `YOUR_CONVERSATION_TOKEN` is a conversation identifier generated by Warp. For the complete list of command-line flags, see the [CLI reference](/agents/cli/reference/). ### Compacting context [Section titled “Compacting context”](#compacting-context) Long conversations eventually fill the model’s [context window](/agents/local-agents/interacting-with-agents/#context-window-management), which can degrade response quality. The `/compact` command frees up context by asking the agent to summarize the conversation history so far and carry only the summary forward. * **`/compact`** - Summarizes the conversation history with default instructions. * **`/compact `** - Adds custom summarization instructions. For example, `/compact keep the API design decisions` tells the agent what to preserve in the summary. After compaction, a collapsed **Conversation summary** block appears in the transcript, and the conversation keeps working normally with the summary standing in for the compacted history. ## Related pages [Section titled “Related pages”](#related-pages) * [Permissions and profiles](/agents/cli/permissions-and-profiles/) - Approve, reject, or auto-approve the agent’s tool calls. * [Input and shell commands](/agents/cli/input-and-shell-commands/) - How commands the agent (or you) run appear in the transcript. * [Cloud handoff and orchestration](/agents/cli/cloud-and-orchestration/) - Hand off conversations to cloud agents and resume cloud runs. * [Warp Agent CLI reference](/agents/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. * [Agent code diffs and review](/agents/local-agents/code-diffs/) - Reviewing and refining agent-generated changes. * [Cloud-synced conversations](/agents/local-agents/cloud-conversations/) - How conversations sync, restore, and share across devices. # Cloud handoff and orchestration in the Warp Agent CLI Canonical page: [/agents/cli/cloud-and-orchestration/](https://docs.warp.dev/agents/cli/cloud-and-orchestration/) > Hand off Warp Agent CLI conversations to cloud agents, resume cloud runs, and run multi-agent orchestration from your terminal. The Warp Agent CLI connects your terminal sessions to the Automation Platform. You can hand off a local conversation to a cloud agent, pick a finished cloud run back up in your terminal, and coordinate multiple agents working in parallel, all without leaving the CLI. ## Hand off to a cloud agent [Section titled “Hand off to a cloud agent”](#hand-off-to-a-cloud-agent) Handoff promotes your Warp Agent CLI conversation into a cloud agent run. Use it when a task outgrows your machine: long-running work you don’t want to keep your laptop awake for, or work you want to check on later from another device. The [Handoff overview](/platform/handoff/) explains the feature across all Warp surfaces. This section covers the CLI flow. The cloud agent receives the same context as a handoff from the Warp app: * **Conversation history** - Warp forks the conversation, so the cloud agent sees the full transcript and your local conversation stays untouched. * **Workspace changes** - Warp snapshots your uncommitted repository changes, including untracked files, and applies them in the cloud run. * **Pending input** - The optional follow-up prompt and any images attached to the input move to the cloud run. See [what carries over](/platform/handoff/#what-carries-over) for the full behavior, and [Handoff from local to cloud](/platform/handoff/local-to-cloud/) for prerequisites. ### Hand off a conversation [Section titled “Hand off a conversation”](#hand-off-a-conversation) 1. In an active conversation, run `/handoff`, or `/handoff ` to give the cloud agent a follow-up prompt. The **Hand off to cloud** card replaces the input area while your transcript stays visible. 2. The card suggests your most recent environment (preferring one that contains the current repository) and preselects your conversation’s current model if it can run in the cloud. If the model is incompatible, it’s flagged so you can choose another before continuing. 3. To open the searchable environment and model selectors, press `Ctrl+E`. 4. From the card summary, press `Enter` to hand off. The card shows progress, then reports that the cloud run was created along with a link to the run. Press `Ctrl+C` at any point before confirming to cancel the handoff. Your prompt and attachments return to the input. From the created card: * **`Enter`** - Opens the cloud run in your browser. * **`C`** - Continues the conversation locally. The card collapses into a transcript banner with the run link, and the input reopens. * **`N`** - Starts a new conversation. Handoff needs the conversation in a state it can fork. You can’t hand off while a command is still running, or while the conversation has child agents that are in progress or blocked. Cancel the command or let the children finish first. Handing off an orchestrator forks only its own conversation. The orchestration and its child agents stay local. ## Resume cloud conversations [Section titled “Resume cloud conversations”](#resume-cloud-conversations) There are two ways to pick up a cloud agent’s work: * **In the browser** - Open the run in the Oz web app to review its transcript and changes, steer it, or continue the conversation there. [Viewing cloud agent runs](/platform/viewing-cloud-agent-runs/) covers that flow. * **In the CLI** - Pull a finished cloud run into your terminal. It appears in the conversation history alongside local conversations. Press `←` in an empty input, or run `/conversations`, to open the conversation list, then select the cloud run. Your next prompt continues the conversation locally. Resuming in the CLI has two constraints: * **The run must be finished** - Cloud runs that are still in progress or blocked can’t be opened in the CLI. * **Warp Agent runs only** - Conversations that ran with a different harness, such as Claude Code or Codex, can’t be opened in the CLI. You can also open a conversation directly at startup with `warp --resume `. See [managing conversations in the CLI](/agents/cli/agent-conversations/#managing-conversations) to learn more about conversation history and resume details. ## Multi-agent orchestration [Section titled “Multi-agent orchestration”](#multi-agent-orchestration) Orchestration lets one conversation spawn child agents that work in parallel, on your machine or in the cloud. The CLI runs the same parent/child model as the rest of the platform. [Multi-agent orchestration](/platform/orchestration/) covers the model, run states, and common patterns. To start an orchestration, ask the agent to parallelize the work, for example “split this migration across three agents”. You can also shape the configuration in your prompt. For example, ask for a specific model to manage token spend: keep the parent on a premium model while child agents handle research on a cheaper open-source model. When the agent decides to spawn child agents, the CLI shows an approval card titled **Can I start additional agents for this task?** that summarizes the agents it wants to launch and the run-wide configuration. By default, no child agents launch until you approve. The **Run orchestrated agents** permission in your profile controls this: **Always allow** skips the approval card, and **Never** blocks child agents entirely. See [Permissions and profiles](/agents/cli/permissions-and-profiles/). From the approval card: * **`Enter`** - Approves the request and launches the child agents. * **`Ctrl+E`** - Edits the configuration first: where the agents run (on your machine or in the cloud) and which model they use. Cloud agents add pages for the harness, environment, and host, plus an API key page for harnesses that need one. * **`Ctrl+C`** - Rejects the request. After launch, a tab bar labeled **Agents:** appears above the session with one tab for the orchestrator and one tab per child agent. Messages between the parent and child agents appear in each agent’s transcript.  The Agents: tab bar with one child agent running and two finished. * **Local child agents** - Each local child runs on your machine as its own session, starting in the parent’s working directory. Local children always run the Warp Agent. * **Cloud child agents** - Each cloud child runs in a cloud [environment](/platform/environments/), and can run a different harness than the parent, such as Claude Code or Codex, chosen on the approval card’s harness page. A cloud child’s session shows the run’s live status and a link. Press `Enter` or click the link to open the run in the Oz web app. If a cloud child can’t start because GitHub authentication is required, its session shows the authentication link. Authenticate, then ask the agent to run the orchestration again. Caution Cloud child sessions in the CLI only show status. They don’t accept input. To send prompts to a cloud child or respond to its approvals, open the run in the Oz web app. ## Managing child agents [Section titled “Managing child agents”](#managing-child-agents) The **Agents:** tab bar is how you move around an orchestration. * **Focus the tab bar** - Press `Shift+↑` from the input. The bar highlights the active conversation. * **Switch agents** - `Tab` or `→` selects the next agent and `Shift+Tab` or `←` the previous one, wrapping across the orchestrator and all children. Switching keeps the bar focused so you can keep cycling. * **Jump to an end** - `Shift+←` selects the first child and `Shift+→` selects the last one. * **Return to the conversation** - `↓` moves focus back to the current session’s input. `Esc` jumps back to the orchestrator. * **Use the mouse** - Tabs are clickable, and when there are more children than fit, arrows at the ends of the bar page through them without changing your selection. Each agent keeps its own session. Transcript position, input drafts, and running work are all preserved while you view another agent, and child agents keep working in the background. Tabs reorder as statuses change, moving children that need attention, such as blocked ones, toward the front of the bar. A focused local child behaves like a regular conversation. You can send it follow-up prompts and respond to its permission requests. If a child’s tab shows a blocked status, switch to that child to respond to its pending request. ### Kill a child agent [Section titled “Kill a child agent”](#kill-a-child-agent) `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. In the orchestrator’s own session, `Ctrl+C` keeps its usual behavior. ## Related pages [Section titled “Related pages”](#related-pages) * [Handoff overview](/platform/handoff/) - Directions of handoff and what carries over in each. * [Handoff from local to cloud](/platform/handoff/local-to-cloud/) - Prerequisites, the Warp app flow, and troubleshooting. * [Multi-agent orchestration](/platform/orchestration/) - The parent/child model, run states, and orchestration patterns. * [Viewing cloud agent runs](/platform/viewing-cloud-agent-runs/) - Open, inspect, and continue cloud runs in the Oz web app. * [Agent conversations in the CLI](/agents/cli/agent-conversations/#managing-conversations) - Conversation history, `/conversations`, and `--resume`. * [Environments](/platform/environments/) - Configure the repos, image, and setup commands cloud agents run with. # Customizing the Warp Agent CLI Canonical page: [/agents/cli/configuration/](https://docs.warp.dev/agents/cli/configuration/) > Configure Warp Agent CLI themes, the statusline, and the start screen, and give the agent context from project rules, skills, and MCP servers. The Warp Agent CLI keeps its configuration in a plain TOML settings file on your machine. You can change settings by editing the file directly, by running slash commands like `/theme` and `/statusline`, or by asking the agent to update a setting for you. Beyond the CLI’s own settings, this page also covers the agent’s context, which includes the project rules, skills, and MCP servers the agent picks up as you work. ## The settings file [Section titled “The settings file”](#the-settings-file) The CLI reads its settings from a `settings.toml` file: * **macOS** - `~/.warp_cli/settings.toml` * **Linux** - `~/.config/warp-terminal/cli/settings.toml` (respects `$XDG_CONFIG_HOME`) * **Windows** - `%LOCALAPPDATA%\warp\Warp\config\cli\settings.toml` The file is created the first time you change a setting, and you can also create it yourself. Settings use dotted TOML sections. For example: settings.toml ```toml [appearance] theme = "dark" ``` ## Edit settings [Section titled “Edit settings”](#edit-settings) Change settings any of these ways: ### Edit the file directly [Section titled “Edit the file directly”](#edit-the-file-directly) Open the settings file in your editor and change values directly. The CLI watches the file while it’s running and reloads most values as you save, so edits take effect without a restart. Theme edits are the exception: they apply the next time you run `/theme` or restart the CLI. If a value is invalid, the CLI logs the problem and uses the default for that setting instead. If the file can’t be parsed at all, the CLI starts with default settings. ### Use slash commands [Section titled “Use slash commands”](#use-slash-commands) Commands like `/theme` and `/statusline` open interactive panels for specific settings and save your choice to the settings file automatically. See [Themes](#themes) and [Statusline](#statusline). ### Ask the agent [Section titled “Ask the agent”](#ask-the-agent) Describe the change to the agent in your CLI session, in plain language. The CLI ships with a bundled skill and a schema of every available setting, which the agent uses to find the right key, validate the value, and update the settings file for you. Try prompts like: * “Switch my theme to light.” * “Add the time to my [statusline](#statusline).” * “What CLI settings can I change?” The agent’s edits follow the same hot-reload behavior as editing the file directly (see [Edit the file directly](#edit-the-file-directly)). For the full list of built-in skills, see [Bundled skills](#bundled-skills). ## Themes [Section titled “Themes”](#themes) The CLI renders with a light or dark color theme. Set it with the `/theme` slash command: * **`/theme auto`** - Matches the host terminal’s background (default). * **`/theme light`** - Always uses the light theme. * **`/theme dark`** - Always uses the dark theme. Running `/theme` applies the change immediately and persists it across sessions as the `theme` key under `[appearance]` in the settings file. In auto mode, detection runs at startup, so if you switch your terminal’s colors while the CLI is running, restart it or set a theme explicitly. ## Statusline [Section titled “Statusline”](#statusline) The statusline is the row below the CLI’s input box that shows session information at a glance. By default it shows the auto-approve indicator, the active model, the working directory, the Git branch, and the Git diff status inside a repository, plus the Vim mode indicator when Vim mode is on. You can enable any of these items:  The statusline with credit usage, context window usage, and task list chips enabled. * **Auto-approve indicator** - A clickable `▶▶` toggle for auto-approve, highlighted when it’s on. * **Vim mode indicator** - The active Vim mode (such as `NOR` or `INS`), shown only when Vim mode is enabled. * **Model** - The active model. Click it to open the model picker. * **Working directory** - The current working directory. * **Git branch** - The current branch, when the directory is a Git repository. * **Git branch status** - The branch, plus how far it is ahead of or behind its upstream (for example, `master • ↑1`). Enabling this replaces the plain Git branch chip, rather than adding a second one. * **Git diff status** - Files changed, with line additions and deletions. * **GitHub pull request** - The pull request for the current branch. Click it to open the PR on GitHub. * **Credit usage** - Credits used by the current conversation. Click it to switch between credits and provider cost. * **Context window usage** - How much of the model’s context window the conversation has used. * **Agent to-do list** - The agent’s progress through its current task list. You can also add the date, the time (12- or 24-hour), and a voice input control. Items only appear when they have something to show. For example, the Git items appear only inside a repository. In shell mode, the statusline always leads with a shell mode label. ### Customizing the statusline [Section titled “Customizing the statusline”](#customizing-the-statusline) Choose which items appear and in what order: 1. Run `/statusline`. The **Configure statusline** panel opens with every available item. 2. Select an item and press `Enter` to toggle its visibility. 3. Press `←` and `→` to move the highlighted item earlier or later in the row. 4. Press `Esc` to save and close. Press `Ctrl+C` to cancel without saving. Your choices are saved to the settings file, so the layout persists across sessions. To start over, run `/reset-statusline`, which restores the default items and ordering. ## Start screen [Section titled “Start screen”](#start-screen) The start screen appears when you launch the CLI, showing a rotating ASCII object alongside sections for your account, the changelog, project info, and MCP servers. Customize it with the `appearance.zero_state` settings: * **`object`** - The rotating object. Keep the built-in one, or point the setting at your own ASCII art file (a path relative to the CLI settings directory). Changing the setting reloads the object. Edits to the linked file take effect after a restart. * **`rotation_period_seconds`** - Seconds per full rotation, from 1 through 60. * **`show_signed_in_user`, `show_changelog`, `show_project_info`, `show_mcp`, `show_animation`** - Toggle individual start-screen sections. * **`freeze_animation_when_unfocused`** - Stop repainting the animation while your terminal window is unfocused, so an idle start screen doesn’t use CPU in the background. Off by default, and applied as soon as you save the setting. The fastest way to change these is to [ask the agent](#ask-the-agent), for example “use my own ASCII art for the start screen object”. ## Project context and rules [Section titled “Project context and rules”](#project-context-and-rules) The CLI gives its agent the same layered context system as the Warp app, combining your working directory, project rules, skills, and MCP servers, all scoped to the directory you’re working in. The agent works in your session’s current directory. When you `cd`, project rules and skills re-scope to the new directory automatically. Within a project, the CLI picks up the same rule files as the Warp app: * **Project rules** - `AGENTS.md` (or `WARP.md`) files in your repository apply automatically, starting from the repository root and your current directory. See [Rules](/agents/capabilities/rules/) for the file format, nested rules in subdirectories, and precedence. * **Global rules** - A rule file at `~/.agents/AGENTS.md` applies across all projects on your machine. Because rules and skills come from the same shared locations, a repository already configured for agents in the Warp app (or any tool that reads `AGENTS.md`) works in the CLI immediately. ## Skills [Section titled “Skills”](#skills) [Skills](/agents/capabilities/skills/) are reusable instruction sets the agent can invoke to perform specific tasks. The CLI discovers the same skills as the Warp app. Project skills come from your repository’s skill directories (e.g., `.agents/skills/`), and personal skills come from your home directory (e.g., `~/.agents/skills/`), scoped to your current working directory. Run `/skills` to browse every skill in scope. Selecting a skill inserts `/skill-name` into the input so you can add extra instructions before running it. Any text after the skill name is passed along, either as [skill arguments](/agents/capabilities/skills/#skill-arguments) or as additional context for the agent. You can also invoke a skill directly by typing `/` followed by its name, for example `/deploy push the latest changes to staging`. ### Bundled skills [Section titled “Bundled skills”](#bundled-skills) The CLI ships with built-in skills that appear in the skills menu alongside your own: * **`/modify-settings`** - Updates CLI settings using the bundled settings schema to find and edit the right key. See [Ask the agent](#ask-the-agent). * **`/tui-migrate-setup`** - Sets up the CLI from an existing Warp app installation. The agent copies compatible settings and global MCP server definitions from the app, and asks for approval before changing anything. Credentials and OAuth state are never copied, so MCP servers that require authentication prompt you to re-authenticate. Rules and skills don’t need migration: the CLI and the Warp app both discover them from the same file locations (see [Project context and rules](#project-context-and-rules) and [Skills](#skills)). ## MCP servers [Section titled “MCP servers”](#mcp-servers) [MCP servers](/agents/capabilities/mcp/) extend the agent with external tools and data sources. The CLI keeps its own MCP server configuration, separate from the Warp app’s, so each can run its own set of servers. Servers are defined in a JSON config file using the same `mcpServers` format as [file-based MCP servers](/agents/capabilities/mcp/#file-based-mcp-servers) in the Warp app (on macOS, the file is `~/.warp_cli/.mcp.json`). Edit the file to add or remove servers. The CLI picks up changes automatically. Configured servers start automatically once you’re logged in. ### Managing servers with `/mcp` [Section titled “Managing servers with /mcp”](#managing-servers-with-mcp) Type `/mcp` to open the MCP management view. The header shows the path to the config file the CLI is reading. Each configured server is listed with its transport (`stdio` or `HTTP/SSE`) and current status, including the number of tools a running server exposes. Press `Enter` on a server to start, stop, or retry it depending on its state. Failed rows show the error message. Servers awaiting authentication reopen the OAuth page in your browser, and servers with saved credentials show a **Log out** row that clears them. ## Related pages [Section titled “Related pages”](#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. * [Warp Agent CLI reference](/agents/cli/reference/) - Command-line flags, slash commands, and keyboard shortcuts. # Input and shell commands in the Warp Agent CLI Canonical page: [/agents/cli/input-and-shell-commands/](https://docs.warp.dev/agents/cli/input-and-shell-commands/) > Compose prompts, edit input, and run shell commands in the Warp Agent CLI, including menus, history, completions, images, voice, and interactive commands. The Warp Agent CLI is a full terminal as well as an agent. Every session runs a real shell, so you can run commands in the same place you prompt the agent. The input is a multiline editor that combines readline-style editing with inline menus for slash commands, history, and completions, plus mouse support, image attachments, and voice input. For the complete list of flags, slash commands, and keyboard shortcuts, see the [Warp Agent CLI reference](/agents/cli/reference/). ## Editing basics [Section titled “Editing basics”](#editing-basics) The input is a multiline editor. * **Insert a newline** - Press `Ctrl+J`, or `Shift+Enter` in terminals that support distinguishing it. `Alt+Enter` also works. * **Edit with readline-style keys** - The editor supports familiar bindings such as `Ctrl+A` and `Ctrl+E` (start and end of line), `Ctrl+W` (delete the previous word), `Ctrl+K` and `Ctrl+U` (delete to the end or start of the line), `Ctrl+Y` (reinsert the last deleted text), and `Ctrl+Z` (undo). * **Use macOS Command shortcuts** - When the Kitty keyboard protocol is enabled in your terminal, the editor supports Command-modified shortcuts such as `⌘+X` to cut and `⌘+Shift+←` or `⌘+Shift+→` to extend the selection. The full editing and selection table is in the [keyboard shortcuts reference](/agents/cli/reference/#keyboard-shortcuts). ### Vim mode [Section titled “Vim mode”](#vim-mode) If you prefer modal editing, run `/vim-mode` to toggle Vim keybindings in the input. The setting persists across sessions. Turn on the [statusline](/agents/cli/configuration/#statusline) Vim mode item to see the active mode (such as `NOR` or `INS`) while you type. ## Slash commands [Section titled “Slash commands”](#slash-commands) Type `/` at the start of an empty input to open the slash command menu. Entries for toggles and pickers show their current state, for example `/theme (currently auto: Dark)` or `/auto-approve (currently off)`. When a command takes an argument, the input shows a ghost-text argument hint after the full command name, for example `/theme `. Your [skills](/agents/cli/configuration/#skills) also appear in the slash command menu, so you can invoke a skill by typing `/` followed by its name. The [slash commands reference](/agents/cli/reference/#slash-commands) lists every command. ## Input history [Section titled “Input history”](#input-history) Press `↑` with the cursor on the first row of the input to open the history menu. * **What’s listed** - In agent mode, the menu combines your previous prompts and shell commands in one list, with commands marked by a `!` prefix. In [shell mode](#shell-mode), the menu lists commands only. * **Preview** - Moving the selection previews each entry in the input and switches the input to the matching mode: recalled commands run as shell commands, and recalled prompts go to the agent. * **Submit** - `Enter` runs the selection immediately. It doesn’t insert it for editing. * **Dismiss** - `Esc` restores what you had typed. Pressing `↓` past the newest entry does the same. ## Tab completions [Section titled “Tab completions”](#tab-completions) In [shell mode](#shell-mode), press `Tab` to complete the command you’re typing, including file and directory paths. * If exactly one completion matches, the CLI applies it immediately. * If several completions match, the CLI inserts the longest shared prefix and opens a completion menu. Press `Tab` again to cycle through the suggestions. ## Selection and clipboard [Section titled “Selection and clipboard”](#selection-and-clipboard) * **Highlight to copy** - Finishing a mouse selection in the input or the [conversation transcript](/agents/cli/agent-conversations/) automatically copies it. * **Keyboard selection** - Extend the selection with `Shift` plus the arrow keys, or select everything with `Ctrl+Shift+A`. Copy with `Ctrl+Shift+C` and cut with `Ctrl+X`. * **Paste** - Press `Ctrl+V` or `Ctrl+Shift+V` (also `Alt+V` on Windows). Your terminal’s own paste shortcut works as well. * **Click controls** - Interactive elements such as the **Voice** footer entry and the attachment bar controls respond to clicks. ## Attach images [Section titled “Attach images”](#attach-images) Attach images to a prompt so the agent can analyze them: * **Paste an image** - Copy an image to your clipboard and press `Ctrl+V`. * **Paste or drop a file path** - Paste the path to an image file, or drag the file onto your terminal window to insert its path. Absolute paths, paths relative to the working directory, and `~` paths all resolve. Supported formats are PNG, JPEG, GIF, and WebP. Attaching an image locks the input to agent mode, since images are sent to the agent rather than the shell. Attached images appear in an attachment bar above the input. Press `Tab` to focus the bar, `Backspace` to remove the selected attachment, and `Esc` to return to the input. ## Voice input [Section titled “Voice input”](#voice-input) Dictate prompts instead of typing them: Caution Voice input isn’t currently included in the official Linux build. Linux support is planned. 1. Start listening with `Ctrl+S`, the `/voice` slash command, or by clicking **Voice** in the footer. The footer shows **Listening** while recording. 2. Press `Enter`, or click the footer entry again, to stop recording. The transcribed text lands in the input so you can review and edit it before submitting. Press `Esc` while transcription is in progress to cancel it. `/voice` clears the input before recording, and `Ctrl+S` keeps what you’ve already typed. Voice input in the CLI uses the same transcription service as the Warp app. See [voice input for agents](/agents/local-agents/interacting-with-agents/voice/) for microphone setup, privacy, and usage limits. ## Keyboard hints and the shortcuts menu [Section titled “Keyboard hints and the shortcuts menu”](#keyboard-hints-and-the-shortcuts-menu) The CLI shows its shortcuts in context, so you rarely need to memorize them: * **Placeholder hints** - An empty input shows the key triggers for the current mode. * **Shortcuts menu** - Type `?` in an empty input to open a shortcuts overview. Its contents adapt to what you’re doing: agent mode lists the menu triggers and input history, shell mode shows how to return to agent mode, and extra sections appear during multi-agent sessions or agent-controlled terminal use. Press `Esc`, or start typing, to close it. ## Shell mode [Section titled “Shell mode”](#shell-mode) The input is agent-first: by default, pressing `Enter` sends your text to the agent as a prompt. Use shell mode to run a command instead: 1. Press `!` at the start of the input. The prompt marker changes from `>` to `!`, and the statusline below the input shows **Shell mode**. 2. Run a command. The input returns to agent mode afterward. To leave shell mode without running a command, press `Esc`, or press `Backspace` at the start of the input. Any text you typed stays in the input. In shell mode, press `Tab` to complete commands and paths. See [Tab completions](#tab-completions). ## Natural language detection [Section titled “Natural language detection”](#natural-language-detection) 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. 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. ## Long-running and interactive commands [Section titled “Long-running and interactive commands”](#long-running-and-interactive-commands) 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. 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. ## Full-screen terminal apps [Section titled “Full-screen terminal apps”](#full-screen-terminal-apps) 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. ## Stopping commands and exiting [Section titled “Stopping commands and exiting”](#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. 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. When you exit, the CLI prints a command you can use to pick the conversation back up later. See [Managing conversations](/agents/cli/agent-conversations/#managing-conversations) for resuming and switching conversations. ## Related pages [Section titled “Related pages”](#related-pages) * [Warp Agent CLI reference](/agents/cli/reference/) - Flags, environment variables, slash commands, and keyboard shortcuts. * [Agent conversations in the Warp Agent CLI](/agents/cli/agent-conversations/) - The transcript, tool calls, diffs, and managing conversations. # Models and usage in the Warp Agent CLI Canonical page: [/agents/cli/models-and-usage/](https://docs.warp.dev/agents/cli/models-and-usage/) > Choose models in the Warp Agent CLI, bring your own API key, and track credit usage and per-response cost. The Warp Agent CLI gives you the same model options as the Warp app. You can 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 [Section titled “Choosing a model”](#choosing-a-model) Run `/model` to open the model picker. You can also click the model name in the [statusline](/agents/cli/configuration/#statusline) 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](/agents/cli/permissions-and-profiles/) for how profiles work in the CLI. For the full list of supported models and to learn more about how Warp’s Auto models pick for you, see [Model choice](/agents/inference/model-choice/). ## Bring your own API key [Section titled “Bring your own API key”](#bring-your-own-api-key) The CLI supports [Bring Your Own API Key (BYOK)](/agents/inference/bring-your-own-api-key/) for OpenAI, Anthropic, and Google models, and can connect an [X Premium or SuperGrok subscription](/agents/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/). Run `/api-keys` to open the key management menu. It lists each provider with its connection state, plus a Warp credit fallback toggle: * **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 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. Running `/connect-grok` jumps straight to this row and starts the sign-in. * **Warp credit fallback** - Press `Enter` to toggle whether a request that fails through your key is retried with Warp credits. See [failover and fallback behavior](/agents/inference/bring-your-own-api-key/#failover-and-fallback-behavior). You can also store or clear keys outside a session with the `--set-provider-api-key` and `--clear-provider-api-key` flags. See the [Warp Agent CLI reference](/agents/cli/reference/#command-line-flags). X Premium/SuperGrok connections can only be managed from inside a session, with `/api-keys` or `/connect-grok`. ## Custom model routing [Section titled “Custom model routing”](#custom-model-routing) [Custom routers](/agents/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. These are YAML files in `~/.warp/custom_model_routers/`, plus any team-synced routers your admin shares. [Authoring a router as a file](/agents/inference/custom-routers/#author-a-router-as-a-file) documents the file format. ## Usage and cost [Section titled “Usage and cost”](#usage-and-cost) The CLI shows usage at two levels: * **Conversation total** - Once a conversation has reported any usage, the [statusline](/agents/cli/configuration/#statusline) shows its accumulated credits (e.g., `2.5 credits`). Click the entry to switch between credits and the equivalent provider cost in dollars. Your 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 (e.g., `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 [Section titled “Related pages”](#related-pages) * [Model choice](/agents/inference/model-choice/) - Supported models and how automatic model selection works. * [Bring Your Own API Key](/agents/inference/bring-your-own-api-key/) - How BYOK works, key storage, and billing behavior. * [SuperGrok subscription](/agents/inference/grok-subscription/) - Use Grok models through your xAI account. * [Custom routers](/agents/inference/custom-routers/) - Define routing logic that picks a model per task. * [Warp Agent CLI reference](/agents/cli/reference/) - Flags and slash commands, including the API key commands. # Permissions and profiles in the Warp Agent CLI Canonical page: [/agents/cli/permissions-and-profiles/](https://docs.warp.dev/agents/cli/permissions-and-profiles/) > Control what the agent can do in the Warp Agent CLI with permission request cards, auto-approve, and execution profiles in the settings file. The Warp Agent CLI uses the same permission model as the Warp app: you choose how much approval each type of action needs. This page covers how to set permissions in the CLI, what happens when the agent asks for approval, and how to grant full autonomy with auto-approve. For the full permission model, including team-wide controls, see [Profiles & Permissions](/agents/capabilities/agent-profiles-permissions/). ## How permissions work [Section titled “How permissions work”](#how-permissions-work) Every action the agent proposes, such as running a shell command, editing files, or calling an MCP tool, is checked against your active execution profile before it runs. Each action type is set independently to [`always_ask`, `always_allow`, or `agent_decides`](#permission-values). For example, you could require approval for every shell command while letting the agent read files without asking, or allow everything for an agent that never stops to ask. By default, the CLI applies these permission values: * **Shell commands, file edits, file reads, MCP tool calls** - `agent_decides`. For file edits, `agent_decides` still prompts every time, so you always review a diff before it’s applied. * **Typing into a running command, launching child agents** - Always asks. * **Command denylist** - Sits on top of these values. Matching commands require approval even when `execute_commands` is `always_allow`. Change any of this by [editing your execution profile](#execution-profiles). ## Approving agent actions [Section titled “Approving agent actions”](#approving-agent-actions) When an action needs your approval, the agent pauses and shows a permission card with the proposed command or file edits. Beyond approving or rejecting it, you can: * Select **Other** to reply with guidance instead of running the action. The agent adjusts its approach based on what you type. * Press `E` on a command card to edit it before approving. `Esc` exits the editor without rejecting the request. * Press `E` on a file-edits card to expand or collapse all diffs. ## Auto-approve [Section titled “Auto-approve”](#auto-approve) Auto-approve gives the agent full autonomy. Proposed actions run immediately, without permission cards, until the task finishes or you turn it off. Toggle it with `/auto-approve` or `Ctrl+Shift+I`. Auto-approve is scoped to a single conversation, and new conversations start with it off. To start every new conversation in a session with auto-approve already on, launch with `warp --auto-approve`. The statusline’s auto-approve indicator (`▶▶`) shows the current state and is on by default. If your profile sets `ask_user_question = "ask_except_in_auto_approve"`, the agent also skips clarifying questions while auto-approve is on. Danger With auto-approve on, the agent runs commands and applies file edits without review, including commands that match your own command denylist. Press `Ctrl+C` to stop the agent if it starts doing something you didn’t intend. To keep your denylist in force while auto-approve is on, turn off the bypass in your [settings file](/agents/cli/configuration/#the-settings-file): settings.toml ```toml [agents.warp_agent.other] auto_approve_bypasses_command_denylist = false ``` Denylist rules enforced by your team in the [Admin Panel](/enterprise/team-management/admin-panel/) always require approval and are never bypassed, regardless of this setting. ## Execution profiles [Section titled “Execution profiles”](#execution-profiles) The CLI reads its permissions from execution profiles stored in its [settings file](/agents/cli/configuration/). Profiles live under the `agents.execution_profiles` table, and the CLI always runs with the profile under the reserved `default` key: settings.toml ```toml [agents.execution_profiles.default] name = "Default" execute_commands = "agent_decides" apply_code_diffs = "agent_decides" read_files = "agent_decides" command_allowlist = ['cargo (build|check|test)(\s.*)?'] ``` Caution Setting `command_denylist` replaces the built-in default denylist, which covers `rm`, `curl`, `wget`, `eval`, `ssh`, shells, and other risky command patterns. Omitting the field keeps the defaults. To deny additional commands, extend the generated list in your settings file rather than writing a short list from scratch. Edit the file directly, or ask the agent to change its own permissions and it will update the settings file for you. The CLI picks up saved changes automatically. Profiles in the Warp Agent CLI are local to your machine. They never sync to the cloud, and they are separate from the Agent Profiles you configure in the Warp app. You can define additional profiles in the file, but the CLI currently always runs with `default`. ### Permission values [Section titled “Permission values”](#permission-values) Most permission fields accept one of three values: * **`agent_decides`** - The agent acts on its own when it’s confident and asks when it’s uncertain. * **`always_ask`** - Every action of this type requires approval. * **`always_allow`** - Actions of this type run without prompting. ### Profile fields [Section titled “Profile fields”](#profile-fields) * **`execute_commands`** - Permission to run shell commands. * **`apply_code_diffs`** - Permission to apply file edits. * **`read_files`** - Permission to read files. * **`mcp_permissions`** - Permission to call MCP servers. * **`write_to_pty`** - Permission to type into running interactive commands. Also accepts `ask_on_first_write`. * **`ask_user_question`** - Whether the agent may pause to ask clarifying questions: `always_ask`, `ask_except_in_auto_approve`, or `never`. * **`run_agents`** - Permission to launch child agents: `always_ask`, `always_allow`, or `never_allow`. * **`command_allowlist`** - Regular expressions for commands that run without approval. * **`command_denylist`** - Regular expressions for commands that require approval regardless of the other permission values. [Auto-approve bypasses this list by default](#auto-approve). * **`directory_allowlist`** - Directories the agent may read without approval. Profiles also hold model overrides such as `base_model`, covered in [Models and usage in the Warp Agent CLI](/agents/cli/models-and-usage/). ## Related pages [Section titled “Related pages”](#related-pages) * [Profiles & Permissions](/agents/capabilities/agent-profiles-permissions/) - The full permission model, autonomy levels, and allowlist/denylist behavior. * [Configuring the Warp Agent CLI](/agents/cli/configuration/) - The settings file, themes, statusline, and start screen. * [Agent conversations in the Warp Agent CLI](/agents/cli/agent-conversations/) - How tool calls, diffs, and agent questions render in the transcript. # Warp Agent CLI quickstart Canonical page: [/agents/cli/quickstart/](https://docs.warp.dev/agents/cli/quickstart/) > Install the Warp Agent CLI, log in, and run your first agent conversation in your own terminal in a few minutes. This guide takes you from installing the Warp Agent CLI to your first agent conversation in about five minutes. ## Prerequisites [Section titled “Prerequisites”](#prerequisites) * **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 (Apple Silicon or Intel), Linux (x64 or Arm64), or Windows (x64 or Arm64). ## 1. Install the Warp Agent CLI [Section titled “1. Install the Warp Agent CLI”](#1-install-the-warp-agent-cli) Install the CLI with the command for your operating system. The install script is the recommended method, because it’s the only one that keeps the CLI up to date on its own. * macOS and Linux ```bash curl -fsSL https://app.warp.dev/download/agent-cli | bash ``` * Windows Run this command in PowerShell: ```powershell Invoke-RestMethod "https://app.warp.dev/download/agent-cli.ps1" | Invoke-Expression ``` * Homebrew On macOS 14 or later and on Linux, install the `warp-agent-cli` cask. It’s in the main Homebrew cask repository, so you don’t need to tap anything first: ```bash brew install --cask warp-agent-cli ``` Caution Homebrew installations don’t update themselves. The CLI still tells you when a new version is available, but you install it by running `brew upgrade --cask warp-agent-cli`. To get background updates instead, use the install script. After installing, verify that the `warp` command is available: ```bash warp --version ``` The command prints the installed version. ## 2. Log in [Section titled “2. Log in”](#2-log-in) Log in once so the CLI can access your Warp account, models, and saved context. Start the CLI: ```bash warp ``` 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. You stay signed in across sessions. To sign out later, run `/logout`, which returns the CLI to its login screen and signs out your browser session too. ## 3. Run your first prompt [Section titled “3. 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`. 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](/agents/cli/agent-conversations/) and [Permissions and profiles](/agents/cli/permissions-and-profiles/). ## 4. Run a shell command [Section titled “4. Run a shell command”](#4-run-a-shell-command) You can run shell commands directly without leaving the CLI. 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](/agents/cli/input-and-shell-commands/) for long-running commands, interactive programs, and full-screen apps. ## 5. Exit and resume [Section titled “5. 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. On exit, the CLI prints a resume command for the conversation: ```bash warp --resume CONVERSATION_TOKEN ``` 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](/agents/cli/agent-conversations/#conversation-history). ## Next steps [Section titled “Next steps”](#next-steps) * [Agent conversations](/agents/cli/agent-conversations/) - Work with the transcript, code diffs, plans, and tasks. * [Customizing the CLI](/agents/cli/configuration/) - Rules, skills, MCP servers, themes, and settings. * [Reference](/agents/cli/reference/) - All flags, slash commands, and keyboard shortcuts. # Warp Agent CLI reference Canonical page: [/agents/cli/reference/](https://docs.warp.dev/agents/cli/reference/) > Look up Warp Agent CLI command-line flags, environment variables, slash commands, keyboard shortcuts, and fixes for common issues. This page is a lookup reference for the Warp Agent CLI, covering 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 [Section titled “Command-line flags”](#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. They are listed alphabetically. ### `--api-key` [Section titled “--api-key”](#--api-key) 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_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** > **Cloud platform** > **Automation Platform Cloud API Keys**. See the [API keys reference](/reference/cli/api-keys/) for details. ### `--auto-approve` [Section titled “--auto-approve”](#--auto-approve) Starts new conversations with auto-approve enabled, so the agent runs actions without asking for approval first. ```bash warp --auto-approve ``` 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](/agents/cli/permissions-and-profiles/) for how approvals work. ### `--clear-provider-api-key` [Section titled “--clear-provider-api-key”](#--clear-provider-api-key) Deletes a stored model-provider API key from your device’s secure storage, then exits. ```bash warp --clear-provider-api-key ``` `` is `openai`, `anthropic`, or `google`. For example: ```bash warp --clear-provider-api-key anthropic ``` ### `--help` [Section titled “--help”](#--help) Prints usage information for all flags and exits. ```bash warp --help ``` ### `--resume` [Section titled “--resume”](#--resume) 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](/agents/cli/agent-conversations/#managing-conversations) for how persistence and resuming work. ### `--set-provider-api-key` [Section titled “--set-provider-api-key”](#--set-provider-api-key) 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 ``` 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. Inside a session, manage the same keys with the `/api-keys` menu. See [models and usage](/agents/cli/models-and-usage/#bring-your-own-api-key) for how stored keys affect billing. ### `--version` [Section titled “--version”](#--version) Prints the installed version and exits. ```bash warp --version ``` ## Environment variables [Section titled “Environment variables”](#environment-variables) * **`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 [Section titled “Slash commands”](#slash-commands) 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, and square brackets mark optional ones. | Command | Argument | Description | | ----------------------------- | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `/agent` | `[prompt]` | Start a new conversation | | `/api-keys` | | View and manage model-provider API keys | | `/auto-approve` | | Toggle auto-approve for agent actions | | `/clear` | `[prompt]` | Clear the transcript and start a new conversation | | `/compact` | `[instructions]` | Free up context by summarizing the conversation history | | `/connect-grok` | | Connect an X Premium or SuperGrok subscription for Grok models | | `/conversations` | | Open conversation history | | `/copy-debugging-id` | | Copy the current conversation’s debugging information to the clipboard | | `/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 | | `/fork` | `[prompt]` | Fork the current conversation into a copy, optionally sending a prompt in the copy | | `/handoff` | `[prompt]` | Hand off this conversation to a cloud agent | | `/logout` | | Log out of Warp | | `/manage-billing` | | Open your team’s billing page in the browser | | `/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`) | | `/orchestrate` | `[task]` | Break a task into subtasks and run them in parallel with multiple agents. See [multi-agent orchestration](/agents/cli/cloud-and-orchestration/#multi-agent-orchestration) | | `/plan` | `[task]` | Ask the agent to research and create a plan for a task | | `/reset-statusline` | | Restore the statusline to its default items and ordering | | `/skills` | | Browse skills in scope and insert one into the input | | `/status` | | Show session and account status | | `/statusline` | | Configure the statusline | | `/theme` | `` | Set the color theme | | `/upgrade` | | Open the Warp upgrade page in the browser | | `/view-logs` | | Bundle your logs into a zip archive | | `/vim-mode` | | Toggle Vim keybindings in the input | | `/voice` | | Start voice input | Some commands appear only when they apply to your account. `/manage-billing` is listed when you administer billing for your team, and opens that team’s billing page; it isn’t available to members without billing access. `/connect-grok` opens the same subscription row as [`/api-keys`](/agents/cli/models-and-usage/#bring-your-own-api-key) and starts the xAI sign-in directly. `/status` opens a read-only panel with the installed version, the current conversation’s name and ID, the working directory, and the organization and email you’re signed in as. Press `Esc` to close it, and include those details when you report a problem. Skills also appear in the same menu under their own names, so you can invoke a skill directly as `/skill-name`. [Customizing the CLI](/agents/cli/configuration/) covers how skills are discovered. ## Keyboard shortcuts [Section titled “Keyboard shortcuts”](#keyboard-shortcuts) Press `?` on an empty input to open the contextual shortcuts panel inside the CLI. The tables below list the default bindings. ### Session [Section titled “Session”](#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 [Section titled “Approvals”](#approvals) These bindings apply while the agent is waiting for you to approve an action. [Permissions and profiles](/agents/cli/permissions-and-profiles/) explains the approval flow. | Shortcut | Action | | ------------ | ----------------------------------------------------------------------------------- | | `Enter` | Confirm the selected option on the approval card | | `Esc` | Reject or cancel the request | | `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 [Section titled “Terminal control”](#terminal-control) These bindings apply while an interactive terminal command is running. | Shortcut | Action | | -------- | ---------------------------------------------------------------------------------- | | `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 [Section titled “Multi-agent tabs”](#multi-agent-tabs) When an orchestration launches child agents, an **Agents:** tab bar appears above the session. [Cloud and orchestration](/agents/cli/cloud-and-orchestration/) covers the workflow. | Shortcut | Action | | -------------------------------- | ---------------------------------------------------------------- | | `Shift+↑` | Focus the agent tab bar | | `←` / `→` 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 [Section titled “Text editing”](#text-editing) The input supports 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` | Reinsert 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 shell commands](/agents/cli/input-and-shell-commands/). ## Troubleshooting [Section titled “Troubleshooting”](#troubleshooting) This section covers common issues, including gathering logs for a bug report, fixing sign-in problems, resuming conversations, and keeping the CLI up to date. ### Viewing and sharing logs [Section titled “Viewing and sharing logs”](#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 older session logs are rotated out over time. The `/view-logs` archive is written to the same directory. When the problem is with the agent’s response rather than the CLI itself, run `/copy-debugging-id` in the session. It copies the conversation’s debugging information to your clipboard so you can paste it into a bug report. See [Gathering AI conversation ID](/support-and-community/troubleshooting-and-support/sending-us-feedback/#gathering-ai-conversation-id). ### The browser doesn’t open during sign-in [Section titled “The browser doesn’t open during sign-in”](#the-browser-doesnt-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” [Section titled “”Login failed””](#login-failed) 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. 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 [Section titled “Signed in to the wrong account”](#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 [Section titled “”Could not restore conversation” when resuming”](#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 menu](/agents/cli/agent-conversations/#conversation-history) with `/conversations` instead. ### Updating [Section titled “Updating”](#updating) 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 `/status` in a session, or run: ```bash warp --version ``` 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](/agents/cli/configuration/#the-settings-file). If an install becomes corrupted, re-running the install command from the [quickstart](/agents/cli/quickstart/) replaces it with the latest version. ### Getting help [Section titled “Getting help”](#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.