New to Kiro CLI V3? This page covers migration from CLI 2.x. If you're setting up permissions for the first time, start with the current permissions reference. Without a
permissions.yaml, Kiro allows workspace reads and common read-only commands, blocks writes to its own settings, and asks before other operations.
Kiro CLI V3 replaces persistent per-tool toolsSettings rules with structured permissions.yaml policies. The --trust-all-tools startup flag and /tools trust-all slash command grant session-wide trust. In non-interactive V3 runs, --trust-tools can pre-approve exact V3 tool IDs; the interactive V3 terminal UI ignores that flag. Use scoped permissions.yaml allow rules for reusable capability policies.
The core shift is from per-tool configuration to capability rules that apply consistently across every tool performing the same kind of operation.
| 2.x behavior | V3 behavior | Migration |
|---|---|---|
toolsSettings with per-tool allow and deny lists | Unified permissions.rules with capability, match, and effect | Rewrite using the toolsSettings migration table → |
autoAllowReadonly configured read-only shell approval | Read-only-shell policy generated by /upgrade-agent unless legacy denyByDefault also applies | Run /upgrade-agent, review the generated policy, and add shell allow rules for any additional commands you use |
denyByDefault blocked unlisted tool operations | Explicit deny rules, optionally with exclude exceptions | Use { capability: shell, exclude: ["git *", "npm *"], effect: deny } to deny everything except the excluded patterns |
| Regex patterns in permissions | Glob patterns only (no regex) | Rewrite .* as *, \.ts$ as *.ts, etc. |
? single-character wildcard for command patterns | Not supported for shell or URL patterns | Use * or spell out alternatives. File path patterns (fs_read, fs_write) still support ? |
| Read and write restrictions configured per tool | One capability rule applies to every tool that performs that operation | Account for the broader scope of fs_read, fs_write, and other capabilities |
| Per-tool denies evaluated independently | Deny always wins across all scopes | Remove conflicting allows or narrow the deny pattern |
These controls apply only to the current session:
# Trust every tool in a V3 session kiro-cli chat --v3 --trust-all-tools # In headless V3, trust exact tool IDs kiro-cli chat --v3 --no-interactive --trust-tools=read_file,grep_search "Review this repository" # In interactive V3, trust every tool after startup /tools trust-all
In V3, --trust-tools is honored only with --no-interactive and matches exact internal tool IDs. The interactive V3 terminal UI ignores it. CLI 2.x accepts its own tool names. For reusable or capability-level rules, use permissions.yaml.
Create ~/.kiro/settings/permissions.yaml for user-scoped rules:
rules: - capability: shell match: ["git *", "npm *", "npx *"] effect: allow - capability: fs_write match: ["src/**", "tests/**"] effect: allow - capability: fs_read effect: allow - capability: mcp match: ["my-server/*"] effect: allow
Workspace-scoped rules (~/.kiro/workspace-roots/<hash>/permissions.yaml) are stored per-user outside the repository, so a cloned repo cannot inject permission rules. Use them to scope rules to one project:
rules: - capability: shell match: ["rm -rf *", "sudo *"] effect: deny - capability: fs_write match: ["*.env", "*.pem", "*.key"] effect: deny
Rules are evaluated using a deny-overrides algorithm: deny > ask > allow. There is no precedence between scopes — the most restrictive effect wins regardless of which scope it came from.
| Scope | Location | Allowed effects |
|---|---|---|
| Kiro | Hardcoded security invariants (cannot be overridden) | deny, ask |
| administration | Enterprise/MDM-managed policy (enterprise plans only) | deny, ask |
| user | ~/.kiro/settings/permissions.yaml | deny, ask, allow |
| workspace | ~/.kiro/workspace-roots/<hash>/permissions.yaml | deny, ask, allow |
| agent | Embedded in agent profile (permissions field) | deny, ask, allow |
| session | Runtime (e.g., --trust-all-tools) | deny, ask, allow |
Kiro applies shared built-in defaults before user, workspace, agent, and session rules. Creating a permissions.yaml adds to those defaults; it does not replace them. See Default behavior for the authoritative policy and protected paths.
For CI pipelines that previously used --trust-all-tools, create a user-scoped permissions file in your CI environment:
# ~/.kiro/settings/permissions.yaml (CI environment) rules: - capability: all effect: allow
The --trust-all-tools flag still works as a session-scope override and continues to function for CI use cases without configuration changes.
fs_read, fs_write, shell, web_fetch, web_search, mcp, subagent, skill, power, context, diagnostics, sandbox_network. Meta-capabilities: all (everything), builtin (all built-in tools), filesystem (fs_read + fs_write).
Rules also support an exclude field for "allow everything except" patterns:
rules: - capability: mcp match: ["my-server/*"] exclude: ["my-server/dangerous-tool"] effect: allow
Permissions migration