docs(cli): customization (settings, themes, statusline, rules, skills, MCP)

[hongyi-chen]

Drafts the Warp Agent CLI customization page for the CLI launch docs. As part of the 13→9 page consolidation, this page now also absorbs the content of the agent context page from PR #400 (that PR will be closed; context.mdx itself is deleted at integration, and the slug rename to customization happens at integration).

Pages changed

• src/content/docs/cli/configuration.mdx — retitled "Customizing the Warp Agent CLI"; covers CLI configuration plus agent context (rules, skills, MCP)

Features covered

• TOML settings file: per-platform locations verified in code (macOS ~/.warp_cli/settings.toml; Linux ~/.config/warp-terminal/cli/settings.toml, XDG-aware; Windows %LOCALAPPDATA%\warp\Warp\config\cli\settings.toml), example TOML, hot reload while running, invalid-value fallback to defaults, and the local-only story (never cloud-synced; fully separate from the Warp app's settings file).
• Edit settings with the agent: bundled skill + settings schema workflow, example prompts, in-page cross-link to bundled skills.
• Themes: /theme auto|light|dark, immediate apply + persistence as appearance.theme, terminal background detection at startup (light → light; dark/undetectable → dark).
• Statusline: full item catalog (14 items, labels matching the config panel), defaults (model, working directory, Git branch, Git diff status), conditional visibility and shell-mode label, and the /statusline config flow (Enter toggle, arrow-key reorder, Esc save, Ctrl+C cancel).
• Project context pickup (from docs(cli): context (rules, skills, MCP) #400): working-directory context; cd re-scopes rules and skills; AGENTS.md/WARP.md project rules; global ~/.agents/AGENTS.md rules; cross-links agent-platform/capabilities/rules.
• Skills (from docs(cli): context (rules, skills, MCP) #400): /skills menu (search, select, insert /skill-name for extra instructions), direct /skill-name invocation with arguments; cross-links agent-platform/capabilities/skills.
• Bundled skills (from docs(cli): context (rules, skills, MCP) #400, deduped): /modify-settings (canonical treatment lives in "Edit settings with the agent") and /tui-migrate-setup (migrate compatible settings + global MCP definitions from the Warp app; no credentials copied).
• MCP (from docs(cli): context (rules, skills, MCP) #400): /mcp management view (transport, status, tool counts; start/stop/retry; OAuth reopen + log out), CLI-specific global .mcp.json config (same mcpServers format, auto-reloaded, servers auto-start after login); cross-links agent-platform/capabilities/mcp.

Dropped/unconfirmed

• Keybinding customization: dropped. The CLI registers named bindings, but loading user overrides from keybindings.yaml is not wired in the CLI process (the loader only runs in the app's launch path); code comments mark override loading as a follow-up.
• Theme live refresh on external settings-file edits (CODE-1909): dropped as a claim. Settings values hot-reload from disk, but nothing re-applies the rendered theme on an external file edit; the theme applies immediately only via /theme (documented that way).
• Project-scoped MCP servers (carried from docs(cli): context (rules, skills, MCP) #400): not shipped in the CLI — MCP discovery is limited to the CLI's global config (project + third-party provider discovery is deferred in code). The page carries a note that only the global config file is read.
• MCP import/discovery from other tools (carried from docs(cli): context (rules, skills, MCP) #400): fast follow, not landed; excluded per plan.
• Note for integration review: the settings-file section lists Linux and Windows paths from code on master. If launch is macOS-only, trim those two bullets in the integration branch.

Validation

• npm run build passes (363 pages); built title renders as "Customizing the Warp Agent CLI | Warp".

Suggested reviewer(s): Kevin, moira

Co-Authored-By: Oz oz-agent@warp.dev

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
docs	Ready	Preview	Jul 31, 2026 11:08pm

[oz-for-oss]

@hongyi-chen

I'm starting a first review of this pull request.

You can view the conversation on Warp.

I completed the review and no human review was requested for this pull request.

Comment /oz-review on this pull request to retrigger a review (up to 3 times on the same pull request).

Powered by Oz

[oz-for-oss]

Overview

This PR expands src/content/docs/cli/configuration.mdx from a placeholder into a full CLI configuration page covering the TOML settings file, agent-assisted edits, themes, statusline customization, and related pages.

Concerns

• The page over-promises settings-file hot reload for theme changes made by editing the file or by asking the agent to edit the file; the current TUI applies rendered themes through /theme and startup, not generic settings-file reload.
• The Windows settings path currently renders with doubled backslash separators.

Verdict

Found: 0 critical, 2 important, 1 suggestions

Request changes

Comment /oz-review on this pull request to retrigger a review (up to 3 times on the same pull request).

Powered by Oz

[hongyi-chen]

Reviewed as part of a coherence pass across the hyc/launch-cli sub-PRs. All the falsifiable claims here verify against the client source — settings file locations and the MCP config path match tui_config_local_dir() / tui_mcp_config_file_path() in crates/warp_core/src/paths.rs exactly. A few mesh items:

Orphaned stub (the #423 pattern):

• This PR supersedes cli/context.mdx but leaves the stub, its sidebar entry ("Rules, skills, & MCP"), and inbound links in place: merged reference.mdx ("Context in the CLI" under Slash commands), plus docs(cli): overview and quickstart #398 (overview + quickstart) and docs(cli): input and shell commands #406 (skills mention). Either delete + repoint here (like docs(cli): remove orphaned conversations stub, repoint its links #423 / docs(cli): remove orphaned troubleshooting stub #425 do for the other stubs), or leave for the docs: Warp Agent CLI launch documentation #411 integration sweep — noting so it isn't missed either way.

Gap (worth fixing here):

• Merged reference.mdx §Updating ends with "turn off the autoupdate setting in the settings file; see configuration", and docs(cli): overview and quickstart #398's overview names general.autoupdate_enabled — but this page never documents that setting. A one-liner (e.g. under the settings-file section) would close the loop.

Accuracy nit:

• "The CLI watches the settings file … The color theme is the exception" — general.autoupdate_enabled is also read only once at startup (crates/warp_tui/src/autoupdate.rs: "read once here, at startup; toggling it takes effect on the next launch"), so the theme isn't the only exception. Suggest softening to "some settings, such as the theme and autoupdate, take effect on the next launch."

Cosmetic: sidebar label is still "Configuration" while the page is now "Customizing the Warp Agent CLI" — presumably resolved by the planned customization slug rename in the integration commit.