Lesson 15

Kiro CLI

What the CLI Is

The Kiro CLI is the same agent you use in the IDE, but living in your terminal. It reads your codebase, writes code, runs commands, and asks before doing anything destructive - same capabilities, different interface.

It's not a replacement for the IDE - it's a complementary surface. Some workflows are better in the terminal.

When CLI Over IDE

Use the CLI when	Use the IDE when
You're already in the terminal and want to stay there	You need visual diffs, file tree, editor features
Headless/CI automation (no UI needed)	Interactive development with visual feedback
Quick one-off tasks without opening the IDE	Long sessions with multiple files open
SSH'd into a remote machine	Local development on your Mac
Running in scripts or pipelines	Collaborative/pair-programming with the agent

Getting Started

# Install - check kiro.dev/docs/cli/quick-start for the current method
# Common options include Homebrew, npm, or the official installer script

# Start an interactive chat in the current directory
kiro

# Start with a specific prompt
kiro "explain how the auth service works"

The CLI uses the same .kiro/ configuration as the IDE - steering, hooks, skills, MCP, custom agents all apply.

Key CLI Features

File references with @path

Include file contents directly in your message without a tool call:

kiro "refactor this service @src/app/services/user.service.ts to use signals"

The file content is expanded inline before sending - saves tokens by avoiding a read_file tool call. Use @folder/ (with trailing slash) to include a directory tree structure.

Session memory

The CLI automatically saves all chat sessions per-directory. When you start a session where you previously chatted, you can resume:

# Resume the last session in this directory
kiro --resume

# List previous sessions
kiro session list

This means you can close the terminal, come back tomorrow, and pick up where you left off.

Slash commands

Within an interactive session, slash commands provide shortcuts. Available commands may vary by CLI version - use /help to see what's available in yours:

Command	What it does
`/compact`	Manually compact conversation history to free context space
`/plan`	Switch to the planning agent (read-only research → structured plan)
`/model`	Change the active model
`/trust`	Manage tool permissions
`/knowledge`	Persistent knowledge base (experimental) - stores info across sessions
`/help`	Show all available commands

Headless mode (CI/CD)

Run Kiro without an interactive terminal - for automation:

# In a CI pipeline
kiro --headless --prompt "review this PR for security issues" --api-key $KIRO_API_KEY

Use cases: automated code review on PRs, test generation in CI, build failure troubleshooting, documentation generation.

Tool permissions

The CLI has explicit permission management:

Ask (default for destructive actions) - prompts you before running
Trust - auto-approve specific tools or commands
Deny - block specific tools entirely

You can trust specific command patterns: /trust "ng lint" means lint commands run without asking.

CLI-Specific Features Not in the IDE

Session persistence and resume - conversations saved automatically, resumable across terminal sessions
Headless mode - non-interactive execution for CI/CD pipelines
/plan agent - dedicated planning mode that researches then hands off to execution
/knowledge - experimental persistent knowledge base across sessions
@path file references - inline file expansion (IDE uses #File instead)
Custom agents with full YAML config - more elaborate than the IDE's markdown format (from Lesson 9)

Shared Configuration

The CLI reads the same config as the IDE:

Config	Shared?
Steering (`.kiro/steering/`)	Yes - same files
MCP servers (`.kiro/settings/mcp.json`)	Yes - same config
Global config (`~/.kiro/`)	Yes - same location
Skills (`.kiro/skills/`)	Yes - same files
Custom agents	Yes (though CLI supports richer format)
Hooks (`.kiro/hooks/`)	Yes - same hooks

This means everything you configure for the IDE works in the CLI too. No duplication needed.

The KIRO_HOME variable: Set KIRO_HOME to redirect the global ~/.kiro directory to a different location. Useful for maintaining separate profiles on the same machine (e.g. work vs personal).

Practical Scenarios

"I'm in the terminal and don't want to switch to the IDE"

kiro "add error handling to the payment service - wrap all HTTP calls in try/catch with structured logging"

"I want to review the PR changes before merging"

kiro "review the git diff for security issues and potential bugs @$(git diff --name-only)"

"I want to automate code review in CI"

kiro --headless --prompt "review this diff for: security issues, missing error handling, and Angular best practices. Output a summary." --api-key $KIRO_API_KEY

Your Tangible Win

You now know the CLI exists as a complementary surface, when to use it over the IDE, its unique features (session persistence, headless mode, @path references, /plan agent), and that it shares all your IDE configuration. If you ever need terminal-native workflows or CI automation, you know where to look.

Quick Check

The @path syntax in CLI does what?

Expands file contents inline into your message - avoids a tool call, saves tokens

Creates a symlink to the file for the agent to read later

Attaches the file as a binary blob

Which CLI feature has no equivalent in the IDE?

Steering support

Headless mode for CI/CD automation

MCP server connections

Recommended resources: CLI Overview, Quick Start, Headless Mode, File References, Session Management.