Migration guide

Follow these steps in order to upgrade from CLI 2.x to V3.

Start a V3 session in the workspace you want to migrate:

kiro-cli --v3

V3 uses a different session store from V2. Trying V3 does not change or delete your existing V2 sessions.

• To continue a V2 session in V3, use /sessions, --resume, or --resume-id. Kiro creates a V3 copy, keeps the original V2 session, and does not carry over the saved tool approvals from the V2 session.
• To continue a V2 session on the V2 harness, run kiro-cli chat --v2 --resume-picker.

V2 cannot open a V3 session.

If you need an external record of an important conversation, open it with the harness that created it and run /chat save <path>. Treat the exported file as an archive unless you have verified that the target harness can load it.

From the V3 session, run the conversion and review its diagnostics before editing files manually:

> /upgrade-agent
> /upgrade-agent diagnostics

The command backs up selected profiles, converts compatible permission and Hook fields, and reports anything that needs manual attention. Complete those manual steps from the report. Run /upgrade-agent again after changing V2 trust settings so the generated V3 rules stay current. If the selection menu shows an out-of-sync agent, review Upgrading agent configs before rebuilding it because that action overwrites manual V3 edits.

/upgrade-agent converts an object-form hooks map to a flat array of Hook documents. It preserves legacy camelCase trigger strings as accepted compatibility aliases. Use PascalCase when you hand-author or revise the migrated definitions. Move Hooks that should run independently of a profile into standalone .kiro/hooks/*.json files, and update the five CLI lifecycle triggers:

CLI V3 also supports PostFileCreate, PostFileSave, and PostFileDelete for agent-made file changes, plus PreTaskExec and PostTaskExec around spec task execution. Manual Hooks are a legacy IDE 0.x feature. See Hooks migration for the current CLI schema, matcher behavior, global Hook location, and a complete before-and-after example.

Review the permissions rules created by /upgrade-agent, then apply any remaining changes below. Resolve every warning before using the migrated profile in CI.

For CI pipelines, --trust-all-tools grants session-wide approval. For narrower headless approval, --trust-tools accepts exact V3 tool IDs. You can also create ~/.kiro/settings/permissions.yaml with capability-specific allow rules in your CI environment.

Session overrides that remain in V3:

kiro-cli chat --v3 --no-interactive --trust-all-tools "Run the CI task"
kiro-cli chat --v3 --no-interactive --trust-tools=read_file,grep_search "Review this repository"

/tools trust-all

In V3, --trust-tools is honored only with --no-interactive; the interactive terminal UI ignores it. CLI 2.x accepts its own tool names.

New approach (~/.kiro/settings/permissions.yaml for user scope):

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

For the full reference — behavioral changes, scope definitions, and pattern conversion table — see Permissions migration →.

Sub-agents: In CLI 2.x, a sub-agent's own pre-approved tools ran without prompts, even if the parent didn't allow them. In CLI V3, a sub-agent's tool call runs without a prompt only when the parent session's policy also allows it, and headless runs deny the call. If a parent agent relied on this, copy the sub-agent's allow rules into the parent agent's permissions.rules, or into your user or workspace permissions.yaml. See Sub-agent permissions.

/upgrade-agent preserves supported profile fields and converts known tools and toolsSettings entries. Review its output and diagnostics before using the profile:

• The tools field now uses category tags or direct selectors. Step 6 maps common CLI 2.x names by destination.
• toolsSettings and allowedTools become capability-based permissions.rules.
• Profiles can remain JSON or use Markdown with YAML frontmatter and a body system prompt.
• Fields such as excludedTools, includeMcpJson, includePowers, resources, permissions, and welcomeMessage are optional.

Migrating toolsSettings to permissions:

Note: V2 allowedCommands and deniedCommands used regex patterns. V3 permissions use globs: remove anchors such as ^ and $, replace .* with *, and rewrite complex regexes as multiple rules.

See Agent config changes for complete JSON and Markdown examples, current fields, embedded MCP servers, and format guidance. If the profile contains Hooks, review their converted array or move profile-independent automation to a standalone file as described in Hooks migration.

The CLI 2.x structured AWS tool (use_aws, preferred alias aws) is not a V3 built-in. Configure an AWS MCP server instead. The managed remote AWS MCP entry in the MCP server registry uses this configuration:

.kiro/settings/mcp.json:

{
  "mcpServers": {
    "aws-mcp": {
      "url": "https://aws-mcp.us-east-1.api.aws/mcp",
      "disabled": false
    }
  }
}

Review the server's IAM access before using it, and use the registry for current setup options.

V3 uses different identifiers for agent-profile selection, permission policy, and runtime matching. Do not substitute one namespace for another.

The tools field accepts category tags and selected direct tool IDs:

/upgrade-agent rewrites the CLI 2.x task-list names (task, todo, todo_list) to todo_list, but CLI V3 has no task-list tool, so that entry selects nothing. Remove it from the converted profile.

The capability field uses operation classes, not profile tags or tool IDs:

knowledge has no generated per-tool capability mapping. Define rules for the operations the workflow actually performs instead of inventing a capability name.

V3 PreToolUse and PostToolUse matchers accept a tool selector (a V3 tool ID, a category tag, @builtin, @mcp, @<server>, @<server>/<tool>, or a */? wildcard) or a regular expression. A matcher that contains regex metacharacters is evaluated only as an unanchored regex against the internal tool ID. /upgrade-agent rewrites known CLI 2.x names to the matching tag; use this table when you hand-author a matcher:

The headless --trust-tools flag uses exact internal V3 tool IDs in a comma-separated list, not selectors or regexes—for example, --trust-tools=read_file,grep_search. See the tool catalog for profile tags and built-in IDs, Permissions for capabilities, and Hook types for matcher behavior.

1. From your shell, validate each migrated agent configuration:

   bash

   kiro-cli agent validate --path .kiro/agents/my-agent.json
   

2. Start or return to a V3 session in the migrated workspace. Run /config and /hooks to confirm Kiro loaded the expected agents, permissions, and Hooks.

3. Exercise representative commands to verify the approval behavior you intended.

Resolve every conversion warning or validation error before using the configuration in CI.

• Permissions migration — detailed guidance on migrating trust flags to permissions.yaml
• Hooks migration — full trigger mapping and new format reference