Kiro Installation Guide: IDE, CLI, and First Configuration

Kiro comes in two primary surfaces: the IDE (a VS Code fork) and the CLI (terminal-based agent). On Day 0, we covered what Kiro is and why its spec-driven approach matters. Today, we install both and configure them for real work.

If you’re coming from VS Code, the IDE will feel immediately familiar. If you live in the terminal, the CLI might be your daily driver. Either way, the setup takes minutes.

Prerequisites#

OS: macOS, Linux, or Windows (WSL2 recommended for Windows)
Git installed and configured
GitHub account (for autonomous agent features)
Node.js 18+ (recommended for CLI usage)
Disk space: ~500 MB for IDE, negligible for CLI

No AWS account required — Kiro uses AWS Builder ID, which is free and separate from your AWS billing account.

1. Installing Kiro IDE#

Kiro IDE is a VS Code fork built on Code OSS, so extensions, keybindings, and themes carry over.

Download: Visit kiro.dev/downloads

The download page auto-detects your OS. Grab the appropriate package:

macOS: .dmg (Apple Silicon & Intel)
Linux: .deb (Debian/Ubuntu), .rpm (Fedora), or .AppImage
Windows: .exe installer

Alternative — install via Homebrew (macOS/Linux):

1
brew install kirodev/tap/kiro

After installation: Launch Kiro IDE. You’ll be greeted by the sign-in screen — close it for now; we’ll handle configuration next.

What you get out of the box#

Kiro IDE is VS Code with these additions:

Agent panel — right sidebar for chat, specs, and agent interaction
Spec tab — structured requirement editor (prompt → spec flow)
Steering file generator — auto-creates .kiro/steering.md per project
Powers tab — MCP server marketplace built into the IDE
Kiro terminal — drop-down terminal with CLI pre-integrated

2. Installing Kiro CLI#

The CLI is a single binary with no dependencies beyond Git.

1
curl -fsSL https://kiro.dev/install.sh | sh

This installs the kiro command to /usr/local/bin. Verify:

1
kiro --version
2
# Example output: Kiro CLI 2.3.1 (build abc1234)

Manual install: If you prefer not to pipe curl to shell, grab the binary from kiro.dev/cli.

3. Authentication: AWS Builder ID#

Both IDE and CLI require AWS Builder ID — Amazon’s single sign-on for developer tools. It’s free and separate from your AWS root account.

Via IDE#

Launch Kiro IDE
Click Sign in with Builder ID in the welcome screen
A browser window opens — complete the sign-in flow
You’ll be redirected back to the IDE automatically

Via CLI#

1
kiro auth login

This opens a browser window. Complete the flow, and the CLI stores your session token locally.

Verify authentication:

1
kiro auth whoami
2
# Example output: Logged in as user@example.com (Builder ID: amzn1.account.xxxxx)

Offline/Temporary tokens#

If you’re on a headless server (CI/CD, SSH), you can generate a session token:

1
kiro auth token --output env
2
# Sets KIRO_SESSION_TOKEN in your environment

This token expires after a configurable duration. For CI/CD pipelines, you typically regenerate it per job.

4. Steering Files: Teaching Kiro How You Code#

Steering files are Kiro’s mechanism for project-level AI configuration. They tell the agent about your code standards, architecture decisions, testing preferences, and security rules.

Create a steering file#

In your project root, create .kiro/steering.md:

1
mkdir -p .kiro

Here’s a practical example for a Node.js/TypeScript project:

1
## Tech Stack
2
- Runtime: Node.js 22 LTS
3
- Language: TypeScript 5.x strict mode
4
- Framework: Hono.js (backend), React 19 with Vite (frontend)
5
- Database: PostgreSQL 16 via Drizzle ORM
6
- Testing: Vitest (unit), Playwright (E2E)
7

8
## Code Standards
9
- Use named exports, not default exports
10
- All functions must have TypeScript return types
11
- Error handling: use Result/Option pattern, not try/catch
12
- Maximum line length: 100 characters
13
- Imports: group by external/internal, sorted alphabetically
14

15
## Architecture Rules
16
- Backend follows clean architecture: routes → services → repositories
17
- Frontend follows feature-based folder structure
18
- API responses follow JSend specification
19
- All database queries must use parameterized statements
20

21
## Testing Requirements
22
- Minimum 80% line coverage for new code
23
- Every API endpoint needs integration tests
24
- Mock external services in unit tests
25
- E2E tests for critical user journeys only (login, checkout, search)
26

27
## Security Constraints
28
- Never log passwords, tokens, or PII
29
- All user input must be validated with Zod schemas
30
- Rate limiting required on all public endpoints
31
- CORS: restrict to known origins only

Global vs. Project steering#

Kiro loads both levels:

File	Scope	Priority
`~/.kiro/steering.md`	All projects	Lower (base)
`.kiro/steering.md`	Current project only	Higher (override)

Global steering is useful for cross-cutting conventions you want everywhere. Project steering can override specific sections.

Reload steering files#

Steering files are read fresh at the start of every session. Changes take effect immediately when you start a new chat or task. There’s no cache to clear.

5. Connecting Your First MCP Server#

Kiro natively supports MCP (Model Context Protocol). During spec generation and task execution, the agent can call external MCP tools.

Via IDE (no config needed)#

Open the Powers tab in the left sidebar
Browse or search for an MCP server (e.g., “GitHub”, “Figma”, “Context7”)
Click Add — follow the auth flow if required
The server is active for all subsequent sessions

Via CLI (`kiro.json`)#

Add MCP servers in your project’s .kiro/kiro.json:

1
{
2
  "mcpServers": {
3
    "github": {
4
      "command": "npx",
5
      "args": ["-y", "@modelcontextprotocol/server-github"],
6
      "env": {
7
        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
8
      }
9
    }
10
  }
11
}

Always use environment variables for tokens, never hardcode secrets in JSON files.

Via CLI (`~/.kiro/kiro.json`)#

Global MCP servers go in your home directory:

1
{
2
  "mcpServers": {
3
    "context7": {
4
      "command": "npx",
5
      "args": ["-y", "context7-mcp"]
6
    }
7
  }
8
}

Global servers are available in every project. Project-level servers merge on top.

Which MCP servers to start with?#

Server	Why First	Token Needed
GitHub	Issue management, PR creation, code review	GitHub PAT (read-only to start)
Context7	Up-to-date library docs (no stale training data)	None (free)
Firecrawl	Web scraping, documentation fetching	API key (free tier available)

6. First Kiro Session#

Open any project in Kiro IDE and try your first spec-driven prompt:

Prompt: “Add a health check endpoint to the API”

Kiro will:

Generate a spec — review and approve it
Create a task plan — you’ll see the dependency graph
Implement — the agent writes real changes to your files
Run tests — if your project has a test framework configured
Ask for feedback — review before considering it done

Try in Vibe Mode first for small changes, then graduate to Spec Mode for new features.

7. CLI Workflow Example#

The CLI is powerful for automation, especially in CI/CD pipelines. Here’s a practical autofix workflow:

1
# In your CI config after a test failure
2
git checkout -b fix/ci-failure
3
kiro --print "Review the latest CI logs, find the failing test, and fix the root cause in the source code"
4
git add -A
5
git commit -m "fix: resolve CI test failure"
6
git push origin fix/ci-failure
7
gh pr create --title "fix: resolve CI test failure" --body "Automated fix via Kiro CLI"

The --print flag outputs the agent’s response to stdout without opening an interactive session — perfect for headless automation.

Troubleshooting Common Issues#

Issue	Likely Cause	Fix
`kiro: command not found`	CLI not in PATH	Reinstall or add `/usr/local/bin` to PATH
`Auth token expired`	Builder ID session expired	Run `kiro auth login` again
MCP server not responding	NPX cache issue	Clear cache: `npx clear-npx-cache`
IDE won’t start	Extension conflict	Launch with `--disable-extensions` to isolate
Steering file ignored	Wrong path or YAML frontmatter	Verify `.kiro/steering.md` exists, check for YAML/Wiki formatting
Slow spec generation	Large project	Increase `.kiro/steering.md` specificity to narrow the agent’s scope

What’s Next#

With Kiro installed and configured, you’re ready for Day 2: Spec-Driven Development Workflow in Practice — where we’ll build a real feature from prompt to pull request using specs, see how to refine requirements, and walk through the exact approval flow.

Series: Practical Kiro — AWS’s Agentic Development Environment. Day 1: Installation & Configuration. Day 2: Spec-Driven Development → coming next.