docs(cli): permissions and profiles - #404
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.
|
|
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 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.*)?'] |
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.
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>
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>
|
|
||
| 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. |
There was a problem hiding this comment.
this does not feel necessary to include to an end user
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).
| ## 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. |
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
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).
| {/* 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 |
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?
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>
1 participant
Pages changed
src/content/docs/cli/permissions-and-profiles.mdx(stub replaced with full draft)Features covered
Enterto run,Escto cancel, Other for replacement guidanceEto edit;Enter/Escexits the editor without cancelling the request; approving runs the edited command)Eexpand/collapse all, click headers to toggledefault_profile_for_tui); file edits prompt by default; denylist always prompts and takes precedence/auto-approve: slash command with current-state suffix,Ctrl+Shift+Ibinding, clickable "▶▶ Auto approve" control on the progress row, opt-in statusline indicator via/statusline, per-conversation scope, question-skipping interplay, safety cautionagents.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-forward+ fast-forward mode: no such slash command exists instatic_commands/commands.rsand no fast-forward surface exists in the TUI crate on master; the "▶▶" control is labeled "Auto approve" and is documented under Auto-approve instead--dangerously-skip-permissions: not present in thewarpbinary's CLI args on master (only--resume,--api-key,--set-provider-api-key,--clear-provider-api-key,--version,--help); Unattended use section removedcomputer_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 confirmsNotes for review
can_autoexecute_commandchecks the denylist before the run-to-completion override) but contradicts the older note on the GUI Profiles & Permissions page ("Run until completion ignores the denylist entirely"). Worth an eng sanity check, and possibly a follow-up fix to the GUI page.{{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).Suggested reviewer(s): harry
Co-Authored-By: Oz oz-agent@warp.dev