docs(cli): permissions and profiles - #404
Merged
Merged
Conversation
Replace the cli/permissions-and-profiles.mdx stub with full content: permission request cards (yes/no/Other), command editing with E and Esc behavior, inline diff approval, /auto-approve (slash command, Ctrl+Shift+I, progress-row control, statusline indicator), and settings-file execution profiles under agents.execution_profiles with the CLI's agent_decides default for shell commands. Dropped from the outline after verifying against warp master: /fast-forward and fast-forward mode (no such slash command or TUI surface) and --dangerously-skip-permissions (flag does not exist on the warp binary). Co-Authored-By: Oz <oz-agent@warp.dev>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
Contributor
|
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}
Contributor
There was a problem hiding this comment.
Overview
This PR replaces the CLI permissions stub with a full page covering permission cards, auto-approve, and settings-file execution profiles. The overall structure is appropriate, and no approved spec context was available to compare against.
Concerns
- The execution profile TOML example can weaken command-approval protections if copied because it replaces the built-in command denylist with only two entries.
Security
- The sample
command_denylistshould not imply thatrmandcurlare sufficient denylist coverage; users need to preserve or intentionally extend the default denylist.
Verdict
Found: 0 critical, 1 important, 0 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
| apply_code_diffs = "agent_decides" | ||
| read_files = "agent_decides" | ||
| command_allowlist = ['cargo (build|check|test)(\s.*)?'] | ||
| command_denylist = ['rm(\s.*)?', 'curl(\s.*)?'] |
Contributor
There was a problem hiding this comment.
rm and curl if copied into settings.toml, dropping default prompts for shells, ssh, wget, and other risky commands. Omit this field from the minimal example or explicitly tell readers to preserve/extend the generated default denylist.
Collaborator
Author
There was a problem hiding this comment.
Fixed in 1557266. Removed command_denylist from the minimal example and added a caution: omitting the field keeps the built-in default denylist, while setting it replaces the defaults entirely (verified against the settings deserialization on master: omitted fields fall back to the built-in profile defaults, and a set list is used as-is with no merging), so readers are told to extend the generated list in settings.toml instead of writing a short list from scratch.
The vars transform does not apply to frontmatter parsed by Astro's content
layer, so {{WARP_CLI}} tokens rendered literally in built titles. Replace
them with the literal product name; body prose keeps {VARS.WARP_CLI}.
Co-Authored-By: Oz <oz-agent@warp.dev>
…cli-cli-permissions
Update the literal product name in the title and description to the confirmed launch name. Body prose renders the new name via the merged WARP_CLI var value. Co-Authored-By: Oz <oz-agent@warp.dev>
4 tasks
Remove command_denylist from the minimal execution-profile example: a copied short list would replace the built-in default denylist and drop prompts for other risky commands. Add a caution explaining that omitting the field keeps the defaults and setting it replaces them, so users should extend the generated list instead. Addresses PR #404 review comment 3669356200. Co-Authored-By: Oz <oz-agent@warp.dev>
Use "the CLI" after the intro's first full product-name mention, keeping the full name where the contrast with the Warp app matters and in page title link text. Fold two trailing "See [X]." sentences into their preceding sentences. Co-Authored-By: Oz <oz-agent@warp.dev>
Cut self-evident selector mechanics (Enter to confirm, Esc to reject), output-streaming and diff-header narration, and the slash-menu state sentence. Keep the non-obvious behaviors: Other for replacement guidance, E to edit commands and toggle diffs, the Esc-while-editing gotcha, and all defaults and cautions. Co-Authored-By: Oz <oz-agent@warp.dev>
hongyi-chen
commented
Jul 29, 2026
|
|
||
| When the agent asks "Is it OK if I make these file edits?", the card shows the proposed diffs inline, with one section per file: | ||
|
|
||
| * Each file header shows the change type, the file name, and added/removed line counts. Multi-file edits are grouped under a summary header, and all diffs start expanded while the request is pending. |
Collaborator
Author
There was a problem hiding this comment.
this does not feel necessary to include to an end user
Collaborator
Author
There was a problem hiding this comment.
Fixed in d6bd6e1. Deleted the progress-row control bullet and folded the remaining toggles into one sentence (/auto-approve or Ctrl+Shift+I).
hongyi-chen
commented
Jul 29, 2026
| ## Approving agent actions | ||
|
|
||
| {/* TODO(cli-permissions): permission request cards, command edit/escape behavior, diff approval. */} | ||
| When an action needs your approval, the CLI pauses the conversation and shows a permission card in the transcript: what the agent wants to do, the details (the exact command, the file diffs, or the tool call), and a **yes**/**no** selector. Select **Other** to type a reply instead; the agent receives your guidance in place of the proposed action, which is useful when you want it to take a different approach. |
Collaborator
Author
There was a problem hiding this comment.
this feels like too much to explain to a user, you're basically just describing the UI in plain words at this point
Collaborator
Author
There was a problem hiding this comment.
Fixed in d6bd6e1. Cut the card-anatomy walkthrough; the section now leads with one sentence and lists only the non-obvious actions (Other, E shortcuts, Esc-while-editing).
hongyi-chen
commented
Jul 29, 2026
| {/* TODO(cli-permissions): permission request cards, command edit/escape behavior, diff approval. */} | ||
| When an action needs your approval, the CLI pauses the conversation and shows a permission card in the transcript: what the agent wants to do, the details (the exact command, the file diffs, or the tool call), and a **yes**/**no** selector. Select **Other** to type a reply instead; the agent receives your guidance in place of the proposed action, which is useful when you want it to take a different approach. | ||
|
|
||
| ### Reviewing commands |
Collaborator
Author
There was a problem hiding this comment.
this also feels like describing UI rather than anything novel to the user, can we simplify or combine with another section?
Collaborator
Author
There was a problem hiding this comment.
Fixed in d6bd6e1. Merged Reviewing commands (and Reviewing file edits) into Approving agent actions; each is now a single bullet keeping only the E shortcut and the Esc-while-editing gotcha. No other pages linked to the removed anchors.
Merge the Reviewing commands and Reviewing file edits subsections into Approving agent actions, keeping only the non-obvious behaviors (Other as replacement guidance, E shortcuts, Esc-while-editing). Drop the card anatomy description, the quoted card questions, and the progress-row auto-approve control bullet; fold the remaining toggles into a sentence. Addresses PR #404 comments 3678712189, 3678714624, 3678709662. Co-Authored-By: Oz <oz-agent@warp.dev>
harryalbert
approved these changes
Jul 30, 2026
harryalbert
left a comment
harryalbert
left a comment
Contributor
There was a problem hiding this comment.
nice! Just had a few additions for functionality that was merged recently (last night lol)
| {/* TODO(cli-permissions): draft per drafts/warp-cli-launch-plan.md — "cli/permissions-and-profiles.mdx" section. Feature-doc content type. */} | ||
|
|
||
| The {VARS.WARP_CLI} documentation for this page is in progress. | ||
| The {VARS.WARP_CLI} uses the same permission model as the Warp app: the agent acts on its own when it's confident an action is safe, and asks for your approval when it isn't. This page covers how permission requests appear in the CLI and how to tune the agent's autonomy with auto-approve and execution profiles. For the full permission model, including autonomy levels and organization-wide controls, see [Profiles & Permissions](/agent-platform/capabilities/agent-profiles-permissions/). |
Contributor
There was a problem hiding this comment.
I feel like this isn't quite the right summary of our permissions model, and makes it sound more unsafe than it is. Like you can set the permissions to agent_decides so that the agent will decide on how safe an action is, but you could also require every single action to get approval or make it so no actions need approval
Collaborator
Author
There was a problem hiding this comment.
Fixed in fe8e58d. Reframed the intro and "How permissions work" around per-action-type configuration rather than implying the agent always self-judges safety: each action type is set independently to always_ask, always_allow, or agent_decides, and the section now explicitly calls out that you can set everything to always_ask to review every action or always_allow for an agent that never stops to ask. The CLI-specific defaults (agent_decides for commands/edits/reads/MCP, always_ask for write_to_pty and run_agents, verified against AIExecutionProfile::default_profile_for_tui) are now described as defaults rather than as the model itself.
| ## Auto-approve | ||
|
|
||
| {/* TODO(cli-permissions): /auto-approve toggle and when to use it. */} | ||
| Auto-approve gives the agent full autonomy for the current conversation: 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`. |
Contributor
There was a problem hiding this comment.
this probably wasn't merged when you wrote these docs (I merged last night), but you can also now run the TUI w/ the --fast-forward flag (so like warp --fast-forward) to auto-enable fast forward for all new conversations. This is like the claude code --dangerously-skip-permissions flag
Collaborator
Author
There was a problem hiding this comment.
Added in fe8e58d. One naming note: the flag as merged is --auto-approve, not --fast-forward — warpdotdev/warp#14483 ("Add --auto-approve to Warp Agent CLI"), TuiArgs::auto_approve in crates/warp_tui/src/session.rs. So the page documents warp --auto-approve, which also keeps it consistent with /auto-approve and Ctrl+Shift+I on the same page.
The Auto-approve section now reads: toggle with /auto-approve or Ctrl+Shift+I, or launch with warp --auto-approve to start every new conversation in that session with it already on. I also corrected the follow-on sentence — new conversations start with auto-approve off unless you launched with the flag, since TuiConversationSelection applies the launch default to each new conversation even after you toggle one off.
Heads up that --auto-approve also needs to land in the flags table on cli/reference.mdx; that page is a stub owned by a separate PR on this stack, so I left it alone here.
|
|
||
| {/* TODO(cli-permissions): fast-forward mode and /fast-forward toggle. */} | ||
| :::caution | ||
| With auto-approve on, the agent executes commands and applies file edits without review. Commands matching your command denylist still require approval, but everything else runs immediately. Press `Ctrl+C` to stop the agent if it starts doing something you didn't intend. |
Contributor
There was a problem hiding this comment.
The "commands matching your command denylist still require approval" actually isn't true anymore. There's a new setting that you can flip to change it so that denylisted commands do require approval even when fast forward is on (auto_approve_bypasses_command_denylist), but this setting defaults to on (i.e. fast forward bypasses the command denylist). The one exception is that workspace level denylisted commands still require approval no matter what
Collaborator
Author
There was a problem hiding this comment.
Fixed in fe8e58d. Confirmed against can_autoexecute_command in app/src/ai/blocklist/permissions.rs and the setting definition in app/src/settings/ai.rs (auto_approve_bypasses_command_denylist, default: true, surfaced on all surfaces): with auto-approve on, the user denylist is bypassed and only get_org_execute_commands_denylist is enforced.
The caution is now a :::danger and says auto-approve runs denylisted commands by default, shows how to turn the bypass off:
[agents.warp_agent.other]
auto_approve_bypasses_command_denylist = false...and notes that team-enforced denylist rules from the Admin Panel always require approval regardless of the setting. I also updated the command_denylist bullet in the profile-fields list, which previously claimed the denylist applies "regardless of other settings."
One downstream thing this surfaces: the GUI page at agent-platform/capabilities/agent-profiles-permissions.mdx still has two statements that are now stale — line 60 ("any denylist rules will still override these settings") and the caution at line 39. Line 144 ("Run until completion ignores the denylist entirely") is now the accurate one. Happy to fix that page in a follow-up PR since it's outside this branch's scope; let me know if you'd rather I fold it in here.
… behavior Addresses review feedback on the CLI permissions page: - Reframe the intro and "How permissions work" around per-action-type configuration (always_ask / always_allow / agent_decides) instead of implying the agent always self-judges safety. - Document the new `warp --auto-approve` launch flag (warpdotdev/warp#14483), which starts every new conversation in the session with auto-approve on. - Correct the auto-approve caution: `auto_approve_bypasses_command_denylist` defaults to true, so auto-approve bypasses the user command denylist unless it's turned off. Team-enforced denylist rules are never bypassed. Co-Authored-By: Oz <oz-agent@warp.dev>
Editorial pass, no factual changes: - The three permission values were defined inline in "How permissions work" and again under "Permission values", then restated a third time. Keep the definitions in the reference section and link to them from the overview. - Lift the denylist bypass config out of the :::danger callout into body prose so the callout is a warning rather than a mini-procedure. - Split the auto-approve toggles from the --auto-approve launch flag and state the per-conversation scope once instead of twice. Co-Authored-By: Oz <oz-agent@warp.dev>
hongyi-chen
added a commit
that referenced
this pull request
Aug 4, 2026
* Add Warp CLI launch docs skeleton and internal plan - New 'Warp CLI' sidebar topic with 13 stub pages under src/content/docs/cli/ - drafts/warp-cli-launch-plan.md: internal feature->page->reviewer analysis - New WARP_CLI content var (distinct from WARP_AGENT_CLI, reserved for the Oz CLI rename) Co-Authored-By: Oz <oz-agent@warp.dev> * Rename product to Warp Agent CLI - WARP_CLI var value -> "Warp Agent CLI" (body prose updates site-wide) - Sidebar topic label updated - Frontmatter literals fixed in the four stubs pending deletion - drafts doc: naming confirmed; WARP_AGENT_CLI key collision flagged Co-Authored-By: Oz <oz-agent@warp.dev> * docs(cli): models and usage + reference with troubleshooting (#405) * docs(cli): draft reference, models & usage, and troubleshooting pages Fill in the three cli-reference pages from the Warp CLI launch skeleton: - cli/reference: command-line flags with examples, environment variables, full slash-command table (25 commands verified against the CLI command registry), and default keyboard shortcuts sourced from the CLI keybinding definitions. - cli/models-and-usage: /model picker and footer model entry, BYOK via /add-api-key + provider flags (OpenAI/Anthropic/Google), custom model routers in the picker, and cost transparency (footer credits toggle, /cost per-response summary). - cli/troubleshooting: /view-logs bundling and log locations, login troubleshooting, autoupdate behavior with /version and --version, and support links. Co-Authored-By: Oz <oz-agent@warp.dev> * docs(cli): use literal Warp CLI in frontmatter title/description Frontmatter {{WARP_CLI}} tokens are not substituted by the build (Astro's content layer parses frontmatter outside Vite), so built titles showed the raw token. Body prose keeps {VARS.WARP_CLI}. Co-Authored-By: Oz <oz-agent@warp.dev> * docs(cli): fold troubleshooting into the reference page Consolidation: the standalone troubleshooting page merges into cli/reference.mdx as a final Troubleshooting section with problem-oriented H3 subsections. Existing H2 anchors (#slash-commands, #keyboard-shortcuts) are unchanged; internal links now point at #updating and #command-line-flags. troubleshooting.mdx is restored to the base-branch stub (the orchestrator removes it at integration). Co-Authored-By: Oz <oz-agent@warp.dev> * docs(cli): rename literal Warp CLI to Warp Agent CLI in frontmatter Follows the base-branch WARP_CLI var value change; body prose picks up the new name automatically via {VARS.WARP_CLI}. Co-Authored-By: Oz <oz-agent@warp.dev> * docs(cli): security fixes for API key examples Address review feedback: - Make WARP_API_KEY=... warp the primary non-interactive auth example and document --api-key secondarily with a caution that command-line arguments can be captured in shell history and process listings. - Replace the persistent key.txt stdin example with a tool-agnostic secret-manager pipe and a note against staging keys in plaintext files. Co-Authored-By: Oz <oz-agent@warp.dev> * docs(cli): editorial polish pass Reduce product-name density after each page's intro (prefer "the CLI"), vary repeated trailing "See [X]" sentences, and fold two cross-links into their sentences. No structural, factual, heading, or link-target changes. Co-Authored-By: Oz <oz-agent@warp.dev> * docs(cli): trim menu-mechanics narration Cut the type-to-filter/arrows/Enter sentence from the model picker prose and the keep-typing-to-filter clause from the slash-command intro, per the editorial bar against narrating self-evident UI mechanics. Defaults, exceptions, and lookup tables are unchanged. Co-Authored-By: Oz <oz-agent@warp.dev> * docs(cli): note macOS Option-as-Alt requirement for Alt shortcuts Platform audit: every keybinding registration is identical on macOS and Linux (the only platform-conditional binding is a Windows-only Alt+V paste, which is not documented since no Windows build ships). Input arrives as terminal key events, so Alt shortcuts depend on the host terminal delivering Option as Alt on macOS; add one note to the keyboard shortcuts section instead of per-row annotations. Co-Authored-By: Oz <oz-agent@warp.dev> * docs(cli): tighten disabled-models sentence in model picker prose Co-Authored-By: Oz <oz-agent@warp.dev> * docs(cli): update API key docs for /api-keys menu and --auto-approve flag Address review feedback on the API key flow change (warpdotdev/warp#14472), which replaced /add-api-key and /clear-provider-api-key with a single inline /api-keys menu: - models-and-usage: rewrite the BYOK section around the /api-keys menu — set/replace/clear provider keys with masked entry, connect or disconnect X Premium/SuperGrok via browser sign-in, and toggle Warp credit fallback. The --set-provider-api-key/--clear-provider-api-key flags stay documented for scripting (they remain supported per the CODE-1930 spec). - reference: swap the /add-api-key and /clear-provider-api-key slash-command rows for /api-keys, and point --set-provider-api-key at the in-session menu. - reference: document the new --auto-approve flag (warpdotdev/warp#14483), which starts new conversations in that launch with auto-approve enabled. Co-Authored-By: Oz <oz-agent@warp.dev> * docs(cli): editorial trim pass on API key and auto-approve additions Remove redundant clauses: drop the repeated launch-default sentence in --auto-approve, the doubled keys-over-credits statement in the fallback bullet, the repeated browser-sign-in rationale in the scripting paragraph, and tighten the /api-keys table row to match the terse row pattern. Co-Authored-By: Oz <oz-agent@warp.dev> --------- Co-authored-by: Oz <oz-agent@warp.dev> * docs(cli): permissions and profiles (#404) Replaces the `cli/permissions-and-profiles.mdx` stub with a full draft covering the permission model, permission cards, auto-approve, and settings-file execution profiles. Verified against `warp` master: - Per-action-type permission values and CLI defaults (`AIExecutionProfile::default_profile_for_tui`) - `warp --auto-approve` launch flag (warpdotdev/warp#14483) - `auto_approve_bypasses_command_denylist` defaults to true, so auto-approve bypasses the user command denylist; team-enforced Admin Panel rules are never bypassed (`can_autoexecute_command`) Follow-ups tracked, not included here: - `--auto-approve` needs adding to the flags table on `cli/reference.mdx` (separate stub PR on this stack) - `agent-platform/capabilities/agent-profiles-permissions.mdx` has two now-stale denylist statements given the new bypass default Reviewed by @harryalbert. Co-Authored-By: Oz <oz-agent@warp.dev> * docs(cli): cloud handoff and orchestration (#402) Replaces the cli/cloud-and-orchestration stub with the full draft: /handoff flow and guardrails, resuming cloud runs (browser-first), multi-agent orchestration approval card and permission, child-agent tab bar management, and Ctrl+C kill paths. Includes review feedback from harryalbert and a final editorial pass. Co-Authored-By: Oz <oz-agent@warp.dev> * docs(cli): agent conversations and conversation management (#399) * docs(cli): draft agent conversations page Covers the streaming transcript, Markdown/Mermaid rendering, tool-call rows, file-edit diffs, thinking blocks, interactive agent questions, task lists, /plan flow, and transcript selection/copy for the Warp CLI. Co-Authored-By: Oz <oz-agent@warp.dev> * docs(cli): use literal Warp CLI in frontmatter {{WARP_CLI}} tokens are not substituted in MDX frontmatter by the content layer, so built titles/descriptions showed the raw token. Body prose keeps {VARS.WARP_CLI}. Co-Authored-By: Oz <oz-agent@warp.dev> * docs(cli): absorb conversation management into agent conversations page Adds a Managing conversations section group (persistence/restore, /new /agent /clear, /conversations menu + left-arrow shortcut, /compact, exit summary + --resume) from the standalone conversations page, which is being removed in the consolidation. Updates the intro, description, and related pages accordingly. Co-Authored-By: Oz <oz-agent@warp.dev> * docs(cli): rename to Warp Agent CLI in frontmatter Follows the launch-name change; body prose picks up the new name via the WARP_CLI var from the base branch merge. Co-Authored-By: Oz <oz-agent@warp.dev> * docs(cli): editorial polish on agent conversations page Reduces product-name repetition after the intro, links bold lead terms in the tool-call list instead of trailing See-X sentences, swaps 'unfolds' for 'appears', fixes 'just', and de-metas the intro's managing-conversations pointer. No factual, heading, or link-target changes. Co-Authored-By: Oz <oz-agent@warp.dev> * docs(cli): trim self-evident UI narration per review Per PR review: cut transcript scrolling narration, collapse the markdown-features list to its non-obvious caveats (folding the H3), drop the tool-call glyph state-machine detail, and sweep the rest of the page with the same lens (menu how-tos, click-to-collapse, and double/triple-click narration removed). Feature facts, caveats, shortcuts, and cross-links are unchanged. Co-Authored-By: Oz <oz-agent@warp.dev> * docs(cli): apply editorial audit cuts Seven targeted trims: intro filler sentence, diff-header bullet detail, multi-question tail, bold header adjective, copy-confirmation footer mention, managing-conversations enumeration, and history restore phrasing. Co-Authored-By: Oz <oz-agent@warp.dev> * docs(cli): address review feedback on agent conversations - Trim styling narration from the transcript intro (prompt row marker, elapsed-time progress indicator) that would go stale with small UI changes; keep the durable behavior (streaming, Ctrl+C to stop). - Color the task-list status glyphs to match the TUI: yellow in-progress dot and green completed check, via mode-aware Starlight hue tokens so they stay legible in dark and light mode. - Lead "Resuming conversations" with the conversation menu, the primary way to resume in the CLI, and note type-to-filter in the menu. Co-Authored-By: Oz <oz-agent@warp.dev> * docs(cli): editorial pass for redundancy and flow - Collapse three separate "restores the full transcript" statements into one, in Conversation persistence, where the detail belongs. - Replace the duplicated "saved automatically" claim with the account vs. local-machine distinction, which sets up the menu contents and the offline caution that follow. - Move Resuming conversations next to Conversation history so the two cross-referencing sections are adjacent instead of split by Compacting context. - Point the intro's resume link at #resuming-conversations directly, and fix a dangling modifier in the tool-call description. Co-Authored-By: Oz <oz-agent@warp.dev> --------- Co-authored-by: Oz <oz-agent@warp.dev> * docs(cli): remove orphaned conversations stub, repoint its links (#423) PR #397 (hyc/launch-cli-cli-conversations) was closed unmerged when #399 absorbed its content into cli/agent-conversations.mdx, but the stub it was meant to fill survived on the launch branch. The sidebar listed it as "Managing conversations" four lines below the real "Agent conversations" page, so the launch would have shipped a nav entry leading to a page that reads "documentation for this page is in progress". - Delete src/content/docs/cli/conversations.mdx. - Drop its sidebar entry in src/sidebar.ts. - Repoint the four inbound links from cloud-and-orchestration.mdx and reference.mdx to the corresponding anchors on cli/agent-conversations. No redirect needed: /cli/conversations has never been published (404 live, and src/content/docs/cli/ does not exist on main). Co-authored-by: Oz <oz-agent@warp.dev> * docs(cli): remove orphaned troubleshooting stub (#425) PR #405 consolidated troubleshooting into cli/reference.mdx (its Troubleshooting section) and reset cli/troubleshooting.mdx back to the skeleton stub, leaving the stub published in the sidebar with no sub-PR left to fill it. Remove the stub and its sidebar entry, matching the treatment #423 gives the conversations stub. No inbound links exist to /cli/troubleshooting/ (checked all merged and open cli sub-PR content), so no repoints are needed. Advances the 'delete 4 orphaned stubs' item on the #411 integration checklist. Validation: npm run build green; internal link check 0 broken. Co-authored-by: Oz <oz-agent@warp.dev> * docs(cli): customization (settings, themes, statusline, rules, skills, MCP) (#401) * 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 <oz-agent@warp.dev> * 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 <oz-agent@warp.dev> * 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 <oz-agent@warp.dev> * 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 <oz-agent@warp.dev> * 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 <oz-agent@warp.dev> * 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 <oz-agent@warp.dev> * 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 <oz-agent@warp.dev> * 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 <oz-agent@warp.dev> * docs(cli): re-verify statusline items against latest master Master's statusline catalog changed (moira's #14257/#14458): the auto-queue item was removed, and Vim mode indicator and GitHub pull request items were added. Auto-approve and Vim mode indicator are now on by default. Update the item list, defaults, and the auto-approve and git diff descriptions accordingly. Themes, settings paths, and the /statusline config flow re-verified against master and unchanged. Co-Authored-By: Oz <oz-agent@warp.dev> --------- Co-authored-by: Oz <oz-agent@warp.dev> * Post-merge coherence pass on cli docs - Remove orphaned context stub (content lives in configuration.mdx via #401) and its sidebar entry; repoint the reference page link - Fix stale auto-approve statusline claim in permissions page (the indicator is default-on since the statusline catalog update) Co-Authored-By: Oz <oz-agent@warp.dev> * docs: address review feedback on agent-conversations.mdx Applies suggested edits and resolves open questions from PR review: - Applies wording/phrasing suggestions from inline suggestion comments - Reworks the tool-call and code-diff bullet lists for consistent bold-term + dash + description formatting - Clarifies multi-file diff nesting based on TuiFileEditsView source - Clarifies the plan toggle shortcut per the CLI reference page (Ctrl+Shift+P expands/collapses the latest plan) - Reorders the copy/export paragraph before the clipboard note - Simplifies the /new, /agent, /clear list since the intro sentence already explains their behavior - Formats YOUR_CONVERSATION_TOKEN as inline code Co-Authored-By: Oz <oz-agent@warp.dev> * docs: address review feedback on cloud-and-orchestration.mdx Applies suggested edits and resolves open questions from PR review: - Applies wording/phrasing suggestions from inline suggestion comments - Rewords the intro to avoid the ambiguous "Oz Platform" phrase pending a vars.ts decision - Reworks the handoff steps and card-action bullets for consistent bold-term + dash + description formatting; moves the pre-confirm Ctrl+C cancel note to its correct chronological position - Clarifies the handoff card's model-preselection wording - Restructures 'Resume cloud conversations' into a clear two-option (browser / CLI) + constraints layout - Splits the dense orchestration-start paragraph and the tab-bar navigation bullet for scannability - Clarifies 'read-only status views' wording for cloud child sessions - Fixes non-em-dash usage flagged in the kill-agent paragraph - Adds a real screenshot of the Agents: tab bar, captured liv- Adds a real screenshot of the Agents: tab bar, captured liv- Adds a real screenshot of the Agents: tab bar, captured liv- Adds in warpdotdev/warp Co-Authored-By: Oz <oz-agent@warp.dev> * docs: address review feedback on models-and-usage.mdx - Applies suggestion comments: intro rewording, model-picker/profile wording, semicolon and colon cleanup, usage bullet rewording - Clarifies the ambiguous "footer" reference by naming and linking to the statusline section in configuration.mdx (applied consistently to both occurrences on the page) Co-Authored-By: Oz <oz-agent@warp.dev> * docs: fix statusline default-items accuracy and add screenshot Verified against warpdotdev/warp origin/master (crates/warp_tui/src/ terminal_session_view/statusline.rs, app/src/settings/ai.rs): - Adds the missing 'Working directory' bullet; it's a default item, not one you 'also add' - Clarifies that enabling Git branch status replaces the plain Git branch chip rather than adding a second one (should_render_plain_git_branch requires branch status disabled) - Adds a real screenshot of the statusline with credit usage, context window usage, and task-list chips enabled, captured live via the tui-verify-change skill in warpdotdev/warp Co-Authored-By: Oz <oz-agent@warp.dev> * docs: address review feedback on permissions-and-profiles.mdx and reference.mdx permissions-and-profiles.mdx: - Applies suggestion comments: description/intro trims, colon removal - Clarifies the vague "letting file reads through" example - Converts the dense default-permissions paragraph into a scannable bulleted list - Removes semicolons from the approval-card bullets and tightens wording - Links the settings-file bypass instructions to configuration.mdx reference.mdx: - Applies the intro suggestion, removing the mid-sentence colon Co-Authored-By: Oz <oz-agent@warp.dev> * docs: holistic style pass across Warp Agent CLI docs Applies the same rubric from earlier review rounds (unclear language, wordy passages, unnecessary UI detail, colons/semicolons) to the rest of the PR: - reference.mdx: fixes a grammar issue in the flags intro, removes mid-sentence colons/semicolons in the slash commands, keyboard shortcuts, and troubleshooting sections (only line 9 had been reviewed directly) - Re-scanned all previously-edited files (agent-conversations, cloud-and-orchestration, configuration, models-and-usage) for remaining semicolons joining independent clauses and split them into separate sentences for consistency index.mdx, quickstart.mdx, input-and-editing.mdx, and shell-commands.mdx are still TODO-only placeholder stubs (no drafted prose yet), so there was nothing to style-review there. Co-Authored-By: Oz <oz-agent@warp.dev> * docs: crop and highlight the CLI screenshots for clarity Both screenshots previously showed the full 120x40 terminal window, making it unclear which part was the actual subject. Cropped each to the relevant region and added a highlighted border around the exact row being documented: - tui-agents-tab-bar.png: cropped to the top strip (bar + one line of context below); highlighted the Agents: tab bar row - tui-statusline.png: cropped to the bottom strip (last transcript line, input box, statusline); highlighted the statusline row Co-Authored-By: Oz <oz-agent@warp.dev> * docs(cli): overview and quickstart (#398) * docs(cli): draft Warp CLI overview and quickstart pages Fill in cli/index.mdx (what the CLI is, key features, relationship to the Warp app and Oz, supported platforms, login/logout, automatic updates, migration from the Warp app, open source) and cli/quickstart.mdx (install placeholder, device-auth login, first prompt, shell command, exit and resume). Co-Authored-By: Oz <oz-agent@warp.dev> * docs(cli): use literal Warp CLI in frontmatter titles and descriptions Frontmatter {{WARP_CLI}} tokens are not substituted by the build pipeline, so built titles showed the raw token. Body prose keeps {VARS.WARP_CLI}. Co-Authored-By: Oz <oz-agent@warp.dev> * docs(cli): rename to Warp Agent CLI in frontmatter and intro Update literal frontmatter titles/descriptions for the confirmed launch name and rework the overview intro now that Warp Agent CLI is the primary name (positioning: the Warp Agent from the Warp app, in any terminal). Body {VARS.WARP_CLI} usages pick up the new name from the merged var change. Co-Authored-By: Oz <oz-agent@warp.dev> * docs(cli): address PR #398 review comments Add a visible interim note to the quickstart install section so it no longer renders empty alongside the pending-instructions comment, and make the WARP_API_KEY environment variable the primary non-interactive auth recommendation with a caution about --api-key appearing in shell history and process listings. Co-Authored-By: Oz <oz-agent@warp.dev> * docs(cli): editorial polish on overview and quickstart Link the bold feature names in the overview's key features list and drop the trailing See-X sentences, prefer "the CLI" over the full product name after first mention, and fold the trailing conversations link in the quickstart into its sentence. Co-Authored-By: Oz <oz-agent@warp.dev> * docs(cli): address owner review on overview page Remove named third-party terminals from the intro, reference the platform name through the content variable in body prose (heading and frontmatter keep the literal name), and drop the Open source section. Co-Authored-By: Oz <oz-agent@warp.dev> * docs(cli): trim narration of obvious mechanics from quickstart Cut the section-enumerating intro sentence, the press-Enter and output-appears step narration, and the placeholder restatement in the resume step. Overview page needed no cuts. Co-Authored-By: Oz <oz-agent@warp.dev> * docs(cli): correct Warp Drive claim to saved prompts only Verified against the Warp repo: the CLI's slash menu wires only the saved-prompts data source (plus static commands and skills); workflows, notebooks, and environment variables have no CLI surface. Co-Authored-By: Oz <oz-agent@warp.dev> * docs(cli): repoint links after context and conversations pages merged The context and conversations pages were consolidated on the base branch. Point the overview and quickstart links at their new homes: project context -> configuration#project-context-and-rules, and persistence/history -> agent-conversations sections. Merge the duplicate quickstart next-step into a single Configuration bullet. Co-Authored-By: Oz <oz-agent@warp.dev> * docs(cli): update overview and installation Co-Authored-By: Oz <oz-agent@warp.dev> * docs(cli): clarify zero-state customization Co-Authored-By: Oz <oz-agent@warp.dev> * docs(cli): fix renamed agent docs links Co-Authored-By: Oz <oz-agent@warp.dev> --------- Co-authored-by: Oz <oz-agent@warp.dev> Co-authored-by: Yunfan Yang <kevin@warp.dev> * docs(cli): input and shell commands (#406) * docs(cli): draft input and editing page Replace the cli/input-and-editing.mdx stub with full content covering editing basics, the slash command menu with argument hints, up-arrow prompt history, shell tab completions, mouse support, selection and clipboard behavior (incl. OSC 52 over SSH), image attachments, voice input, and the contextual keyboard hints plus the ? shortcuts menu. Dropped from the outline after verifying against warp master: Vim mode (not merged), inline-menu mouse clicks (not shipped), and configurable keybinding claims (the CLI does not load keybinding overrides yet). Co-Authored-By: Oz <oz-agent@warp.dev> * docs(cli): use literal Warp CLI in frontmatter {{WARP_CLI}} tokens are not substituted in MDX frontmatter (Astro's content layer parses frontmatter outside Vite), so the built title and description showed the raw token. Body-prose {VARS.WARP_CLI} is unchanged. Verified the built dist/cli/input-and-editing <title> now reads "Input and editing in the Warp CLI". Co-Authored-By: Oz <oz-agent@warp.dev> * docs(cli): absorb shell commands page into input page Consolidation: merge the verified content of cli/shell-commands.mdx (PR #403, branch hyc/launch-cli-cli-shell-commands) into cli/input-and-editing.mdx as a single "Input and shell commands in the Warp CLI" page. Adds shell mode, natural language detection, long-running and interactive commands, full-screen apps, and stopping/ exiting sections; merges the two history sections into one (adopting the verified submit-on-Enter semantics); rewires shell-mode links to in-page anchors. File rename to the new slug happens at integration. Co-Authored-By: Oz <oz-agent@warp.dev> * docs(cli): rename Warp CLI to Warp Agent CLI in frontmatter Launch name confirmed as Warp Agent CLI. Base branch merge picks up the WARP_CLI var change (e2aebe3) for body prose; this updates the two literal frontmatter strings (title, description). Verified the built title reads "Input and shell commands in the Warp Agent CLI". Co-Authored-By: Oz <oz-agent@warp.dev> * docs(cli): light editorial polish on input page Reduce product-name density (prefer "the CLI" after the intro; keep the full name in the intro and Related pages), drop one banned word ("just"), remove a filler wayfinding sentence from the intro, vary a repeated cross-reference rhythm, dedupe "lands in the input", and use a plainer verb for the hints section opener. No heading, fact, or link target changes. Co-Authored-By: Oz <oz-agent@warp.dev> * docs(cli): trim narration of obvious UI mechanics Per editorial direction: cut the slash-menu usage steps, the Submit and six-row-scroll narration in editing basics, the history Filter bullet, completion-menu Enter/Esc narration, cursor-click and scroll-wheel bullets, the attachment-bar arrow/Enter steps (kept Tab focus, Backspace remove, Esc return as one sentence), the "Speak your prompt" voice step, the duplicated long-running interrupt hint, type-and-press- Enter in shell mode, and the output-streams-in sentence. Kept non-obvious keys, defaults, and gotchas (submit-on-Enter history semantics, restore-on-dismiss, OSC 52 note). No heading changes. Co-Authored-By: Oz <oz-agent@warp.dev> * docs(cli): address review comments on NLD and interrupt hint Rename the natural-language-detection bullet lead from "Biased toward the agent" to "Ambiguous input" so it states the behavior without characterizing the classifier, and drop the interrupt-hint bullet from long-running commands (Ctrl+C interrupt is already covered in Stopping commands and exiting). Co-Authored-By: Oz <oz-agent@warp.dev> * docs(cli): apply orchestrator editorial audit Shorten the editing-basics intro, add the verified macOS/Linux Alt keybinding note, sharpen the history Submit/Dismiss bullets and drop the command-history sentence, fold the click-controls bullet into Selection and clipboard and remove the Mouse support section (no inbound #mouse-support links), trim the copied-to-clipboard footer narration, generalize the placeholder-hints bullet, simplify shell-mode step 2, and remove the transcript-styling sentence. Co-Authored-By: Oz <oz-agent@warp.dev> * docs(cli): repoint links to removed context and conversations pages The base branch merged context.mdx into configuration.mdx and folded the conversations page into agent-conversations.mdx. Repoint the skills link to /cli/configuration/#skills, and the two Managing conversations links to /cli/agent-conversations/#managing-conversations (verified both anchors exist in the merged base). Related pages now lists a single agent-conversations entry. Co-Authored-By: Oz <oz-agent@warp.dev> * docs(cli): clarify keyboard and voice support Co-Authored-By: Oz <oz-agent@warp.dev> * docs(cli): clarify Linux voice packaging Co-Authored-By: Oz <oz-agent@warp.dev> * docs(cli): fix renamed agent docs links Co-Authored-By: Oz <oz-agent@warp.dev> --------- Co-authored-by: Oz <oz-agent@warp.dev> Co-authored-by: Yunfan Yang <kevin@warp.dev> * docs(cli): final holistic pass before launch - Remove the leftover shell-commands stub; its content ships in the combined input page, now at cli/input-and-shell-commands (slug matches the title). Repoint all inbound links and update the sidebar entry. - Document start-screen customization (appearance.zero_state: object/ASCII art, rotation period, section toggles) on the customization page, and trim the overview's Key features bullet to match; keys verified in warp master. - Remove keybinding-customization claims (loading keybindings.yaml overrides in the CLI is still a follow-up per crates/warp_tui/src/keybindings.rs). - Cover Windows in the reference's platform bindings note (incl. the Windows-only Alt+V paste alias). - Apply the established style rubric (no semicolon-joined clauses or mid-sentence colon narration) to the three pages that merged after the style pass, plus two stragglers in the reference. - Dedupe the quickstart's natural-language-detection explanation and fix an 'Agent Mode' capitalization. - Add a Warp Agent CLI llms.txt custom set; delete the internal drafts/warp-cli-launch-plan.md planning doc so it doesn't ship to main. Co-Authored-By: Oz <oz-agent@warp.dev> * docs: keep local pricing drafts out of the launch branch Untracked local drafts were swept into the previous commit by git add -A; remove them from tracking (files remain on disk). Co-Authored-By: Oz <oz-agent@warp.dev> * docs(cli): fix TOC-visible VARS tokens in headings, shorten nav label Starlight's on-this-page TOC renders heading text without evaluating MDX expressions, so two headings showed a literal VARS.WARP_CLI token. Use the literal product name in headings. Also shorten the top-nav topic label from 'Warp Agent CLI' to 'Agent CLI'. Co-Authored-By: Oz <oz-agent@warp.dev> * docs(cli): use right-caret prompt chevron for the Agent CLI nav icon Co-Authored-By: Oz <oz-agent@warp.dev> --------- Co-authored-by: Oz <oz-agent@warp.dev> Co-authored-by: Rachael Rose Renk <91027132+rachaelrenk@users.noreply.github.com> Co-authored-by: Yunfan Yang <kevin@warp.dev>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Pages changed
src/content/docs/cli/permissions-and-profiles.mdx(stub replaced with full draft)Features covered
always_ask/always_allow/agent_decides), CLI defaults (agent_decidesfor commands/edits/reads/MCP,always_askforwrite_to_ptyandrun_agents, verified indefault_profile_for_tui), and the command denylist layered on topEto edit a proposed command (approving runs the edited version;Escexits the editor without cancelling),Eto expand/collapse all diffs/auto-approveslash command,Ctrl+Shift+Ibinding,warp --auto-approvelaunch flag, opt-in statusline indicator via/statusline, per-conversation scope, question-skipping interplay, denylist-bypass safety calloutagents.execution_profilesTOML table, reserveddefaultkey (the CLI always runs withdefault), field and value reference (snake_case values), allowlist/denylist regexes, whole-collection validation and fallback behavior, local-only (no cloud sync, separate from Warp app Agent Profiles)Dropped/unconfirmed
/fast-forwardslash command: no such command exists instatic_commands/commands.rs; the "▶▶" progress-row control is labeled "Auto approve" and the whole surface is documented under Auto-approve insteadcomputer_useprofile field: intentionally omitted from the field list because I could not confirm the computer-use tool is reachable from the CLI; happy to add if eng confirmsReview round 2 (@harryalbert)
always_askoralways_allow.warp --auto-approve([APP-4992] Add --auto-approve to Warp Agent CLI warp#14483). Note the merged flag is--auto-approve, not--fast-forward; seeTuiArgs::auto_approveincrates/warp_tui/src/session.rs. Also corrected the follow-on sentence: new conversations start with auto-approve off unless launched with the flag.auto_approve_bypasses_command_denylistdefaults totrue, so auto-approve runs denylisted commands; the page now shows how to set it tofalseand notes that team-enforced Admin Panel denylist rules are never bypassed. Thecommand_denylistfield bullet was updated to match.--auto-approvestill needs to land in the flags table oncli/reference.mdx, which is a stub owned by a separate PR on this stack.Notes for review
agent-platform/capabilities/agent-profiles-permissions.mdx: with the new bypass default, the caution at line 39 and the note at line 60 ("any denylist rules will still override these settings") are now stale, while line 144 ("Run until completion ignores the denylist entirely") is accurate. Happy to fix in a separate PR or fold it in here.{{WARP_CLI}}frontmatter tokens render literally in built page titles/descriptions. Thevars-transformVite plugin is registered, but Astro's content layer parses frontmatter outside Vite, so only body-prose{VARS.WARP_CLI}substitutes. Needs a fix onhyc/launch-cli(e.g. a remark plugin or frontmatter preprocessing).Validation:
npm run buildpasses (363 pages);style_lint --changedreports 0 issues.Suggested reviewer(s): harry
Co-Authored-By: Oz oz-agent@warp.dev