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

Composing and escaping:

Command	What it does
/editor	Draft a long prompt in your $EDITOR
/reply	Open the editor quoting the last assistant message
!npm test	Run a shell command directly, no AI in the loop
Ctrl+O	Expand compressed (head+tail) command output

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.

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.

The CLI moves fast

Recent releases (from the official changelog) show the pace: v2.4 (May 2026) added conversation rewind and five-level reasoning-effort control; v2.5 added visible thinking and subagent review loops; v2.6 (June 2026) added transcript export and persistent model preferences. If a flag here behaves differently next month, the changelog is the referee.