# How to use Kiro CLI: a step-by-step guide

URL: https://agentvera.dev/en/blog/how-to-use-kiro-cli/ · Published: 2026-10-29

How to use Kiro CLI: install kiro-cli, sign in, chat with your code, pick a model, and set up steering files, custom agents, MCP servers and specs. Credits explained.

**In short:**

- Install with the official script, Homebrew or PowerShell, sign in through the browser with GitHub, Google, AWS Builder ID or IAM Identity Center, then run kiro-cli in a project and describe the change.
- Project rules go in .kiro/steering/ or AGENTS.md, custom agents in .kiro/agents/, MCP servers in .kiro/settings/mcp.json, and /spec turns a feature into requirements, design and tasks.
- As of October 2026 Kiro bills in credits: 50 on the free plan, 1,000 on Pro at $20 a month. Auto picks the model for you; each model has its own credit multiplier.

To use Kiro CLI, install it with `curl -fsSL https://cli.kiro.dev/install | bash` (or `brew install kiro-cli` on macOS), sign in through the browser, then run `kiro-cli` inside a project folder and describe what you want. Kiro reads your code, edits files and runs commands, asking before it uses a tool you haven’t trusted. Type `/model` to pick a model, or leave it on Auto and let Kiro choose.

That’s the core loop. This guide covers the rest: signing in, the chat commands you’ll use every day, models and credits, steering files, custom agents, MCP servers, specs, running Kiro in CI, and running it next to other agents. Everything here follows Kiro’s official documentation as of October 2026.

## What Kiro is

Kiro is AWS’s agentic development environment. It comes in several forms that share one account: a desktop IDE, the CLI and Kiro Web. The CLI is the terminal side. It has an interactive chat with a full-screen terminal UI, a headless mode for scripts and CI, and it can act as an agent for editors that speak the Agent Client Protocol (ACP).

What sets Kiro apart from other coding agents is its focus on specs. Before writing code for a feature, Kiro can turn your idea into requirements, a design and a task list, and then work through the tasks. If that approach is new to you, [spec-driven development with AI](/en/blog/spec-driven-development-with-ai/ "Spec-driven development with AI") explains the idea and compares Kiro with the other tools that do it.

A note on versions: the installer gives you Kiro CLI 2.x. Version 3 is an early release you can try with `kiro-cli --v3`. It runs alongside your 2.x install, and your setup stays as it is until you opt in. This guide follows 2.x and points out where V3 differs.

## Step 1: install Kiro CLI

| Platform | Command |
| --- | --- |
| macOS, Linux | `curl -fsSL https://cli.kiro.dev/install \| bash` |
| macOS (Homebrew) | `brew install kiro-cli` |
| Windows 11 (PowerShell) | `irm 'https://cli.kiro.dev/install.ps1' \| iex` |

On Linux you can also use a `.deb` package, an AppImage or a zip file. The CLI needs glibc 2.34 or newer; on older distributions, download the musl variant of the zip. On Windows, run the installer in PowerShell or Windows Terminal; the old Command Prompt isn’t supported.

Check that everything works:

```bash
kiro-cli doctor
```

`kiro-cli update` checks for a new version, and `kiro-cli settings app.disableAutoupdates true` turns automatic updates off. With Homebrew, upgrade with `brew upgrade --greedy kiro-cli`.

## Step 2: sign in

After the install, Kiro opens your browser to sign in. You can choose:

- **GitHub or Google:** the quickest way for individuals.
- **AWS Builder ID:** a free personal AWS identity.
- **AWS IAM Identity Center:** for companies that manage Kiro through AWS. You enter your organization’s start URL and region.
- **An external identity provider:** such as Okta or Microsoft Entra ID, if your company set it up.

You can sign in again at any time with `kiro-cli login`. On a remote machine without a browser, `kiro-cli login --use-device-flow` prints a URL and a code that you open on another device. Device flow works with Builder ID, IAM Identity Center, Google and GitHub, but not with an external identity provider. `kiro-cli whoami` shows who you are signed in as, and `kiro-cli logout` signs you out.

One thing to know: on the free plan and individual plans, Kiro may use your content to improve the service. You can opt out; the Kiro docs explain how.

## Step 3: chat basics

Move into a project and start Kiro:

```bash
cd my-project
kiro-cli
```

The terminal UI is the default. A few things you’ll use constantly:

- **`@path`** adds a file to your message.
- **`!`** at the start of a line runs a shell command directly, for example `!npm test`.
- **Shift+Tab** switches to plan mode, where Kiro thinks a change through before touching code.
- **Shift+Enter** or **Ctrl+J** starts a new line, **Ctrl+O** expands long output, and **Ctrl+C** exits.
- **`/paste`** adds an image from the clipboard.

| Command | What it does |
| --- | --- |
| `/model` | Pick a model |
| `/effort` | Set the reasoning effort |
| `/agent` | Switch to another agent |
| `/context` | Show, add or remove context files |
| `/compact` | Summarize the chat to free up context |
| `/plan` | Plan a change before making it |
| `/spec` | Create or run a spec |
| `/tools` | Trust or untrust tools |
| `/mcp` | Check MCP servers and sign in to them |
| `/usage` | See your plan and remaining credits |
| `/guide` | Ask questions about Kiro CLI itself |
| `/quit` | Exit |

Chats are saved per folder. `kiro-cli chat --resume` continues the latest chat in the current folder, `--resume-picker` lets you choose one, and `--list-sessions` lists them. If you prefer the older line-by-line interface, start with `kiro-cli chat --classic`.

## Step 4: models and credits

Kiro defaults to **Auto**, which routes each request to a suitable model. The docs recommend it for most work. To choose yourself, use `/model` in a chat, or list the models from the shell:

```bash
kiro-cli chat --list-models
```

To make a model your default, save it in the settings:

```bash
kiro-cli settings chat.defaultModel "claude-sonnet-4.6"
```

Kiro bills in credits, and each model has a multiplier. As of October 2026, Claude Opus 5 costs 2.2x, Claude Sonnet 5.5 1.3x, DeepSeek 3.2 0.25x and Qwen3 Coder Next 0.05x. The same task costs very different amounts depending on the model, so check `/usage` now and then.

| Plan (October 2026) | Price | Credits |
| --- | --- | --- |
| Free | $0 | 50 |
| Pro | $20 per user per month | 1,000 |
| Pro+ | $40 per user per month | 2,000 |
| Pro Max | $100 per user per month | 5,000 |
| Power | $200 per user per month | 10,000 |
| Enterprise | Contact sales | Custom |

Paid plans can keep going past their credits at $0.04 per credit, and add-on packs are available. The free plan covers open-weight models and Claude Sonnet 4.5; the newest Claude models need a paid plan. Prices and models change often, so check kiro.dev/pricing before you decide.

## Step 5: steering files and AGENTS.md

Steering files are Markdown files with your project rules: what the product does, the tech stack, where things live, what to avoid. Kiro looks for them in two places:

- **Workspace:** `.kiro/steering/` in the project, committed with the code.
- **Global:** `~/.kiro/steering/`, for rules you want everywhere. If the two disagree, the workspace wins.

The docs suggest starting with three files: `product.md`, `tech.md` and `structure.md`. A steering file is included in every chat by default. Front matter can limit it to certain files:

```markdown
---
inclusion: fileMatch
fileMatchPattern: "components/**/*.tsx"
---

- Components are function components with named exports.
- Styles use CSS modules; no inline styles.
```

There are four inclusion modes: `always` (the default), `fileMatch`, `manual` (you pull the file in with `#file-name`) and `auto` (Kiro decides from the file’s name and description). Kiro CLI 2.x only loads `always` files automatically; V3 supports all four.

Kiro also reads `AGENTS.md` and treats it as an always-included steering file. If your team already keeps one for Codex, opencode or other agents, Kiro uses it as is. [How to write CLAUDE.md and AGENTS.md](/en/blog/claude-md-agents-md/ "How to write CLAUDE.md and AGENTS.md") covers what belongs in it.

## Step 6: custom agents

A custom agent is a saved setup: its own prompt, model, tools and context files. Create one with:

```bash
kiro-cli agent create my-agent
```

Agents live in `.kiro/agents/` (per project) or `~/.kiro/agents/` (global), as JSON or, in V3, Markdown. A short example:

```json
{
  "name": "my-agent",
  "description": "Reviews backend changes",
  "prompt": "You are a careful backend reviewer.",
  "model": "claude-sonnet-4.6",
  "includeMcpJson": true,
  "resources": ["file://.kiro/steering/**/*.md", "file://./ARCHITECTURE.md"]
}
```

Start a chat with it using `kiro-cli --agent my-agent`, switch inside a chat with `/agent`, or make it the default with `kiro-cli settings chat.defaultAgent my-agent`. `kiro-cli agent list` shows your agents and `kiro-cli agent validate` checks a file.

Two pitfalls. First, custom agents don’t include steering files on their own, which is why the example adds `.kiro/steering/**/*.md` to `resources`. Second, agents in a project folder load only after you trust that workspace. The fields for tool permissions differ between 2.x and V3; `/upgrade-agent` converts an agent when you move to V3.

## Step 7: MCP servers

[MCP servers](/en/blog/what-is-mcp-server/ "What is an MCP server") give Kiro new tools: documentation search, a browser, your issue tracker. They go in `mcp.json`, either `.kiro/settings/mcp.json` in the project or `~/.kiro/settings/mcp.json` for all projects:

```json
{
  "mcpServers": {
    "fetch": {
      "command": "uvx",
      "args": ["mcp-server-fetch"],
      "disabled": false
    },
    "my-remote": {
      "url": "https://mcp.example.com/mcp"
    }
  }
}
```

A local server is a command Kiro starts; a remote server is a URL (HTTPS, or HTTP on localhost), with optional `headers` and OAuth sign-in. `kiro-cli mcp add` adds a server from the shell, `kiro-cli mcp list` shows what’s configured and `kiro-cli mcp status` shows whether each one is running. Inside a chat, `/mcp` does the same and handles servers that need you to sign in.

If the same server is defined in several places, an agent’s own setting wins over the workspace file, and the workspace file wins over the global one. Every server adds tools to the context, so turn off the ones you don’t need with `"disabled": true`.

## Step 8: specs

Specs are Kiro’s signature feature. For anything bigger than a quick fix, start one:

```text
/spec new user-invitations
```

Kiro writes three files to `.kiro/specs/user-invitations/`: `requirements.md` with user stories and acceptance criteria in EARS notation (“When X, the system shall Y”), `design.md` with the technical approach, and `tasks.md` with a numbered task list. Read and edit each one before moving on; that review is the whole point. Then let Kiro work through the tasks:

```text
/spec run user-invitations
```

The spec files are plain Markdown, so commit them and they become documentation for the next change. For a smaller change, plan mode (Shift+Tab or `/plan`) gives you a lighter version of the same habit.

## Step 9: headless mode and CI

For scripts and CI, Kiro runs without the chat screen:

```bash
export KIRO_API_KEY=your-key
kiro-cli chat --v3 --no-interactive --trust-tools=read_file,grep_search "Summarize the risky changes in this branch"
```

`--trust-tools` lists the tools Kiro may use without asking (the names here are V3’s, which is why the example uses `--v3`, as the docs’ GitHub Actions example does); `--trust-all-tools` allows everything, so use it only in a sandbox. `--require-mcp-startup` makes the run fail if an MCP server doesn’t start. API keys are available on the Pro, Pro+, Pro Max and Power plans. For editors that support ACP, `kiro-cli acp` runs Kiro as their agent.

## Common pitfalls

- **The installer fails on Windows.** You’re in Command Prompt. Use PowerShell or Windows Terminal, on Windows 11.
- **The binary won’t start on an older Linux.** glibc is older than 2.34. Use the musl zip.
- **Your steering rules are ignored.** The file uses `fileMatch` or `auto` inclusion, which 2.x doesn’t load automatically, or you’re in a custom agent without the steering resource.
- **Credits disappear fast.** An expensive model or a long chat. Check `/usage`, try Auto, and use `/compact`.
- **AWS commands stop working in V3.** V3 removed the built-in AWS tool; use an AWS MCP server instead.
- **No API key option.** Headless mode needs a paid plan.

## Kiro CLI or another agent?

Kiro is a good pick if you like to plan with specs, if your company already manages access through AWS IAM Identity Center, or if you want one bill that covers both premium and cheap open-weight models. It is less of a fit if you want to bring your own API key or run local models; [opencode](/en/blog/how-to-use-opencode/ "How to use opencode") does that with any provider. If you already pay for Claude or ChatGPT, Claude Code or Codex CLI uses that subscription directly. [The best Claude Code alternatives](/en/blog/best-claude-code-alternatives/ "Best Claude Code alternatives") compares the main CLI agents side by side.

## Running Kiro CLI next to other agents

Plenty of teams don’t pick just one. Kiro writes the spec, Claude Code or Codex builds a part, another agent reviews. With terminal tabs that gets hard to follow. AgentVera is a desktop app that runs these CLIs side by side in real terminals, using your own installs and logins. Its [Kiro CLI support](/en/agents/kiro-cli/ "Kiro CLI in AgentVera") works like this:

- **Your Kiro login.** AgentVera opens `kiro-cli chat` in a real terminal. You sign in with `kiro-cli login`; if you’re signed out, the agent’s terminal asks you to sign in.
- **Model and effort per agent.** Leave the model empty for Kiro’s default, or pick one per agent. Effort goes from low to max.
- **Rules from your files.** Kiro CLI has no flag for extra instructions, so lasting instructions come from `AGENTS.md` or rule files in the project.
- **Your mcp.json stays yours.** The MCP servers you add in AgentVera and its browser are merged with your own Kiro `mcp.json` on every launch.
- **Sessions resume.** When you continue an agent, it opens with its session id or the folder’s latest session.
- **Panes, flows and review.** Run Kiro in the [workspace](/en/features/workspace/ "Workspace") grid next to Claude Code or Codex, each in its own git worktree. Kiro agents work in flows, broadcasts and scheduled tasks, and get an automatic code review when a turn ends.

The grid, worktrees, code review and the MCP manager are on the free plan; flows are in Pro and Team. [Download AgentVera](/en/download/ "Download AgentVera") to try it.

## Wrapping up

To use Kiro CLI, install it, sign in, run `kiro-cli` in a project and describe the change. Leave the model on Auto until you have a reason not to, and keep an eye on `/usage`. Put your project rules in `.kiro/steering/` or `AGENTS.md`, your tools in `mcp.json`, and repeat setups in custom agents. For anything bigger than a quick fix, start with `/spec new`: reviewing requirements and a task list before the code is written is what Kiro does best.

## Frequently asked questions

**Is Kiro CLI free?** The CLI is free to install, and the free plan includes 50 credits. As of October 2026 paid plans start at $20 a month for 1,000 credits (Pro), with Pro+, Pro Max and Power above it. Extra usage costs $0.04 per credit.

**What is the difference between Kiro IDE and Kiro CLI?** They are two ways into the same Kiro: the IDE is a desktop editor, the CLI is a chat in your terminal. Both use your Kiro account and credits, and both understand steering files, specs and MCP servers in the .kiro folder.

**Does Kiro CLI read AGENTS.md?** Yes. Kiro treats AGENTS.md like a steering file that is always included. Kiro’s own steering files live in .kiro/steering/ in the project and in ~/.kiro/steering/ for global rules.

**What is Kiro CLI V3?** An early release of the next version. You try it with kiro-cli --v3 and it runs alongside your 2.x install, which stays unchanged until you opt in. It shares its engine with the Kiro IDE and adds things like /rewind, hooks and a spec agent.

**Can I use Kiro CLI in CI?** Yes. Run kiro-cli chat --no-interactive with a prompt and set KIRO_API_KEY. API keys are available on the Pro, Pro+, Pro Max and Power plans, not on the free plan.

---

**About AgentVera.** AgentVera is a desktop app for macOS, Windows and Linux, built by Solviera Teknoloji. It runs 18 AI coding agents (Claude Code, Codex, Gemini CLI, Copilot, Cursor, Antigravity, opencode, Hermes, Qwen Code, Kimi Code, Kiro, Amp, Droid, Goose, Vibe, Crush, Aider, Cline) side by side, per project, in real terminals with the user's own CLI installs and logins. The free plan has unlimited agents. Download: https://agentvera.dev/en/download/ · Pricing: https://agentvera.dev/en/pricing/