Setup & First Run

Kiro CLI is an AI coding agent that lives in your terminal — it reads your codebase, writes code, runs commands, and asks before doing anything destructive. This guide gets you from zero to productive in about five minutes.

If you haven't installed yet, run the install command from the installation page and complete browser authentication. Then come back here.

Kiro CLI has a built-in guide agent that knows everything about the CLI — commands, tools, settings, workflows, and best practices. Instead of reading docs, you can just ask it.

After launching a session, type:

> /guide

Then have a conversation:

[guide] > What can you help me with?

[guide] > How should I set up this project to work well with Kiro?

[guide] > What's the best way to do code reviews with Kiro?

[guide] > How do I connect my GitHub account?

The Guide agent draws from indexed documentation that matches your installed version. It can also create configuration files for you — agents, prompts, and steering files — right from the conversation.

Press Shift+Tab to return to your main agent when you're ready to start working.

Navigate to any project directory and launch Kiro:

cd my-project
kiro-cli

The terminal UI opens — a rich chat interface with syntax highlighting, interactive panels, and visual tool progress. You're now talking to an AI agent that can read, write, and run commands in your project.

Type naturally. Kiro understands your project context and can take action:

> Explain the architecture of this project

> Find all TODO comments and summarize them

> Write a unit test for the auth module

> Refactor the database connection to use connection pooling

Kiro reads your files, runs commands, and makes changes — asking for permission before anything destructive.

Point Kiro at specific files using @ with tab completion:

> Review @src/api/routes.ts for security issues

Press Shift+Tab to switch to Plan mode. Kiro outlines what it intends to do before making any changes — useful when you want to review the approach first.

[plan] > Migrate the Express routes to use async/await error handling

The agent produces a structured plan with steps. When you're satisfied, it switches to execution mode and carries out the work.

Prefix with ! to run commands without going through the agent:

!npm run build

When Kiro wants to run a command or write a file, you'll see an approval prompt. Press y to approve, n to reject, or Tab to drill into options and provide feedback.

Out of the box, Kiro reads your files and infers context. But you can make it significantly smarter by telling it about your project's conventions. Create a steering file:

mkdir -p .kiro/steering

Add .kiro/steering/project.md:

# Project Context

- This is a TypeScript project using Next.js 15
- Use pnpm for package management
- Follow the existing code style (Prettier + ESLint)
- Write tests with Vitest
- Prefer functional components with hooks

Kiro reads steering files automatically and follows your guidelines in every response. The difference is immediate — responses match your stack, your conventions, and your preferences.

See Steering for the full guide on writing effective steering files.

Slash commands control your session. Type / and the TUI shows autocomplete suggestions. Here are the ones you'll use most:

Kiro ships with built-in agents for different tasks, and you can create your own:

• Default agent — general-purpose coding assistant
• Plan agent — breaks down complex tasks into structured plans (Shift+Tab)
• Guide agent — answers questions about Kiro CLI itself (/guide)

Create custom agents for recurring workflows — code review, test writing, deployment, or anything specific to your team:

> /guide Create an agent for code review

The Guide agent generates a .kiro/agents/code-review.yaml file. Switch to it anytime with /agent swap code-review.

For larger tasks, Kiro can spawn subagents that work in parallel with isolated context. Press Ctrl+G to open the crew monitor and watch them work in real time.

See Subagents and Custom agents for the full guide.

Beyond the per-action approval flow, you have fine-grained control over what Kiro can do:

• Trust patterns — approve a command once, or trust a pattern (e.g., all npm run commands) so you're not interrupted for routine operations
• Tool permissions — use /tools trust <name> to pre-approve specific tools, or /tools untrust <name> to require explicit permission
• Reset anytime — /tools reset clears all runtime permissions

See Permissions for the full trust model.

Kiro supports the Model Context Protocol (MCP), which lets it interact with databases, APIs, GitHub, and other services directly. Once you configure an MCP server, you can ask things like "list my open pull requests" or "query the staging database."

See MCP integration to connect your first server.

• Press Shift+Enter to type multi-line prompts
• Press Shift+Tab to switch to Plan mode (agent plans before acting)
• Press Esc to cancel the agent or close any panel
• Type /help to see all available commands

The full keyboard reference is in Terminal UI.

Kiro CLI (v1.8.0+) respects standard proxy environment variables. Set these in your shell:

export HTTP_PROXY=http://proxy.company.com:8080
export HTTPS_PROXY=http://proxy.company.com:8080
export NO_PROXY=localhost,127.0.0.1,.company.com

For proxies that require authentication:

export HTTPS_PROXY=http://username:password@proxy.company.com:8080

If you're having a problem with Kiro CLI, run kiro-cli diagnostic. It prints your Kiro CLI version, system information, and environment.

To report the problem, run kiro-cli issue. It opens a GitHub issue form in your browser with the diagnostic report filled in. Over SSH, in CloudShell, or in WSL, kiro-cli issue prints the issue URL instead of opening it. It also prints the URL if the browser does not open.

Kiro CLI writes logs to platform-specific locations:

Override the log path with the KIRO_CHAT_LOG_FILE environment variable:

KIRO_CHAT_LOG_FILE=/tmp/my-debug.log kiro-cli chat

On Windows (PowerShell):

$env:KIRO_CHAT_LOG_FILE = "C:\temp\my-debug.log"
kiro-cli chat

• Home directory fills during startup: In storage-constrained environments such as CloudShell, set KIRO_SKIP_BINARY_PINNING=1 only when the installed Kiro binary remains at a fixed, stable path. This avoids creating a session-specific binary copy. Do not use it if an installer can replace or delete the binary during the session.
• Bundled runtime fills the home directory: In Kiro CLI 2.37 or later, set KIRO_RUNTIME_DIR to an absolute path to extract Kiro's bundled runtime there instead of your home directory. A relative or empty value is ignored. To confirm, start kiro-cli chat and check that the directory now holds the runtime.
• Authentication failures — Run kiro-cli login to re-authenticate.

1. Run kiro-cli diagnostic to check your Kiro CLI version, system information, and environment.
2. Check your internet connection.
3. Verify that you're using a supported environment. See CLI commands for supported shells.
4. Try reinstalling Kiro CLI from the installation page.
5. If the issue persists, report it using kiro-cli issue.

Now that you're up and running, here's where to go deeper:

• Terminal UI — Full reference for the chat interface, themes, and panels
• Steering — Guide Kiro with project-specific context and conventions
• Custom agents — Build specialized agents for your workflows
• MCP — Connect external tools and data sources
• Hooks — Automate actions before and after commands
• Headless mode — Run Kiro non-interactively in CI/CD pipelines
• Guide agent — Ask Kiro about its own features anytime with /guide