From 64fff59451f6b6e10387fc132b1cfd1a083130ce Mon Sep 17 00:00:00 2001 From: Hong Yi Chen Date: Tue, 28 Jul 2026 14:29:52 -0700 Subject: [PATCH 1/8] docs(cli): draft the Warp CLI configuration page Cover the local TOML settings file (per-platform locations, hot reload, error fallback, local-only/no cloud sync), editing settings by asking the agent, /theme with terminal background detection, and the statusline with /statusline customization. Drop the keybindings section: custom keybinding overrides are not loaded by the CLI yet. Co-Authored-By: Oz --- src/content/docs/cli/configuration.mdx | 79 ++++++++++++++++++++++---- 1 file changed, 68 insertions(+), 11 deletions(-) diff --git a/src/content/docs/cli/configuration.mdx b/src/content/docs/cli/configuration.mdx index b83640bf..134fda79 100644 --- a/src/content/docs/cli/configuration.mdx +++ b/src/content/docs/cli/configuration.mdx @@ -1,31 +1,88 @@ --- title: "Configuring the {{WARP_CLI}}" description: >- - Configure the {{WARP_CLI}} with its TOML settings file, themes, statusline, - and keybindings. + Configure the {{WARP_CLI}} with its local TOML settings file, themes, and + statusline. CLI settings stay on your machine and are never cloud-synced. --- import { VARS } from '@data/vars'; -{/* TODO(cli-configuration): draft per drafts/warp-cli-launch-plan.md — "cli/configuration.mdx" section. Feature-doc content type. */} - -The {VARS.WARP_CLI} documentation for this page is in progress. +The {VARS.WARP_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. ## The settings file -{/* TODO(cli-configuration): TOML settings file location and behavior; settings are local to the CLI and not synced. */} +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: + +```toml title="settings.toml" +[appearance] +theme = "dark" +``` + +The CLI watches the settings file while it's running, so edits take effect immediately without a restart. 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. + +:::note +CLI settings are local to your machine and are never synced to the cloud. They are also independent from the Warp app's settings: the app and the CLI keep separate settings files, so changing one never affects the other. +::: ## Edit settings with the agent -{/* TODO(cli-configuration): asking the agent to update settings via the bundled skill. */} +The fastest way to change a setting is to ask the agent 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." +* "What CLI settings can I change?" + +Because the CLI hot-reloads the settings file, changes the agent makes apply immediately. To learn about the other built-in skills, see [bundled skills in the {VARS.WARP_CLI}](/cli/context/). ## Themes -{/* TODO(cli-configuration): /theme auto|light|dark, terminal background detection. */} +The {VARS.WARP_CLI} renders with a light or dark color theme. Set it with the `/theme` slash command: + +* **`/theme auto`** - Matches the host terminal's background. This is the default. +* **`/theme light`** - Always uses the light theme. +* **`/theme dark`** - Always uses the dark theme. + +Theme changes apply immediately and persist across sessions as the `theme` key under `[appearance]` in the settings file. + +In auto mode, the CLI probes the host terminal's default colors when it starts and picks the theme that matches the background: light backgrounds get the light theme, and dark or undetectable backgrounds get the dark theme. 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 -{/* TODO(cli-configuration): statusline contents and /statusline customization — confirm shipped before merge. */} +The statusline is the row below the CLI's input box that shows session information at a glance. By default it shows the active model, the working directory, and, inside a Git repository, the Git branch and diff status. You can enable any of these items: + +* **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** - How far the branch is ahead of or behind its upstream. +* **Git diff status** - Uncommitted line additions and deletions. +* **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. +* **Auto-approve indicator** - Appears when auto-approve is on. +* **Auto-queue next prompt indicator** - Appears when auto-queue is on. +* **Date** - The current date. +* **Time (12 hour format)** and **Time (24 hour format)** - The current time. +* **Voice input** - A control for starting voice input. + +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 + +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. -## Keybindings +## Related pages -{/* TODO(cli-configuration): customizing keybindings. */} +* [{VARS.WARP_CLI} reference](/cli/reference/) for every command-line flag, slash command, and keyboard shortcut. +* [Agent context in the {VARS.WARP_CLI}](/cli/context/) for rules, skills, and MCP configuration. From 3f1b827e474f15278dc9458c668e1e6639aa16a2 Mon Sep 17 00:00:00 2001 From: Hong Yi Chen Date: Tue, 28 Jul 2026 14:44:30 -0700 Subject: [PATCH 2/8] docs(cli): use literal Warp CLI in configuration frontmatter {{WARP_CLI}} tokens are not substituted in MDX frontmatter by the build pipeline, so the built title/description showed the raw token. Body prose keeps {VARS.WARP_CLI}. Co-Authored-By: Oz --- src/content/docs/cli/configuration.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/content/docs/cli/configuration.mdx b/src/content/docs/cli/configuration.mdx index 134fda79..5d553257 100644 --- a/src/content/docs/cli/configuration.mdx +++ b/src/content/docs/cli/configuration.mdx @@ -1,7 +1,7 @@ --- -title: "Configuring the {{WARP_CLI}}" +title: "Configuring the Warp CLI" description: >- - Configure the {{WARP_CLI}} with its local TOML settings file, themes, and + Configure the Warp CLI with its local TOML settings file, themes, and statusline. CLI settings stay on your machine and are never cloud-synced. --- import { VARS } from '@data/vars'; From ab60ec1e0184a3cc38b484d90d9d0b5b93e58155 Mon Sep 17 00:00:00 2001 From: Hong Yi Chen Date: Tue, 28 Jul 2026 15:01:36 -0700 Subject: [PATCH 3/8] docs(cli): absorb agent context content into the customization page Consolidate the CLI docs: fold the context page's rules, skills, bundled skills, and MCP sections into configuration.mdx, retitled "Customizing the Warp CLI". Dedupe the modify-settings bundled skill treatment and switch cross-links to in-page anchors. The context.mdx file itself is removed at integration. Co-Authored-By: Oz --- src/content/docs/cli/configuration.mdx | 70 +++++++++++++++++++++++--- 1 file changed, 63 insertions(+), 7 deletions(-) diff --git a/src/content/docs/cli/configuration.mdx b/src/content/docs/cli/configuration.mdx index 5d553257..e46873f9 100644 --- a/src/content/docs/cli/configuration.mdx +++ b/src/content/docs/cli/configuration.mdx @@ -1,12 +1,12 @@ --- -title: "Configuring the Warp CLI" +title: "Customizing the Warp CLI" description: >- - Configure the Warp CLI with its local TOML settings file, themes, and - statusline. CLI settings stay on your machine and are never cloud-synced. + Customize the Warp CLI: settings file, themes, statusline, and agent context + with project rules, skills, and MCP servers. --- import { VARS } from '@data/vars'; -The {VARS.WARP_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. +The {VARS.WARP_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: the project rules, skills, and MCP servers the agent picks up as you work. ## The settings file @@ -37,7 +37,7 @@ The fastest way to change a setting is to ask the agent in plain language. The C * "Add the time to my statusline." * "What CLI settings can I change?" -Because the CLI hot-reloads the settings file, changes the agent makes apply immediately. To learn about the other built-in skills, see [bundled skills in the {VARS.WARP_CLI}](/cli/context/). +Because the CLI hot-reloads the settings file, changes the agent makes apply immediately. For the full list of built-in skills, see [Bundled skills](#bundled-skills). ## Themes @@ -82,7 +82,63 @@ Choose which items appear and in what order: Your choices are saved to the settings file, so the layout persists across sessions. +## Project context and rules + +The {VARS.WARP_CLI} gives its agent the same layered context system as the Warp app: your working directory, project rules, skills, and MCP servers, all scoped to the directory you're working in. + +Every conversation includes the session's current working directory as context. The {VARS.WARP_CLI} starts in the directory where you ran `warp`, and when you `cd` inside the session, project rules and skills re-scope to the new directory automatically. + +Within a project, the {VARS.WARP_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](/agent-platform/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 are discovered from these shared file locations, a repository that's already set up for agents in the Warp app (or other agent tools that read `AGENTS.md`) works in the {VARS.WARP_CLI} with no extra setup. + +## Skills + +[Skills](/agent-platform/capabilities/skills/) are reusable instruction sets the agent can invoke to perform specific tasks. The {VARS.WARP_CLI} discovers the same skills as the Warp app: project skills from your repository's skill directories (such as `.agents/skills/`) and personal skills from your home directory (such as `~/.agents/skills/`), scoped to your current working directory. + +To browse and invoke skills: + +1. Type `/skills` and press `Enter` to open the skills menu. The menu lists every skill in scope with its description; type to filter the list. +2. Use `↑` and `↓` to select a skill, then press `Enter`. The {VARS.WARP_CLI} inserts `/skill-name ` into the input so you can add extra instructions before running it. +3. Press `Enter` to invoke the skill. Any text after the skill name is passed along, either as [skill arguments](/agent-platform/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`. Matching skills appear in the slash command menu as you type. + +## Bundled skills + +The {VARS.WARP_CLI} ships with built-in skills that appear in the skills menu alongside your own: + +* **`/modify-settings`** - Updates {VARS.WARP_CLI} settings for you, using the bundled settings schema to find and edit the right key. See [Edit settings with the agent](#edit-settings-with-the-agent). +* **`/tui-migrate-setup`** - Sets up the {VARS.WARP_CLI} from an existing Warp app installation. The agent copies compatible settings and global MCP server definitions from the desktop app, and asks for your 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 because both surfaces discover them from the same locations. + +## MCP servers + +[MCP servers](/agent-platform/capabilities/mcp/) extend the agent with external tools and data sources. The {VARS.WARP_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](/agent-platform/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 {VARS.WARP_CLI} picks up changes automatically. Configured servers start automatically once you're logged in. + +:::note +The {VARS.WARP_CLI} reads MCP servers from its global config file only. Project-scoped MCP config files in repositories are not detected. To copy global server definitions from the Warp app, use the `/tui-migrate-setup` bundled skill. +::: + +### Managing servers with /mcp + +Type `/mcp` to open the MCP management view. The header shows the path to the config file the {VARS.WARP_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. Select a server with `↑` and `↓`, then press `Enter` to act on it: + +* **Offline servers** - Pressing `Enter` starts the server. +* **Running servers** - Pressing `Enter` stops the server. +* **Failed servers** - The row shows the failure message. Pressing `Enter` retries the server. +* **Servers awaiting authentication** - Pressing `Enter` reopens the OAuth authorization page in your browser. Servers with saved credentials show a **Log out** row that removes the stored OAuth credentials. + ## Related pages -* [{VARS.WARP_CLI} reference](/cli/reference/) for every command-line flag, slash command, and keyboard shortcut. -* [Agent context in the {VARS.WARP_CLI}](/cli/context/) for rules, skills, and MCP configuration. +* [Rules](/agent-platform/capabilities/rules/) - Full guide to project and global rules +* [Skills](/agent-platform/capabilities/skills/) - Authoring skills, skill arguments, and skill locations +* [MCP servers](/agent-platform/capabilities/mcp/) - Config format, server examples, and authentication +* [Codebase Context](/agent-platform/capabilities/codebase-context/) - Codebase indexing in the Warp app +* [{VARS.WARP_CLI} reference](/cli/reference/) - Command-line flags, slash commands, and keyboard shortcuts From 1ad48d8b413c45d3519632066d05cb4d75a17f90 Mon Sep 17 00:00:00 2001 From: Hong Yi Chen Date: Tue, 28 Jul 2026 15:06:29 -0700 Subject: [PATCH 4/8] docs(cli): rename Warp CLI to Warp Agent CLI in customization frontmatter Follows the site-wide WARP_CLI var update on the base branch; body prose picks up the new name via the var automatically. Co-Authored-By: Oz --- src/content/docs/cli/configuration.mdx | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/content/docs/cli/configuration.mdx b/src/content/docs/cli/configuration.mdx index e46873f9..9cfdbd0d 100644 --- a/src/content/docs/cli/configuration.mdx +++ b/src/content/docs/cli/configuration.mdx @@ -1,8 +1,8 @@ --- -title: "Customizing the Warp CLI" +title: "Customizing the Warp Agent CLI" description: >- - Customize the Warp CLI: settings file, themes, statusline, and agent context - with project rules, skills, and MCP servers. + Customize the Warp Agent CLI: settings file, themes, statusline, and agent + context with project rules, skills, and MCP servers. --- import { VARS } from '@data/vars'; From 6167a16a90f82fb4c235e3d37baeebd957bc3165 Mon Sep 17 00:00:00 2001 From: Hong Yi Chen Date: Wed, 29 Jul 2026 15:50:07 -0700 Subject: [PATCH 5/8] docs(cli): qualify settings hot reload for theme edits Address review on PR #401: settings values hot-reload from disk, but the rendered theme only re-applies via /theme or at the next startup, so the settings-file and agent-edit sections no longer promise immediate effect for theme changes. Also scope the Themes section's immediate-apply claim to /theme. Windows path verified to render with single backslashes in source and built HTML; no change needed. Co-Authored-By: Oz --- src/content/docs/cli/configuration.mdx | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/content/docs/cli/configuration.mdx b/src/content/docs/cli/configuration.mdx index 9cfdbd0d..04e76653 100644 --- a/src/content/docs/cli/configuration.mdx +++ b/src/content/docs/cli/configuration.mdx @@ -23,7 +23,7 @@ The file is created the first time you change a setting, and you can also create theme = "dark" ``` -The CLI watches the settings file while it's running, so edits take effect immediately without a restart. 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. +The CLI watches the settings file while it's running and reloads values as you save, so most edits take effect without a restart. The color theme is the exception: theme edits made directly in the file are applied when you run `/theme` or the next time the CLI starts. 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. :::note CLI settings are local to your machine and are never synced to the cloud. They are also independent from the Warp app's settings: the app and the CLI keep separate settings files, so changing one never affects the other. @@ -37,7 +37,7 @@ The fastest way to change a setting is to ask the agent in plain language. The C * "Add the time to my statusline." * "What CLI settings can I change?" -Because the CLI hot-reloads the settings file, changes the agent makes apply immediately. For the full list of built-in skills, see [Bundled skills](#bundled-skills). +Because the CLI hot-reloads the settings file, most changes the agent makes apply immediately. Theme changes are the exception: they take effect when you run `/theme` or restart the CLI. For the full list of built-in skills, see [Bundled skills](#bundled-skills). ## Themes @@ -47,7 +47,7 @@ The {VARS.WARP_CLI} renders with a light or dark color theme. Set it with the `/ * **`/theme light`** - Always uses the light theme. * **`/theme dark`** - Always uses the dark theme. -Theme changes apply immediately and persist across sessions as the `theme` key under `[appearance]` in the settings file. +Running `/theme` applies the change immediately and persists it across sessions as the `theme` key under `[appearance]` in the settings file. In auto mode, the CLI probes the host terminal's default colors when it starts and picks the theme that matches the background: light backgrounds get the light theme, and dark or undetectable backgrounds get the dark theme. Detection runs at startup, so if you switch your terminal's colors while the CLI is running, restart it or set a theme explicitly. From 9664b532dd70296eeaea98fa45a8b069a9503371 Mon Sep 17 00:00:00 2001 From: Hong Yi Chen Date: Wed, 29 Jul 2026 16:07:40 -0700 Subject: [PATCH 6/8] docs(cli): reduce product-name density on the customization page Editorial polish pass: after the intro's first mention, refer to the product as "the CLI" instead of repeating the full name in every section. The full name stays in the frontmatter, the intro, and the reference link. No structural, factual, heading, or link-target changes. Co-Authored-By: Oz --- src/content/docs/cli/configuration.mdx | 28 +++++++++++++------------- 1 file changed, 14 insertions(+), 14 deletions(-) diff --git a/src/content/docs/cli/configuration.mdx b/src/content/docs/cli/configuration.mdx index 04e76653..408dbf4d 100644 --- a/src/content/docs/cli/configuration.mdx +++ b/src/content/docs/cli/configuration.mdx @@ -41,7 +41,7 @@ Because the CLI hot-reloads the settings file, most changes the agent makes appl ## Themes -The {VARS.WARP_CLI} renders with a light or dark color theme. Set it with the `/theme` slash command: +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. This is the default. * **`/theme light`** - Always uses the light theme. @@ -84,49 +84,49 @@ Your choices are saved to the settings file, so the layout persists across sessi ## Project context and rules -The {VARS.WARP_CLI} gives its agent the same layered context system as the Warp app: your working directory, project rules, skills, and MCP servers, all scoped to the directory you're working in. +The CLI gives its agent the same layered context system as the Warp app: your working directory, project rules, skills, and MCP servers, all scoped to the directory you're working in. -Every conversation includes the session's current working directory as context. The {VARS.WARP_CLI} starts in the directory where you ran `warp`, and when you `cd` inside the session, project rules and skills re-scope to the new directory automatically. +Every conversation includes the session's current working directory as context. The CLI starts in the directory where you ran `warp`, and when you `cd` inside the session, project rules and skills re-scope to the new directory automatically. -Within a project, the {VARS.WARP_CLI} picks up the same rule files as the Warp app: +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](/agent-platform/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 are discovered from these shared file locations, a repository that's already set up for agents in the Warp app (or other agent tools that read `AGENTS.md`) works in the {VARS.WARP_CLI} with no extra setup. +Because rules and skills are discovered from these shared file locations, a repository that's already set up for agents in the Warp app (or other agent tools that read `AGENTS.md`) works in the CLI with no extra setup. ## Skills -[Skills](/agent-platform/capabilities/skills/) are reusable instruction sets the agent can invoke to perform specific tasks. The {VARS.WARP_CLI} discovers the same skills as the Warp app: project skills from your repository's skill directories (such as `.agents/skills/`) and personal skills from your home directory (such as `~/.agents/skills/`), scoped to your current working directory. +[Skills](/agent-platform/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 from your repository's skill directories (such as `.agents/skills/`) and personal skills from your home directory (such as `~/.agents/skills/`), scoped to your current working directory. To browse and invoke skills: 1. Type `/skills` and press `Enter` to open the skills menu. The menu lists every skill in scope with its description; type to filter the list. -2. Use `↑` and `↓` to select a skill, then press `Enter`. The {VARS.WARP_CLI} inserts `/skill-name ` into the input so you can add extra instructions before running it. +2. Use `↑` and `↓` to select a skill, then press `Enter`. The CLI inserts `/skill-name ` into the input so you can add extra instructions before running it. 3. Press `Enter` to invoke the skill. Any text after the skill name is passed along, either as [skill arguments](/agent-platform/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`. Matching skills appear in the slash command menu as you type. ## Bundled skills -The {VARS.WARP_CLI} ships with built-in skills that appear in the skills menu alongside your own: +The CLI ships with built-in skills that appear in the skills menu alongside your own: -* **`/modify-settings`** - Updates {VARS.WARP_CLI} settings for you, using the bundled settings schema to find and edit the right key. See [Edit settings with the agent](#edit-settings-with-the-agent). -* **`/tui-migrate-setup`** - Sets up the {VARS.WARP_CLI} from an existing Warp app installation. The agent copies compatible settings and global MCP server definitions from the desktop app, and asks for your 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 because both surfaces discover them from the same locations. +* **`/modify-settings`** - Updates CLI settings for you, using the bundled settings schema to find and edit the right key. See [Edit settings with the agent](#edit-settings-with-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 desktop app, and asks for your 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 because both surfaces discover them from the same locations. ## MCP servers -[MCP servers](/agent-platform/capabilities/mcp/) extend the agent with external tools and data sources. The {VARS.WARP_CLI} keeps its own MCP server configuration, separate from the Warp app's, so each can run its own set of servers. +[MCP servers](/agent-platform/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](/agent-platform/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 {VARS.WARP_CLI} picks up changes automatically. Configured servers start automatically once you're logged in. +Servers are defined in a JSON config file using the same `mcpServers` format as [file-based MCP servers](/agent-platform/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. :::note -The {VARS.WARP_CLI} reads MCP servers from its global config file only. Project-scoped MCP config files in repositories are not detected. To copy global server definitions from the Warp app, use the `/tui-migrate-setup` bundled skill. +The CLI reads MCP servers from its global config file only. Project-scoped MCP config files in repositories are not detected. To copy global server definitions from the Warp app, use the `/tui-migrate-setup` bundled skill. ::: ### Managing servers with /mcp -Type `/mcp` to open the MCP management view. The header shows the path to the config file the {VARS.WARP_CLI} is reading. +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. Select a server with `↑` and `↓`, then press `Enter` to act on it: From 15ac1d16051d5333f49803c4b61ead10fb68d026 Mon Sep 17 00:00:00 2001 From: Hong Yi Chen Date: Wed, 29 Jul 2026 16:25:53 -0700 Subject: [PATCH 7/8] docs(cli): trim obvious menu-mechanics narration Per editorial direction: collapse the skills-menu step list into the non-obvious behaviors (selection inserts /skill-name for editing, argument passing, direct invocation) and drop the arrow-select narration in the /mcp view. Keep the statusline config steps since its keys are surprising (Esc saves, arrows reorder). No headings, facts, or link targets changed. Co-Authored-By: Oz --- src/content/docs/cli/configuration.mdx | 10 ++-------- 1 file changed, 2 insertions(+), 8 deletions(-) diff --git a/src/content/docs/cli/configuration.mdx b/src/content/docs/cli/configuration.mdx index 408dbf4d..b6d19e31 100644 --- a/src/content/docs/cli/configuration.mdx +++ b/src/content/docs/cli/configuration.mdx @@ -99,13 +99,7 @@ Because rules and skills are discovered from these shared file locations, a repo [Skills](/agent-platform/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 from your repository's skill directories (such as `.agents/skills/`) and personal skills from your home directory (such as `~/.agents/skills/`), scoped to your current working directory. -To browse and invoke skills: - -1. Type `/skills` and press `Enter` to open the skills menu. The menu lists every skill in scope with its description; type to filter the list. -2. Use `↑` and `↓` to select a skill, then press `Enter`. The CLI inserts `/skill-name ` into the input so you can add extra instructions before running it. -3. Press `Enter` to invoke the skill. Any text after the skill name is passed along, either as [skill arguments](/agent-platform/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`. Matching skills appear in the slash command menu as you type. +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](/agent-platform/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 @@ -128,7 +122,7 @@ The CLI reads MCP servers from its global config file only. Project-scoped MCP c 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. Select a server with `↑` and `↓`, then press `Enter` to act on it: +Each configured server is listed with its transport (`stdio` or `HTTP/SSE`) and current status, including the number of tools a running server exposes: * **Offline servers** - Pressing `Enter` starts the server. * **Running servers** - Pressing `Enter` stops the server. From 0cc22af06b5140061a85cf549ac4dd9e2a735223 Mon Sep 17 00:00:00 2001 From: Hong Yi Chen Date: Wed, 29 Jul 2026 16:38:31 -0700 Subject: [PATCH 8/8] docs(cli): compress statusline catalog and tighten context and /mcp prose Apply orchestrator audit: keep only statusline items with non-obvious behavior as bullets and fold the self-explanatory ones into one sentence, shorten the working-directory context paragraph, and replace the four per-state /mcp bullets with two lines. Co-Authored-By: Oz --- src/content/docs/cli/configuration.mdx | 15 +++++---------- 1 file changed, 5 insertions(+), 10 deletions(-) diff --git a/src/content/docs/cli/configuration.mdx b/src/content/docs/cli/configuration.mdx index b6d19e31..a73d6c95 100644 --- a/src/content/docs/cli/configuration.mdx +++ b/src/content/docs/cli/configuration.mdx @@ -56,7 +56,6 @@ In auto mode, the CLI probes the host terminal's default colors when it starts a The statusline is the row below the CLI's input box that shows session information at a glance. By default it shows the active model, the working directory, and, inside a Git repository, the Git branch and diff status. You can enable any of these items: * **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** - How far the branch is ahead of or behind its upstream. * **Git diff status** - Uncommitted line additions and deletions. @@ -65,9 +64,8 @@ The statusline is the row below the CLI's input box that shows session informati * **Agent to-do list** - The agent's progress through its current task list. * **Auto-approve indicator** - Appears when auto-approve is on. * **Auto-queue next prompt indicator** - Appears when auto-queue is on. -* **Date** - The current date. -* **Time (12 hour format)** and **Time (24 hour format)** - The current time. -* **Voice input** - A control for starting voice input. + +You can also add the working directory, 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. @@ -86,7 +84,7 @@ Your choices are saved to the settings file, so the layout persists across sessi The CLI gives its agent the same layered context system as the Warp app: your working directory, project rules, skills, and MCP servers, all scoped to the directory you're working in. -Every conversation includes the session's current working directory as context. The CLI starts in the directory where you ran `warp`, and when you `cd` inside the session, project rules and skills re-scope to the new directory automatically. +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: @@ -122,12 +120,9 @@ The CLI reads MCP servers from its global config file only. Project-scoped MCP c 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: +Each configured server is listed with its transport (`stdio` or `HTTP/SSE`) and current status, including the number of tools a running server exposes. -* **Offline servers** - Pressing `Enter` starts the server. -* **Running servers** - Pressing `Enter` stops the server. -* **Failed servers** - The row shows the failure message. Pressing `Enter` retries the server. -* **Servers awaiting authentication** - Pressing `Enter` reopens the OAuth authorization page in your browser. Servers with saved credentials show a **Log out** row that removes the stored OAuth credentials. +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