Kiro CLI

kiro-cli runs the same Kiro agent in your terminal. It is not a cut-down companion to the IDE: it has the full primitive set, and it is the only surface that works over SSH, inside a container, and in a CI pipeline.

What is the Kiro CLI?

One command starts a session in whatever directory you are in:

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

# Windows 11 (PowerShell or Windows Terminal, not Command Prompt)
irm 'https://cli.kiro.dev/install.ps1' | iex

kiro-cli

Note the platform asymmetry, because it catches people out: the CLI needs Windows 11 specifically, where the IDE supports Windows 10 and 11. On Linux the asymmetry runs the other way, since the CLI needs only glibc 2.34 with a musl fallback against the IDE’s 2.39. On an older server, the CLI is the surface that works.

Kiro CLI is also the successor to Amazon Q Developer CLI. The q and q chat entry points were preserved and configuration migrated from ~/.aws/amazonq/ to ~/.kiro/, which is why so many older tutorials use different command names. History has the full story.

Why it exists

Some work simply is not in an editor. Debugging a box you reached over SSH. Running a migration in a container. A CI job that has no screen at all. Those cases do not want a desktop app; they want a process you can pipe things into.

There is a second reason, subtler and more useful day to day. A terminal session is scriptable and composable. !command drops straight to the shell, sessions save and load as files, and headless mode turns the agent into something a pipeline can call. Once the agent is a command, it fits everywhere your other commands do.

How it works

Steering a session. Slash commands are how you drive:

Command	What it does
/context show | add "glob" | remove | clear	Inspect and shape what is loaded, with per-file and per-tool token cost
/chat new | resume | save | load	Start, resume, export, and import sessions
/agent create | swap	Make and switch custom agents
/spec new | run	Create a spec; /spec run opens the full-screen task view
/compact	Manually summarize older history to free context
/effort	Set reasoning effort for the session
/tangent	Branch a side-conversation that inherits full history
/mcp auth | cancel-auth | logout	Manage MCP server authentication
/voice	Dictate a prompt, transcribed on-device

Outside the slash menu, !command runs a shell command with no AI involved, @ references files, and /guide starts the built-in onboarding agent. Sessions resume with kiro-cli chat --resume, --resume-id <id>, or --resume-picker.

Headless mode. This is the CI story:

kiro-cli chat --no-interactive "Summarize the failing tests and propose a fix"

Authentication comes from the KIRO_API_KEY environment variable, sourced from your secret store. --trust-tools=<categories> pre-approves specific tool categories (read,grep, for example) so the run does not stall waiting for an approval nobody is there to give, and --trust-all-tools exists for cases where you genuinely mean it. --require-mcp-startup fails the run fast if MCP servers cannot connect, which turns a hanging job into an honest error.

ACP. kiro-cli acp, optionally with --agent my-agent, speaks JSON-RPC 2.0 over stdin and stdout, which lets other editors use Kiro as their agent. JetBrains configuration lives in ~/.jetbrains/acp.json; Zed’s goes in ~/.config/zed/settings.json under “Kiro Agent”. Use the full path to the binary, which which kiro-cli will give you. CLI sessions are stored in ~/.kiro/sessions/cli/.

Recent releases. v2.20.0 (August 26, 2026) gave V3 spec runs a full-screen task execution view with real-time progress and task scope selection before execution, plus a “preserve scrollback” toggle. v2.21.0 (September 1, 2026) added a session dashboard covering local and cloud sessions and a configuration panel listing agents, MCP servers, powers, steering, skills, and hooks, with cloud configuration applying to new local V3 sessions.

Compaction settings. Two knobs control how conservative automatic compaction is: compaction.excludeMessages (default 2) and compaction.excludeContextWindowPercent (default 2). The more conservative of the two wins.

Common mistakes

Treating the CLI as the lesser surface. It has steering, hooks, MCP, custom agents, skills, specs, and cloud sessions. The fix: pick a surface by where the work is, not by which feels more serious.

Installing from Command Prompt on Windows. irm ... | iex is PowerShell syntax and will not be recognized elsewhere. The fix: use PowerShell or Windows Terminal, on Windows 11.

Expecting the browser sign-in to finish on a headless box. The install script ends by opening a browser, which is nowhere to be found on a CI runner. The fix: use KIRO_API_KEY.

Letting an unattended run spend without a ceiling. A retry loop that would annoy you interactively will quietly bill you at 3am. The fix: narrow prompt, restricted tool categories, and something that stops it.

Permissions and safety

The CLI uses the same capability-based permission model as everywhere else, with the same ranking: deny > ask > allow, and deny wins from any of the six scopes. In headless mode there is nobody to answer an ask, which is exactly why --trust-tools takes categories rather than a blanket switch. Grant the narrowest set the job needs.

.kiroignore support in the CLI is partial: it currently applies to V3 search results rather than across the board, where the IDE has full support. Plan sensitive-path protection with that difference in mind.

Where it fits

The CLI is one surface among five, running the same agent as the IDE, Web, mobile, and Crew. It is where cloud sessions get their --cloud and --resume-id flags, where headless automation lives, and, through ACP, how Kiro reaches editors that are not the Kiro IDE.

Learn more

• Kiro CLI Guide is the full chapter, with the complete command tables.
• Headless Kiro CLI in CI is the pipeline recipe.
• Kiro CLI in JetBrains and Zed covers ACP setup.
• Compact a long session and Set reasoning effort cover /compact and /effort.
• Start a cloud session from the CLI connects the two ideas.