Como usar o Kiro CLI: guia passo a passo

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 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

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:

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:

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.

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:

kiro-cli chat --list-models

Para deixar um modelo como padrão, configure:

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.

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:

---
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.

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:

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:

{
  "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 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:

{
  "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:

/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:

/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:

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 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 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 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 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 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.