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.
CLI V3 uses the same unified agent harness 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.
Check your version
Run kiro-cli --version and confirm it reports 3.0.0 or later. If it does not, update first; see Installation.
Choose the harness
Read Choose an agent harness 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, 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.
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.
Migrate your configuration
Work through the migration guide, then the guides for permissions, Hooks, and ACP clients 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.
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 →
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 →
Enhanced hooks: Standalone .kiro/hooks/*.json files with two action types (shell commands and agent prompts), new triggers, and a versioned schema. Learn more →
Enhanced agent config: Tag-based tool selection, unified permissions block, Markdown format, inline MCP servers. Learn more →
Introspect sub-agent: Ask Kiro about its own features and it answers from the official documentation. Learn more →
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 →
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 →
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 |
| Prompt input | Available | File references, image paths and clipboard images, queued messages, and multi-line editing | Working with images, File references |
| Settings and display | Available | Global and workspace settings, ASCII mode, custom busy indicators, shared or per-session history, and scrollback control | In-session settings, Settings reference |
| Models and reasoning | Available | Session model selection plus Thinking and Effort controls in /model, with explicit saved defaults | Models, Reasoning effort |
| Documentation help | Available | An introspect sub-agent answers questions about Kiro features from the official documentation | Built-in agents |
| Workflows | Available; opt-in | Background multi-step runs after you set chat.enableWorkflows | Workflows |
| Specs and Plan mode | Available | Guided Spec creation, automatic Plan handoff, in-terminal Spec review, and full-screen task execution | Specs |
| Tangent and rewind | Available; V3 expands Tangent | Rewind branches from an earlier turn; V3 adds named, nestable side-conversations | Tangent, Rewind |
| Custom agents | Available; migration required | Universal agent profiles, AI-assisted creation, editing, and /upgrade-agent | Custom agents, Upgrading agent configs |
| Permissions | Available; migration required | Capability rules, scoped persistent policies, granular approvals, and session-wide trust | Permissions |
| Hooks | Available; migration required | Standalone project Hooks, global Hooks, blocking triggers, and dynamic confirmation | Hooks |
| MCP servers | Available | Configuration hot reload, authentication controls, pre-registered OAuth clients, and current protocol support | MCP configuration |
| Sub-agents | Available | Parallel isolated work, prompt previews, the Ctrl+G monitor, and idle timeouts | Sub-agents, Terminal UI |
| Local sessions | Available | Resume, export, dashboard search and cleanup, response indexing, and full replay of saved tool results | Session management |
| Headless automation | Available | JSON Lines event output, saved agent and model defaults, interruption records, and required-MCP startup checks | Headless mode |
| Cloud sessions | V3 only | Managed sandbox sessions that keep running after disconnect, with local and cloud sessions in one dashboard | Cloud sessions |
| Voice input | Available | Local speech-to-text input with /voice | Voice mode |
| Configuration and Steering | Available | Nested AGENTS.md, the /config panel, and optional Configuration Sync for new local sessions | Configuration, Steering |
| Skills and Powers | Available | Skill discovery, IDE-installed Powers, and /powers listing | Skills, Powers |
| Code Intelligence and Knowledge | Available | LSP-backed code navigation and semantic knowledge indexes | Code Intelligence, Knowledge bases |
| 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 |
| 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 |
| 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 |
| 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 and kiro-cli issue |
| "Vibe" concept removed | N/A for CLI | "Default" mode is the standard name | Low |
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: all 7 steps with examples
- Upgrading agent configs: what
/upgrade-agentconverts, its diagnostics, and the automatic upgrade when V3 starts (off whenchat.enableAutoAgentUpgradeisfalse) - Permissions migration: CLI 2.x trust configuration →
permissions.yaml, behavioral changes - Hooks migration: legacy object Hooks → profile-scoped arrays or standalone
.kiro/hooks/files, trigger name mapping - ACP client migration: 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. The capabilities V3 adds are documented on their own pages, listed under Feature parity today.
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.
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 |
| 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 for the resume commands and for what happens to the original V2 session and its saved tool approvals.
- Choose an agent harness: defaults, one-run and saved choices, verification, and the way back to V2
- Troubleshooting: route a symptom to the page that owns the fix
- CLI 2.x reference: how 2.x Hooks, trust, and compaction behaved
- Hooks documentation: full hooks reference
- MCP configuration: MCP server setup
- Steering: steering document details
Upgrade from CLI 2.x