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 listThis 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_KEYUse 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
/planagent - dedicated planning mode that researches then hands off to execution/knowledge- experimental persistent knowledge base across sessions@pathfile references - inline file expansion (IDE uses#Fileinstead)- 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.
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_KEYYour 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.