docs(cli): customization (settings, themes, statusline, rules, skills, MCP) - #401
docs(cli): customization (settings, themes, statusline, rules, skills, MCP)#401hongyi-chen wants to merge 5 commits into
Conversation
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 <oz-agent@warp.dev>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
|
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 Powered by Oz |
![oz-for-oss[bot]](https://avatars.githubusercontent.com/in/3450139?s=60&v=4){kind=small}
There was a problem hiding this comment.
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
/themeand 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
| 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. |
There was a problem hiding this comment.
/theme or at startup, so qualify the hot-reload behavior.
| * "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/). |
There was a problem hiding this comment.
appearance.theme are still settings-file edits and won't re-render the theme until /theme runs or the CLI restarts.
|
|
||
| * **macOS** - `~/.warp_cli/settings.toml` | ||
| * **Linux** - `~/.config/warp-terminal/cli/settings.toml` (respects `$XDG_CONFIG_HOME`) | ||
| * **Windows** - `%LOCALAPPDATA%\warp\Warp\config\cli\settings.toml` |
There was a problem hiding this comment.
💡 [SUGGESTION] Inline code renders backslashes literally, so this currently displays doubled separators. Use single Windows separators in the path.
| * **Windows** - `%LOCALAPPDATA%\warp\Warp\config\cli\settings.toml` | |
| * **Windows** - `%LOCALAPPDATA%\warp\Warp\config\cli\settings.toml` |
{{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 <oz-agent@warp.dev>
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 <oz-agent@warp.dev>
hongyi-chen
changed the title
…cli-cli-configuration
…tter 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 <oz-agent@warp.dev>
1 participant
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.mdxitself is deleted at integration, and the slug rename tocustomizationhappens 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
~/.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)./theme auto|light|dark, immediate apply + persistence asappearance.theme, terminal background detection at startup (light → light; dark/undetectable → dark)./statuslineconfig flow (Enter toggle, arrow-key reorder, Esc save, Ctrl+C cancel).cdre-scopes rules and skills;AGENTS.md/WARP.mdproject rules; global~/.agents/AGENTS.mdrules; cross-links agent-platform/capabilities/rules./skillsmenu (search, select, insert/skill-namefor extra instructions), direct/skill-nameinvocation with arguments; cross-links agent-platform/capabilities/skills./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)./mcpmanagement view (transport, status, tool counts; start/stop/retry; OAuth reopen + log out), CLI-specific global.mcp.jsonconfig (samemcpServersformat, auto-reloaded, servers auto-start after login); cross-links agent-platform/capabilities/mcp.Dropped/unconfirmed
keybindings.yamlis 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(documented that way).Validation
npm run buildpasses (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