Kiro CLI Guide

The CLI is the same Kiro brain in a different body: everything is text, everything is scriptable, and it works anywhere a terminal works (laptops, servers, containers, CI).

(Historical footnote that explains a lot of old blog posts: Kiro CLI evolved from Amazon Q Developer CLI in late 2025; q still works as an entry point. Details in History.)

Install and first session

On macOS or Linux:

curl -fsSL https://cli.kiro.dev/install | bash

On Windows, the CLI requires Windows 11 and installs from PowerShell or Windows Terminal (not Command Prompt):

irm 'https://cli.kiro.dev/install.ps1' | iex

(Linux also has AppImage, .deb, and zip packages if you’d rather not pipe to bash; see the official install page.) Then, inside any project directory:

kiro-cli

The install finishes with a browser-based sign-in. Complete it and you’re ready. On your first session, try /guide: it starts the CLI’s built-in onboarding agent, which answers “how do I…” questions about your own workflows.

The session toolkit

Everything below is a verified command. Learn the left column; the right column is why you care.

Context (control what the agent sees):

Command	What it does
/context show	Show what’s loaded, with token usage per file
/context add "src/**/*.py"	Include files matching a glob
/context remove	Drop a context rule
/context clear	Empty the context rules

Conversations (make sessions durable):

Command	What it does
/chat new	Fresh conversation (current one is saved)
/chat new "review the auth module"	Fresh conversation with an opening prompt
/chat resume	Return to the previous session
/chat save notes/session.json	Export the conversation to JSON (-f to overwrite)
/chat load notes/session.json	Import a saved conversation

Resuming from the shell:

Command	What it does
kiro-cli chat --resume	Resume this directory’s last session
kiro-cli chat --resume-id <SESSION_ID>	Resume a specific session
kiro-cli chat --resume-picker	Pick interactively

Cloud sessions (v2.17.0+, preview):

Command	What it does
kiro-cli --cloud	Run the session in a managed AWS sandbox instead of on your machine
kiro-cli --cloud --repo <repo>	Attach a repository at creation (or use the /repo picker)
kiro-cli chat --resume-id <id>	Reattach to a cloud session from any machine

The point of a cloud session is that closing the terminal does not stop the agent. Start one, disconnect, reattach later from a different machine, and the transcript replays where you left off. It needs a paid plan and currently runs in US East only; enterprise administrators have to enable it, because cloud sessions ship opt-in for organizations (v2.18.0). The full set of preview limits is in Core Concepts.

Composing and escaping:

Command	What it does
/editor	Draft a long prompt in your $EDITOR
/reply	Open the editor quoting the last assistant message
/voice (or hold Space)	Dictate a prompt; transcription runs on-device with Whisper (v2.18.0)
!npm test	Run a shell command directly, no AI in the loop
Ctrl+O	Expand compressed (head+tail) command output

MCP and specs:

Command	What it does
/mcp auth	Manage MCP server authentication
/mcp cancel-auth	Cancel pending MCP authentication
/mcp logout	Remove saved MCP credentials
/spec new	Start a new spec with a guided description step
/spec run	Open the full-screen task execution view: pick the task scope, then watch progress live (v2.20.0, V3 spec runs)
Ctrl+X (at a spec phase checkpoint)	Open the spec review screen: read the phase document in place and stage line comments (v2.18.0; mouse scroll and click added in v2.19.0)
/tangent	Branch into a side-conversation (inherits full history)
/tangent ls	Visual picker for conversation tree navigation
/upgrade-agent	Migrate a V2 custom agent config to V3 format

Agents:

Command	What it does
/agent create my-agent -D "description"	Create a custom agent (add --manual to edit JSON in your editor)
/agent swap	Switch personas mid-session
kiro-cli --agent reviewer	Start a session as a specific agent

A realistic ten-minute session

cd ~/code/inventory-service
kiro-cli

# inside the session:
/context add "src/services/**"
How does reservation expiry work? Walk me through the flow.

!pytest tests/services/ -x        # direct shell, no AI
The test_expiry_race test fails intermittently. Investigate.

/chat save notes/expiry-debugging.json

That last line matters more than it looks: a saved session is a handoff document. A teammate can /chat load it and continue with full context.

The full toolbox works here

Steering files, hooks, MCP servers, skills, and custom agents all function in the CLI: same files, same locations (.kiro/steering/, .kiro/settings/mcp.json, .kiro/agents/, .kiro/skills/). Configure once, use from both the IDE and the terminal. The CLI also ships autocomplete for context-aware command completion.

Permissions

Every file read, command execution, and MCP call is checked against your permission rules before it happens, in the terminal exactly as in the IDE. The capabilities are fs_read, fs_write, shell, web_fetch, web_search, mcp, subagent, skill, power, context, diagnostics, and sandbox_network, plus the meta capabilities all, builtin, and filesystem. Effects rank deny over ask over allow, and deny wins regardless of scope. User rules live in ~/.kiro/settings/permissions.yaml; workspace rules live under ~/.kiro/workspace-roots/<hash>/permissions.yaml, outside the repository. An approval prompt offers Allow, Deny, Always allow, and Always deny, and your answer can persist to all workspaces, this workspace, or this session. Recipe: Set up permissions.yaml.

Checkpoints and rewind

Two different recoveries, and only one of them touches your files. Rewind is a CLI feature: it forks the conversation at an earlier turn into a new session and leaves your files exactly as they are, which is what you want when the code is fine but the conversation went the wrong way. Checkpoints snapshot the files the agent changed with its built-in tools; they are fully supported in the IDE and are marked experimental in CLI V3. Neither tracks your manual edits, formatter runs, MCP tool writes, or the effects of shell commands, so a commit before a long run remains the real safety net. Recipe: Undo with checkpoints and rewind.

Compaction and context

When the context fills, Kiro summarises the older part of the conversation. That happens automatically on every surface, and the CLI is the only one with a manual /compact. Compaction keeps task status, file paths, decisions, and next steps, and summarises tool output, old code snippets, and resolved errors. It is one-way: history before the compaction point is not recoverable, so /chat save anything you want to keep first. Two settings protect the recent turns: compaction.excludeMessages (default 2) and compaction.excludeContextWindowPercent (default 2), and the more conservative of the two wins. When the pressure comes from loaded files rather than conversation length, /context show reports token usage per file and /context remove drops a rule. Recipe: Compact a long session.

.kiroignore

A .kiroignore file keeps .env, keys, dumps, and build output away from the agent. It uses gitignore syntax, sits in the workspace root or a subdirectory, and stacks with a global file at ~/.kiro/settings/kiroignore. Kiro also respects git’s core.excludesfile. One important caveat for terminal users: support differs by surface. The IDE has full support, CLI V3 applies the rules to search results, and Kiro Web and the mobile app do not support it yet. Negation patterns work, but you cannot re-include a file inside a directory you already excluded. Recipe: Keep secrets out with .kiroignore.

Configuration scopes and KIRO_HOME

Kiro reads configuration from a global directory, ~/.kiro/, and a project directory, .kiro/, with the closer scope winning:

Item	Global	Project
MCP servers	~/.kiro/settings/mcp.json	.kiro/settings/mcp.json
Agents	~/.kiro/agents/	.kiro/agents/
Steering	~/.kiro/steering/	.kiro/steering/
Skills	~/.kiro/skills/	.kiro/skills/
Hooks	~/.kiro/hooks/	.kiro/hooks/
Powers	~/.kiro/powers/	Global only
Specs	Project only	.kiro/specs/

The precedence rules differ by item and are worth knowing: MCP resolves agent over project over global; a project agent supersedes a global agent with the same name and Kiro warns about the clash; steering, skills, and hooks merge across scopes; permissions are deny-overrides. Set KIRO_HOME to relocate the global directory, which is the clean way to keep separate profiles on one machine. CLI sessions themselves are stored in ~/.kiro/sessions/cli/.

Use the CLI inside JetBrains or Zed (ACP)

kiro-cli acp speaks JSON-RPC 2.0 over stdin and stdout, which is what an Agent Client Protocol client expects. Add --agent my-agent to start it as a specific custom agent. JetBrains reads ~/.jetbrains/acp.json, and Zed reads ~/.config/zed/settings.json under a “Kiro Agent” entry. Use the full path from which kiro-cli in both, because an editor launched from a desktop icon may not inherit your shell PATH. There is no Kiro plugin for JetBrains; ACP is the supported route. Recipe: Use Kiro CLI in JetBrains or Zed.

Built-in tools

These are the tools the agent reaches for on its own. Knowing the names makes approval prompts and --trust-tools categories readable rather than mysterious:

Tool	What it does
read_file / read_files	Read one or several files
list_directory	List a directory’s contents
file_search	Find files by name
grep_search	Search file contents
fs_write / fs_append / str_replace	Create, append to, and edit files
delete_file	Delete a file
execute_bash	Run a shell command
web_search / web_fetch	Search the web and fetch a URL
invoke_subagent	Hand work to another agent
disclose_context	Load a skill’s instructions into context
introspect	Explain Kiro’s own features and configuration
todo_list	Track the steps of a task
code (CLI only)	Tree-sitter code analysis across 18 languages
goal (CLI only)	Track the session’s objective
session_settings (CLI only)	Read and change session settings
tool_search (CLI only)	Find an available tool
knowledge, thinking (CLI only)	Experimental

Custom agents control access to these through the tools field, using the categories read, write, shell, web, and @builtin. Recipe: Create a custom agent.

Headless and CI

The CLI runs headless, with the agent as an unattended workflow step (nightly doc regeneration, automated triage, scheduled checks):

# KIRO_API_KEY comes from your CI secret store, never the repo
kiro-cli chat --no-interactive --trust-tools=read,grep "Review this diff for risky changes"

The verified pieces: --no-interactive takes the prompt as an argument and exits when done; authentication comes from the KIRO_API_KEY environment variable; --trust-tools=<categories> pre-approves only the tool categories you name (--trust-all-tools exists, but treat it with suspicion); and --require-mcp-startup fails the run fast instead of hanging the pipeline when an MCP server won’t connect.

Recommended guardrails (practice, not prescription): run headless jobs as a restricted custom agent, keep prompts deterministic and narrow, trust the smallest tool set that works, and watch credit consumption. An unattended loop spends credits without anyone watching. Recipe, with a GitHub Actions skeleton: Run Kiro CLI headless in CI.

What’s new in CLI 2.20 and 2.21

Two releases, both worth updating for.

v2.20.0 (26 August 2026) gave V3 spec runs a dedicated full-screen task execution view. Run a spec with /spec run, choose the task scope before execution begins, and watch real-time progress instead of scrolling a transcript. The same release added a Preserve scrollback toggle, which keeps terminal history available through overflow and resize redraws. If you have ever lost the output you wanted to the redraw after a long run, that toggle is the fix.

v2.21.0 (1 September 2026) added two panels and one piece of plumbing. The session dashboard lists local and cloud sessions together, so you stop tracking session ids by hand. The configuration panel shows what is actually loaded: agents, MCP servers, Powers, steering, skills, and hooks. That panel is the fastest answer to “is my steering file being read”, which is otherwise guesswork. The plumbing is cloud configuration: configuration synced from Kiro Web now applies to new local V3 sessions. Cloud content stays in the cloud and does not overwrite your local files, so cloud-synced items appear as read-only previews locally and stay editable in Kiro Web.

The CLI moves fast

Recent releases (from the official changelog) show the pace: v2.5 (May 2026) added visible thinking and subagent review loops; CLI V3 early access (v2.8.0, June 17) introduced a unified agent harness shared across the IDE, Web, and CLI, opt-in with kiro-cli --v3. v2.11 (July) brought MCP authentication management (/mcp auth); v2.13 added a built-in introspect subagent and global hooks; v2.14 brought /upgrade-agent to migrate V2 agent configs to the V3 format; v2.15 added a guided /spec new flow and automatic plan execution; and v2.16 (late July) introduced /tangent for branching into side-conversations that inherit full history, plus a per-tool token breakdown in /context.

August 2026 kept the pace up: v2.17.0 (Aug 11) added cloud sessions in preview and substring matching in the slash-command menu; v2.18.0 (Aug 12) added /voice dictation with on-device Whisper transcription, the spec review screen, and nested AGENTS.md as steering; v2.19.0 (Aug 19) added mouse support in the spec review screen and, more usefully for long runs, automatic recovery from stream failures — an idle watchdog that warns at 60 seconds and cancels at 300, automatic retries for throttling and dropped connections, and a 60-minute streaming timeout, all tunable through api.streamIdleSoftTimeout, api.streamIdleHardTimeout, and api.timeout. v2.20.0 (Aug 26) gave V3 spec runs a dedicated full-screen execution view via /spec run, with the task scope chosen up front and progress shown live, plus a Preserve scrollback toggle that keeps terminal history through overflow and resize redraws. If a flag here behaves differently next month, the changelog is the referee.