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 (/effort <level>; bare /effort is deprecated in V2, use /model)
/model	Switch model and configure effort in one panel (v2.23.0)
/fullscreen	Expand chat to a dedicated terminal screen (v2.22.0)
/tools trust-all	Auto-approve tool calls for the rest of a V3 session, after a warning (v2.24.0)
/powers install | uninstall	Add or remove a power from a V3 session (v2.25.0)
/workflow run	Launch a Workflow recipe in V3, once enabled in /settings (v2.26.0)
/memories	Set memory access or browse what Kiro remembers (local V3, v2.29.0); see Memory
/sandbox	Run agent shell commands in an operating-system sandbox (V3, v2.31.0)
/autonomous on	Stop approving each shell command in a local V3 session; turns the sandbox on first (v2.31.0)
/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.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. v2.22.0 (September 16, 2026) added fullscreen chat via /fullscreen, which expands the chat to a dedicated terminal screen with independent scrolling and text selection, and redesigned the /sessions dashboard with search, filter, and sort controls. v2.23.0 (September 21, 2026) merged model and effort controls into /model, so you switch models and configure thinking in one place. The same release let V3 cloud sessions start before connecting a repository — run /repo afterwards to attach one.

v2.24.0 (September 23, 2026) changed a default that can break existing setups: project .env files no longer load automatically into chat sessions, MCP servers, or tools. Kiro starts with the environment your terminal gives it, so export the variables in your shell before launching, and have MCP server configs reference the exported values. The same release added /tools trust-all for V3. v2.25.0 (September 28) added /powers install and uninstall (also kiro-cli powers install outside chat), V3 output styles, and a SessionEnd hook trigger. v2.26.0 (September 30) added opt-in Workflows: enable them under /settings → Features, restart, then ask Kiro for a workflow or launch a recipe with /workflow run. It also put a deprecation notice on Classic sessions (the older interface launched with kiro-cli --classic), naming whichever flag, environment variable, or setting launched Classic. v2.27.0 (October 1) exposed saved workspace, global, and MCP prompts as slash commands and added #[[folder:...]] and line-range references to steering in V3.

October continued at the same pace. v2.28.0 (October 5) let V3 hooks match a tool category such as shell or write. v2.29.0 (October 9) added Memory to local V3 sessions through /memories. v2.30.0 (October 12) began a gradual prompt inviting users to switch to V3 and added model fallback notices. v2.31.0 (October 13) brought the local command sandbox (/sandbox) and local autonomous mode (/autonomous on) to every V3 user, loaded MCP tools on demand, and moved all V3 state under KIRO_HOME when it is set; see Turn on the command sandbox. v2.31.1 draws Mermaid diagrams in the terminal, and v2.32.0 (October 15) lets you allow a whole folder at a write prompt and start cloud sessions from non-interactive runs.

V3 becomes the default. Kiro announced on October 9, 2026 that V3, the terminal UI on the shared agent harness, becomes the default with CLI 3.0 at the end of October. CLI 3.0 retires inline shell autocomplete, the CLI desktop app, and Classic sessions. V3 has no use_aws tool, so AWS commands run through the shell tool under shell approval rules. Run /upgrade-agent (or kiro-cli agent upgrade <dir> for a folder) before the switch, and see the CLI Guide for the full checklist.

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.