# Como usar o Kiro CLI: guia passo a passo

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

Como usar o Kiro CLI: instale o kiro-cli, faça login, converse com seu código, escolha o modelo e configure steering, agentes, servidores MCP e specs. Com créditos.

**Resumo:**

- Instale com o script oficial, Homebrew ou PowerShell, faça login no navegador com GitHub, Google, AWS Builder ID ou IAM Identity Center, depois rode kiro-cli no seu projeto e descreva a mudança.
- As regras do projeto ficam em .kiro/steering/ ou no AGENTS.md, agentes próprios em .kiro/agents/ e servidores MCP em .kiro/settings/mcp.json; /spec transforma uma funcionalidade em requisitos, design e tarefas.
- Em outubro de 2026, o Kiro cobra em créditos: 50 no plano gratuito e 1.000 no Pro por US$ 20 por mês. O Auto escolhe o modelo para você, e cada modelo tem seu próprio multiplicador de créditos.

Para usar o Kiro CLI, instale com `curl -fsSL https://cli.kiro.dev/install | bash` (ou `brew install kiro-cli` no macOS), faça login no navegador, rode `kiro-cli` dentro da pasta de um projeto e descreva o que você quer. O Kiro lê seu código, edita arquivos e executa comandos, e pergunta antes de usar qualquer ferramenta em que você ainda não confia. Digite `/model` para escolher um modelo, ou deixe no Auto e o Kiro decide.

Esse é o ciclo básico. Este guia cobre o resto: login, os comandos de chat do dia a dia, modelos e créditos, arquivos de steering, agentes próprios, servidores MCP, specs, o Kiro em CI e o Kiro ao lado de outros agentes. Tudo segue a documentação oficial do Kiro em outubro de 2026.

## O que é o Kiro

O Kiro é o ambiente de desenvolvimento agêntico da AWS. Ele vem em várias formas que compartilham a mesma conta: um IDE desktop, a CLI e o Kiro Web. A CLI é a parte de terminal. Ela oferece um chat interativo com uma interface de terminal em tela cheia, um modo headless para scripts e CI, e pode funcionar como agente em editores que falam o Agent Client Protocol (ACP).

O que diferencia o Kiro de outros agentes de código é o foco em specs. Antes de escrever o código de uma funcionalidade, o Kiro pode transformar sua ideia em requisitos, um design e uma lista de tarefas, e depois ir cumprindo as tarefas. Se a abordagem é nova para você, [Desenvolvimento orientado por especificação com IA](/pt/blog/spec-driven-development-with-ai/ "Desenvolvimento orientado por especificação com IA") explica a ideia e compara o Kiro com outras ferramentas que fazem isso.

Uma observação sobre versões: o instalador entrega o Kiro CLI 2.x. A versão 3 é uma versão inicial que você pode testar com `kiro-cli --v3`. Ela roda ao lado da sua instalação 2.x, e sua configuração continua como está até você trocar. Este guia segue a 2.x e avisa onde a V3 é diferente.

## Passo 1: instale o Kiro CLI

| Plataforma | Comando |
| --- | --- |
| 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` |

No Linux também há um pacote `.deb`, um AppImage e um zip. A CLI precisa de glibc 2.34 ou mais recente; em distribuições mais antigas, use a variante musl do zip. No Windows, rode o instalador no PowerShell ou no Windows Terminal; o antigo Prompt de Comando não é suportado.

Confira se está tudo funcionando:

```bash
kiro-cli doctor
```

`kiro-cli update` procura uma versão nova, e `kiro-cli settings app.disableAutoupdates true` desliga as atualizações automáticas. Se instalou com Homebrew, atualize com `brew upgrade --greedy kiro-cli`.

## Passo 2: faça login

Depois da instalação, o Kiro abre o navegador para o login. As opções são:

- **GitHub ou Google:** o caminho mais rápido para quem usa sozinho.
- **AWS Builder ID:** uma identidade AWS pessoal e gratuita.
- **AWS IAM Identity Center:** para empresas que gerenciam o Kiro pela AWS. Você informa a URL de início e a região da sua organização.
- **Um provedor de identidade externo:** como Okta ou Microsoft Entra ID, se a sua empresa configurou.

Use `kiro-cli login` para entrar de novo quando quiser. Numa máquina remota sem navegador, `kiro-cli login --use-device-flow` mostra uma URL e um código para abrir em outro dispositivo. O device flow funciona com Builder ID, IAM Identity Center, Google e GitHub, mas não com um provedor de identidade externo. `kiro-cli whoami` mostra com qual conta você está logado, e `kiro-cli logout` encerra a sessão.

Vale saber: no plano gratuito e nos planos individuais, o Kiro pode usar seu conteúdo para melhorar o serviço. Dá para recusar; a documentação do Kiro explica como.

## Passo 3: o básico do chat

Entre em um projeto e inicie o Kiro:

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

A interface de terminal é o padrão. Algumas coisas você vai usar o tempo todo:

- **`@caminho`** anexa um arquivo à sua mensagem.
- **`!`** no início da linha executa um comando de shell direto, por exemplo `!npm test`.
- **Shift+Tab** muda para o modo plano, em que o Kiro pensa a mudança antes de mexer no código.
- **Shift+Enter** ou **Ctrl+J** quebra a linha, **Ctrl+O** expande saídas longas e **Ctrl+C** sai.
- **`/paste`** cola uma imagem da área de transferência.

| Comando | O que faz |
| --- | --- |
| `/model` | Escolher o modelo |
| `/effort` | Ajustar o esforço de raciocínio |
| `/agent` | Trocar para outro agente |
| `/context` | Ver, adicionar ou remover arquivos de contexto |
| `/compact` | Resumir o chat para liberar contexto |
| `/plan` | Planejar uma mudança antes de construir |
| `/spec` | Criar ou executar uma spec |
| `/tools` | Confiar ou deixar de confiar em ferramentas |
| `/mcp` | Verificar servidores MCP e fazer login neles |
| `/usage` | Ver seu plano e os créditos restantes |
| `/guide` | Tirar dúvidas sobre o próprio Kiro CLI |
| `/quit` | Sair |

Os chats ficam salvos por pasta. `kiro-cli chat --resume` retoma o último chat da pasta atual, `--resume-picker` deixa você escolher um e `--list-sessions` lista todos. Se prefere a interface antiga, linha a linha, inicie com `kiro-cli chat --classic`.

## Passo 4: modelos e créditos

Por padrão, o Kiro usa o **Auto**, que encaminha cada pedido para um modelo adequado. A documentação recomenda o Auto para a maioria das tarefas. Para escolher você mesmo, digite `/model` no chat ou liste os modelos pelo shell:

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

Para deixar um modelo como padrão, configure:

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

O Kiro cobra em créditos, e cada modelo tem um multiplicador. Em outubro de 2026, o Claude Opus 5 conta 2,2x, o Claude Sonnet 5.5 1,3x, o DeepSeek 3.2 0,25x e o Qwen3 Coder Next 0,05x. A mesma tarefa pode custar bem diferente dependendo do modelo, então dê uma olhada no `/usage` de vez em quando.

| Plano (outubro de 2026) | Preço | Créditos |
| --- | --- | --- |
| Free | US$ 0 | 50 |
| Pro | US$ 20 por usuário por mês | 1.000 |
| Pro+ | US$ 40 por usuário por mês | 2.000 |
| Pro Max | US$ 100 por usuário por mês | 5.000 |
| Power | US$ 200 por usuário por mês | 10.000 |
| Enterprise | Fale com vendas | Personalizado |

Os planos pagos podem continuar além dos créditos a US$ 0,04 por crédito, e existem pacotes extras. O plano gratuito cobre modelos open-weight e o Claude Sonnet 4.5; os modelos Claude mais novos exigem um plano pago. Preços e modelos mudam com frequência, então confira kiro.dev/pricing antes de decidir.

## Passo 5: arquivos de steering e AGENTS.md

Arquivos de steering são arquivos Markdown com as regras do seu projeto: o que o produto faz, a stack, onde fica cada coisa, o que evitar. O Kiro procura esses arquivos em dois lugares:

- **Workspace:** `.kiro/steering/` dentro do projeto, versionado junto com o código.
- **Global:** `~/.kiro/steering/`, para regras que valem em todo lugar. Se houver conflito, o workspace vence.

A documentação sugere começar com três arquivos: `product.md`, `tech.md` e `structure.md`. Por padrão, um arquivo de steering entra em todo chat. Você pode limitá-lo a certos arquivos com front matter:

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

- Componentes são funcionais e usam exports nomeados.
- Os estilos usam CSS modules; nada de estilo inline.
```

Há quatro modos: `always` (o padrão), `fileMatch`, `manual` (você inclui com `#nome-do-arquivo`) e `auto` (o Kiro decide pelo nome e pela descrição do arquivo). O Kiro CLI 2.x só carrega automaticamente os arquivos `always`; a V3 suporta os quatro.

O Kiro também lê o `AGENTS.md` e o trata como um arquivo de steering sempre incluído. Se o seu time já mantém um para o Codex, o opencode ou outros agentes, o Kiro usa do jeito que está. Para saber o que colocar nele, veja [Boas práticas de CLAUDE.md](/pt/blog/claude-md-agents-md/ "Boas práticas de CLAUDE.md").

## Passo 6: agentes próprios

Um agente próprio é uma configuração salva com seu próprio prompt, modelo, ferramentas e arquivos de contexto. Crie um com:

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

Os agentes ficam em `.kiro/agents/` (por projeto) ou `~/.kiro/agents/` (globais), em JSON ou, na V3, também em Markdown. Um exemplo curto:

```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"]
}
```

Abra um chat com ele usando `kiro-cli --agent my-agent`, troque dentro do chat com `/agent` ou torne-o o padrão com `kiro-cli settings chat.defaultAgent my-agent`. `kiro-cli agent list` mostra seus agentes e `kiro-cli agent validate` verifica um arquivo.

Dois detalhes. Primeiro, agentes próprios não incluem os arquivos de steering sozinhos; por isso o exemplo adiciona `.kiro/steering/**/*.md` em `resources`. Segundo, agentes da pasta de um projeto só carregam depois que você confia naquele workspace. Os campos de permissão de ferramentas mudam entre a 2.x e a V3; `/upgrade-agent` converte um agente quando você passa para a V3.

## Passo 7: servidores MCP

[Servidores MCP](/pt/blog/what-is-mcp-server/ "O que é um servidor MCP?") dão novas ferramentas ao Kiro: busca em documentação, um navegador, seu gerenciador de issues. Eles ficam num arquivo `mcp.json`, seja `.kiro/settings/mcp.json` no projeto ou `~/.kiro/settings/mcp.json` para todos os projetos:

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

Um servidor local é um comando que o Kiro inicia; um servidor remoto é uma URL (HTTPS, ou HTTP em localhost), com `headers` opcionais e login via OAuth. No shell, `kiro-cli mcp add` adiciona um servidor, `kiro-cli mcp list` mostra a configuração e `kiro-cli mcp status` diz se cada servidor está rodando. No chat, `/mcp` faz o mesmo e cuida dos servidores que pedem login.

Se o mesmo servidor estiver definido em vários lugares, a configuração de um agente vence o arquivo do workspace, e o do workspace vence o global. Cada servidor adiciona ferramentas ao contexto, então desative os que você não usa com `"disabled": true`.

## Passo 8: specs

As specs são a marca registrada do Kiro. Para qualquer coisa maior que uma correção rápida, crie uma:

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

O Kiro escreve três arquivos em `.kiro/specs/user-invitations/`: `requirements.md` com histórias de usuário e critérios de aceitação em notação EARS (“Quando X, o sistema deve Y”), `design.md` com a abordagem técnica e `tasks.md` com uma lista numerada de tarefas. Leia e corrija cada arquivo antes de seguir; essa revisão é justamente o ponto. Depois, deixe o Kiro cumprir as tarefas:

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

Os arquivos de spec são Markdown comum. Versionados, viram documentação para a próxima mudança. Para mudanças menores, o modo plano (Shift+Tab ou `/plan`) oferece uma versão mais leve do mesmo hábito.

## Passo 9: modo headless e CI

Para scripts e CI, rode o Kiro sem a interface de chat:

```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` lista as ferramentas que o Kiro pode usar sem perguntar (os nomes aqui são da V3, por isso o exemplo usa `--v3`, como o exemplo de GitHub Actions da documentação). `--trust-all-tools` libera tudo, então use só em sandbox. `--require-mcp-startup` faz a execução falhar se um servidor MCP não iniciar. As chaves de API estão disponíveis nos planos Pro, Pro+, Pro Max e Power. Para editores com suporte a ACP, `kiro-cli acp` roda o Kiro como agente deles.

## Armadilhas comuns

- **O instalador falha no Windows.** Você está no Prompt de Comando. Use o PowerShell ou o Windows Terminal no Windows 11.
- **O binário não abre num Linux antigo.** A glibc é anterior à 2.34. Use o zip musl.
- **Suas regras de steering são ignoradas.** O arquivo usa `fileMatch` ou `auto`, que a 2.x não carrega automaticamente, ou você está num agente próprio sem o recurso de steering.
- **Os créditos acabam rápido.** Um modelo caro ou um chat longo. Confira o `/usage`, teste o Auto e use `/compact`.
- **Os comandos da AWS pararam na V3.** A V3 removeu a ferramenta AWS embutida; use um servidor MCP da AWS no lugar.
- **Não aparece a opção de chave de API.** O modo headless exige um plano pago.

## Kiro CLI ou outro agente?

O Kiro é uma boa escolha se você gosta de planejar com specs, se sua empresa já gerencia o acesso pelo AWS IAM Identity Center ou se você quer uma só conta para modelos premium e modelos open-weight baratos. É uma escolha pior se você quer usar sua própria chave de API ou modelos locais; o [opencode](/pt/blog/how-to-use-opencode/ "Como usar o opencode") faz isso com qualquer provedor. Se você já paga Claude ou ChatGPT, o Claude Code ou o Codex CLI usam essa assinatura diretamente. [Melhores alternativas ao Claude Code](/pt/blog/best-claude-code-alternatives/ "Melhores alternativas ao Claude Code") compara os principais agentes de CLI lado a lado.

## Rodando o Kiro CLI ao lado de outros agentes

Muitos times não ficam com um agente só. O Kiro escreve a spec, o Claude Code ou o Codex constrói uma parte e outro agente revisa. Com abas de terminal, isso vira bagunça rápido. O AgentVera é um app desktop que roda essas CLIs lado a lado em terminais reais, com suas próprias instalações e logins. O [suporte ao Kiro CLI](/pt/agents/kiro-cli/ "Kiro CLI no AgentVera") funciona assim:

- **Seu login do Kiro.** O AgentVera abre o `kiro-cli chat` num terminal real. Você faz login com `kiro-cli login`; se não estiver logado, o terminal do agente pede que você entre.
- **Modelo e esforço por agente.** Deixe o modelo vazio para usar o padrão do Kiro ou escolha um por agente. O esforço vai de baixo a máximo.
- **Regras vindas dos seus arquivos.** O Kiro CLI não tem flag de instruções extras, então as instruções permanentes vêm do `AGENTS.md` ou dos arquivos de regras do projeto.
- **Seu mcp.json continua seu.** Os servidores MCP que você adiciona no AgentVera e o navegador do AgentVera são mesclados com o seu próprio `mcp.json` do Kiro a cada inicialização.
- **As sessões continuam.** Ao retomar um agente, ele abre com o ID da sessão ou com a última sessão da pasta.
- **Painéis, flows e revisão.** Rode o Kiro na grade do [workspace](/pt/features/workspace/ "Workspace") ao lado do Claude Code ou do Codex, cada um no seu próprio git worktree. Agentes Kiro funcionam em flows, mensagens em massa e tarefas agendadas, e recebem revisão de código automática ao fim de cada turno.

A grade, os worktrees, a revisão de código e o gerenciador de MCP estão no plano gratuito; os flows, no Pro e no Team. [Baixe o AgentVera](/pt/download/ "Baixar o AgentVera") para experimentar.

## Conclusão

Para usar o Kiro CLI, instale, faça login, rode `kiro-cli` num projeto e descreva a mudança. Deixe o modelo no Auto até ter um motivo para trocar e fique de olho no `/usage`. As regras do projeto vão em `.kiro/steering/` ou no `AGENTS.md`, as ferramentas no `mcp.json` e as configurações que se repetem em agentes próprios. Para qualquer coisa maior que uma correção rápida, comece com `/spec new`: revisar requisitos e uma lista de tarefas antes de o código existir é o que o Kiro faz de melhor.

## Perguntas frequentes

**O Kiro CLI é gratuito?** A CLI não custa nada, e o plano gratuito inclui 50 créditos. Em outubro de 2026, os planos pagos começam em US$ 20 por mês com 1.000 créditos (Pro), com Pro+, Pro Max e Power acima. O uso extra custa US$ 0,04 por crédito.

**Qual a diferença entre o Kiro IDE e o Kiro CLI?** São duas formas de usar o mesmo Kiro: o IDE é um editor desktop e a CLI é um chat no terminal. Os dois usam sua conta e seus créditos do Kiro e entendem os arquivos de steering, as specs e os servidores MCP da pasta .kiro.

**O Kiro CLI lê o AGENTS.md?** Sim. O Kiro trata o AGENTS.md como um arquivo de steering sempre incluído. Os arquivos de steering próprios do Kiro ficam em .kiro/steering/ dentro do projeto e em ~/.kiro/steering/ para regras globais.

**O que é o Kiro CLI V3?** Uma versão inicial da próxima geração. Experimente com kiro-cli --v3; ela roda ao lado da sua instalação 2.x, que continua igual até você trocar. Ela compartilha o motor com o Kiro IDE e traz, entre outras coisas, /rewind, hooks e um agente de specs.

**Dá para usar o Kiro CLI em CI?** Sim. Rode kiro-cli chat --no-interactive com um prompt e defina KIRO_API_KEY. As chaves de API estão disponíveis nos planos Pro, Pro+, Pro Max e Power, não no gratuito.

---

**Sobre o AgentVera.** AgentVera é um app desktop para macOS, Windows e Linux, desenvolvido pela Solviera Teknoloji. Ele roda 18 agentes de programação com IA (Claude Code, Codex, Gemini CLI, Copilot, Cursor, Antigravity, opencode, Hermes, Qwen Code, Kimi Code, Kiro, Amp, Droid, Goose, Vibe, Crush, Aider, Cline) lado a lado, por projeto, em terminais reais com as instalações e logins de CLI do próprio usuário. O plano gratuito tem agentes ilimitados. Baixar: https://agentvera.dev/pt/download/ · Preços: https://agentvera.dev/pt/pricing/