> ## Documentation Index
> Fetch the complete documentation index at: https://kiro.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Upgrade from CLI 2.x

> Move from Kiro CLI 2.x to the V3 agent harness one step at a time. What changed, breaking changes, the guided upgrade path, and where each migration guide lives.

In Kiro CLI 3.0.0 or later, V3 is the normal CLI experience. This page is for anyone still running Kiro CLI 2.x sessions, agent configs, permissions, Hooks, or ACP clients. Follow the steps in order; each ends with a check, and V2 stays one command away until you are done. For the day-to-day CLI documentation, start at [CLI](https://kiro.dev/docs/cli.md).

**ℹ️ Info:** Which harness a launch starts, how to choose one for a run or save a default, and how to answer the first-launch prompt are covered once in [Choose an agent harness](https://kiro.dev/docs/cli/agent-harness.md). This page links there instead of repeating it.

## A single harness for all Kiro surfaces

CLI V3 uses the same [unified agent harness](https://kiro.dev/docs/how-kiro-works.md) as Kiro IDE and Kiro Web. This brings shared agent-loop improvements to the terminal and lets supported `.kiro` configuration travel between surfaces. Some tools, commands, and configuration fields remain surface-specific; the tables below identify the supported V3 path. For how the CLI picks between the V3 and V2 harness, see [Choose an agent harness](https://kiro.dev/docs/cli/agent-harness.md).

## Your upgrade path

  
### Check your version

Run `kiro-cli --version` and confirm it reports 3.0.0 or later. If it does not, update first; see [Installation](https://kiro.dev/docs/getting-started/installation.md).

  
### Choose the harness

Read [Choose an agent harness](https://kiro.dev/docs/cli/agent-harness.md) to learn which harness each launch type starts and how a script, pipeline, or ACP client should name one. Keep `kiro-cli --v2` available until your V3 checks pass.

  
### Start V3

Run `kiro-cli` with no harness flag and answer the first-launch prompt described under [Answer the first-launch prompt](https://kiro.dev/docs/cli/agent-harness.md#answer-the-first-launch-prompt), or run `kiro-cli --v3`, which skips the prompt and saves no default. When V3 starts, it upgrades your V2 agent configs automatically unless `chat.enableAutoAgentUpgrade` is `false`; see [Upgrading agent configs](https://kiro.dev/docs/cli/v3/upgrade-agent.md).

  
### Preserve your sessions

V3 keeps a separate session store. Resume a V2 session in V3 with `--resume` or `--resume-id`, which creates a V3 copy and keeps the original. See [Start V3 and keep V2 sessions available](https://kiro.dev/docs/cli/v3/migration-guide.md#1-start-v3-and-keep-v2-sessions-available).

  
### Migrate your configuration

Work through the [migration guide](https://kiro.dev/docs/cli/v3/migration-guide.md), then the guides for [permissions](https://kiro.dev/docs/cli/v3/permissions.md), [Hooks](https://kiro.dev/docs/cli/v3/hooks-migration.md), and [ACP clients](https://kiro.dev/docs/cli/v3/acp-migration.md) that apply to you.

  
### Verify, and keep a way back

A V3 session opens with **Welcome to Kiro CLI V3**. If something you depend on is missing, return to V2 for one run with `kiro-cli --v2` or save it with `kiro-cli settings chat.agentEngine v2`; see [Return to V2](https://kiro.dev/docs/cli/agent-harness.md#return-to-v2).

## What's new in V3

**Spec-driven development**: The Spec agent brings structured development to the terminal. Define requirements, generate designs, execute task plans. Use `/spec new <name>` to start. [Learn more →](https://kiro.dev/docs/specs.md)

**Capability-based permissions**: Declare structured policies in `permissions.yaml` for fine-grained, auditable control. One rule can allow or deny an entire category of operations across all tools. [Learn more →](https://kiro.dev/docs/permissions.md)

**Enhanced hooks**: Standalone `.kiro/hooks/*.json` files with two action types (shell commands and agent prompts), new triggers, and a versioned schema. [Learn more →](https://kiro.dev/docs/hooks.md)

**Enhanced agent config**: Tag-based tool selection, unified permissions block, Markdown format, inline MCP servers. [Learn more →](https://kiro.dev/docs/custom-agents.md)

**Introspect sub-agent**: Ask Kiro about its own features and it answers from the official documentation. [Learn more →](https://kiro.dev/docs/custom-agents/built-in.md#introspect-sub-agent)

**Workflows**: Run multi-step work in the background while the main conversation stays available. Turn it on with the `chat.enableWorkflows` setting and restart Kiro CLI. [Learn more →](https://kiro.dev/docs/workflows.md)

**Tangent**: Branch your conversation into side-conversations that inherit your context, explore freely, then jump back to exactly where you left off. Use `/tangent` to branch. [Learn more →](https://kiro.dev/docs/cli/chat/tangent.md)

## Feature parity today

The table tracks current V3 support across core CLI workflows and capabilities that exist only on the shared harness. "Available" means the reader task has a supported V3 path; the interface or configuration format can still differ from V2.

| Area | V3 status | What is available now | Details |
|------|:---------:|-----------------------|---------|
| **Chat and terminal UI** | Available | Markdown rendering, tool cards, Preserve scrollback, live progress, and fullscreen chat | [Terminal UI](https://kiro.dev/docs/cli/terminal-ui.md) |
| **Prompt input** | Available | File references, image paths and clipboard images, queued messages, and multi-line editing | [Working with images](https://kiro.dev/docs/cli/chat/images.md), [File references](https://kiro.dev/docs/cli/chat/file-references.md) |
| **Settings and display** | Available | Global and workspace settings, ASCII mode, custom busy indicators, shared or per-session history, and scrollback control | [In-session settings](https://kiro.dev/docs/cli/chat/settings.md), [Settings reference](https://kiro.dev/docs/reference/settings.md) |
| **Models and reasoning** | Available | Session model selection plus Thinking and Effort controls in `/model`, with explicit saved defaults | [Models](https://kiro.dev/docs/models.md), [Reasoning effort](https://kiro.dev/docs/models/effort.md) |
| **Documentation help** | Available | An introspect sub-agent answers questions about Kiro features from the official documentation | [Built-in agents](https://kiro.dev/docs/custom-agents/built-in.md#introspect-sub-agent) |
| **Workflows** | Available; opt-in | Background multi-step runs after you set `chat.enableWorkflows` | [Workflows](https://kiro.dev/docs/workflows.md) |
| **Specs and Plan mode** | Available | Guided Spec creation, automatic Plan handoff, in-terminal Spec review, and full-screen task execution | [Specs](https://kiro.dev/docs/specs.md) |
| **Tangent and rewind** | Available; V3 expands Tangent | Rewind branches from an earlier turn; V3 adds named, nestable side-conversations | [Tangent](https://kiro.dev/docs/cli/chat/tangent.md), [Rewind](https://kiro.dev/docs/checkpoints.md) |
| **Custom agents** | Available; migration required | Universal agent profiles, AI-assisted creation, editing, and `/upgrade-agent` | [Custom agents](https://kiro.dev/docs/custom-agents.md), [Upgrading agent configs](https://kiro.dev/docs/cli/v3/upgrade-agent.md) |
| **Permissions** | Available; migration required | Capability rules, scoped persistent policies, granular approvals, and session-wide trust | [Permissions](https://kiro.dev/docs/permissions.md) |
| **Hooks** | Available; migration required | Standalone project Hooks, global Hooks, blocking triggers, and dynamic confirmation | [Hooks](https://kiro.dev/docs/hooks.md) |
| **MCP servers** | Available | Configuration hot reload, authentication controls, pre-registered OAuth clients, and current protocol support | [MCP configuration](https://kiro.dev/docs/mcp/configuration.md) |
| **Sub-agents** | Available | Parallel isolated work, prompt previews, the `Ctrl+G` monitor, and idle timeouts | [Sub-agents](https://kiro.dev/docs/custom-agents/subagents.md), [Terminal UI](https://kiro.dev/docs/cli/terminal-ui.md) |
| **Local sessions** | Available | Resume, export, dashboard search and cleanup, response indexing, and full replay of saved tool results | [Session management](https://kiro.dev/docs/cli/chat/session-management.md) |
| **Headless automation** | Available | JSON Lines event output, saved agent and model defaults, interruption records, and required-MCP startup checks | [Headless mode](https://kiro.dev/docs/cli/headless.md) |
| **Cloud sessions** | V3 only | Managed sandbox sessions that keep running after disconnect, with local and cloud sessions in one dashboard | [Cloud sessions](https://kiro.dev/docs/cloud-sessions.md) |
| **Voice input** | Available | Local speech-to-text input with `/voice` | [Voice mode](https://kiro.dev/docs/cli/voice.md) |
| **Configuration and Steering** | Available | Nested `AGENTS.md`, the `/config` panel, and optional Configuration Sync for new local sessions | [Configuration](https://kiro.dev/docs/configuration.md), [Steering](https://kiro.dev/docs/steering.md) |
| **Skills and Powers** | Available | Skill discovery, IDE-installed Powers, and `/powers` listing | [Skills](https://kiro.dev/docs/skills.md), [Powers](https://kiro.dev/docs/powers.md) |
| **Code Intelligence and Knowledge** | Available | LSP-backed code navigation and semantic knowledge indexes | [Code Intelligence](https://kiro.dev/docs/tools/code-intelligence.md), [Knowledge bases](https://kiro.dev/docs/cli/experimental/knowledge-management.md) |

## Breaking changes

| Change | Previous (2.x) | New (V3) | Impact |
|--------|----------------|-----------|--------|
| Built-in AWS tool unavailable | CLI 2.x `use_aws` tool (preferred alias `aws`) | Use MCP servers for AWS access | High |
| Session format changed | V2 session store | Separate V3 session store | High. V3 imports a V2 session as a V3 copy; V2 cannot open a V3 session |
| Hook format changed | CamelCase object embedded in the profile | PascalCase array definitions, inline or in standalone `.kiro/hooks/*.json` files | High |
| Hook trigger names | camelCase (`agentSpawn`) | PascalCase (`SessionStart`) | High |
| Persistent trust configuration changed | Per-tool `toolsSettings` rules | Capability-based `permissions.yaml`; session-wide trust uses `--trust-all-tools` or `/tools trust-all` | High |
| Sub-agent tool calls checked against the parent session | A sub-agent's own pre-approved tools ran without prompts, even if the parent didn't allow them | A sub-agent's tool call runs without a prompt only when the parent session's policy also allows it | High. Headless runs deny the call. See [Sub-agent permissions](https://kiro.dev/docs/custom-agents/subagents.md#sub-agent-permissions) |
| Classic interface retired | `--classic` or `--legacy-ui` opened the non-TUI interface | Interactive chat runs in the terminal UI on V3 or V2; a launch that still selects Classic is offered V3 | High. See [If a launch still selects Classic](https://kiro.dev/docs/cli/agent-harness.md#if-a-launch-still-selects-classic) |
| Desktop app and inline autocomplete retired | Desktop app with inline shell autocomplete and suggestions | In Kiro CLI 3.0.0 or later, a single standalone `kiro-cli` binary; existing macOS desktop app installs switch to it on their next update check | High. See [Moving from the Kiro CLI desktop app](https://kiro.dev/docs/getting-started/installation.md#moving-from-the-kiro-cli-desktop-app) |
| Desktop-app commands retired | `kiro-cli autocomplete`, `inline`, `translate`, `theme`, `dashboard`, and `doctor` | `autocomplete`, `inline`, `translate`, `theme`, and `dashboard` are unavailable. Running `kiro-cli doctor` directs you to `kiro-cli diagnostic` or `kiro-cli issue` | Medium. See [`kiro-cli diagnostic`](https://kiro.dev/docs/reference/cli-commands.md#kiro-cli-diagnostic) and [`kiro-cli issue`](https://kiro.dev/docs/reference/cli-commands.md#kiro-cli-issue) |
| "Vibe" concept removed | N/A for CLI | "Default" mode is the standard name | Low |

## Migration guide

Start V3 and run `/upgrade-agent` to convert supported agent fields, permissions, and object-form Hooks. Then review its diagnostics and make only the manual changes it reports or your workflow requires. Run it again after you change V2 trust settings so the generated V3 rules stay current.

- [Full migration guide](https://kiro.dev/docs/cli/v3/migration-guide.md): all 7 steps with examples
- [Upgrading agent configs](https://kiro.dev/docs/cli/v3/upgrade-agent.md): what `/upgrade-agent` converts, its diagnostics, and the automatic upgrade when V3 starts (off when `chat.enableAutoAgentUpgrade` is `false`)
- [Permissions migration](https://kiro.dev/docs/cli/v3/permissions.md): CLI 2.x trust configuration → `permissions.yaml`, behavioral changes
- [Hooks migration](https://kiro.dev/docs/cli/v3/hooks-migration.md): legacy object Hooks → profile-scoped arrays or standalone `.kiro/hooks/` files, trigger name mapping
- [ACP client migration](https://kiro.dev/docs/cli/v3/acp-migration.md): update ACP clients from the CLI v2 server to CLI V3

The current agent configuration format, including the Markdown form, is documented in the [agent configuration reference](https://kiro.dev/docs/custom-agents/configuration-reference.md). The capabilities V3 adds are documented on their own pages, listed under [Feature parity today](#feature-parity-today).

**ℹ️ Info:** Run `/upgrade-agent` inside a V3 session. See [Upgrading agent configs](https://kiro.dev/docs/cli/v3/upgrade-agent.md) for conversion behavior and diagnostics.

### Switch from the startup offer

In Kiro CLI 3.0.0 or later, the first interactive launch asks existing Kiro CLI 2.x users with saved sessions to choose a harness before V3 applies. The answers, what each one saves, and when the prompt is skipped are described under [Answer the first-launch prompt](https://kiro.dev/docs/cli/agent-harness.md#answer-the-first-launch-prompt).

## Remaining differences from V2

V3 does not reproduce every legacy surface. These differences remain relevant when deciding whether to switch:

| Difference | V3 behavior | If you depend on the V2 behavior |
|------------|-------------|----------------------------------|
| **Classic interface** | The V3 harness runs in the terminal UI. The Classic interface no longer runs for interactive chat on either harness | Move the workflow to the terminal UI; see [Terminal UI](https://kiro.dev/docs/cli/terminal-ui.md) |
| **Workspace checkpoints** | The experimental `/checkpoint` feature is not available on V3; V3 provides `/rewind` for conversation branches | Use version control to restore files and `/rewind` to revisit an earlier turn |

V3 can resume its own sessions and your V2 sessions, but V2 cannot open a V3 session because the stored session formats differ. See [Start V3 and keep V2 sessions available](https://kiro.dev/docs/cli/v3/migration-guide.md#1-start-v3-and-keep-v2-sessions-available) for the resume commands and for what happens to the original V2 session and its saved tool approvals.

## Learn more

- [Choose an agent harness](https://kiro.dev/docs/cli/agent-harness.md): defaults, one-run and saved choices, verification, and the way back to V2
- [Troubleshooting](https://kiro.dev/docs/cli/troubleshooting.md): route a symptom to the page that owns the fix
- [CLI 2.x reference](https://kiro.dev/docs/cli/2x-reference.md): how 2.x Hooks, trust, and compaction behaved
- [Hooks documentation](https://kiro.dev/docs/hooks.md): full hooks reference
- [MCP configuration](https://kiro.dev/docs/mcp/configuration.md): MCP server setup
- [Steering](https://kiro.dev/docs/steering.md): steering document details