Kiro CLI: guia prático do prompt ao deploy no terminal

TL;DR

Instala com um curl, entra num projeto e roda kiro-cli. Mesmo agente, mesmo cérebro do IDE, só que no terminal onde você já vive.
A sessão interativa tem slash commands para tudo: /save, /load, /usage, /model, /mcp, /agent, ! para shell, ctrl-j para multi-linha e ctrl-k para busca fuzzy.
O contexto persiste por diretório: você fecha o terminal, volta amanhã, dá /load e retoma de onde parou.
Agentes customizados são JSON com tools/allowedTools — least-privilege de verdade: o agente só roda sem pedir aprovação o que você liberou.
MCP se adiciona por comando (kiro-cli mcp add) ou por mcp.json, e o planning agent explora o código e monta um plano sem tocar em nada até você aprovar.

O terminal nunca foi o problema

Se você passa o dia entre git, ssh, kubectl e um vim ocasional, sair do terminal para conversar com um agente numa aba de navegador é atrito puro. Você perde o pwd, perde o histórico, perde o fluxo. E a maioria das ferramentas de IA assume que você quer uma UI bonita — quando o que você quer é ficar onde já está.

O Kiro CLI resolve isso sem abrir mão de nada. É a mesma assinatura do Kiro IDE — specs, steering, hooks, code intelligence, o agente Auto — empacotada num binário que roda no seu shell. Você não troca de contexto: você adiciona um interlocutor ao contexto que já tem.

Este guia é a rota completa: instalar, abrir a primeira sessão, dominar os slash commands, entender como o contexto sobrevive entre sessões, criar um agente sob medida, plugar servidores MCP e usar o planning agent para explorar antes de escrever. Tudo com o comando de verdade — sem sintaxe inventada.

O melhor agente de terminal é o que não te obriga a sair do terminal para usá-lo.

Instalação e primeiro uso

A instalação é um único comando. O script detecta a plataforma e coloca o binário no PATH:

curl -fsSL https://cli.kiro.dev/install | bash

Depois é só entrar num projeto e chamar o CLI. Ele abre a sessão interativa já com o diretório atual como contexto de trabalho:

cd meu-projeto
kiro-cli

A partir daí você está numa conversa. Digite em linguagem natural o que quer — “adicione paginação no endpoint /users”, “por que esse teste está flaky?”, “explique o fluxo de autenticação” — e o agente lê os arquivos, propõe mudanças e executa comandos (pedindo aprovação quando faz sentido). Como é o mesmo agente do IDE, ele enxerga .kiro/specs/, .kiro/steering/ e .kiro/hooks/ se existirem no projeto.

Sessão interativa e slash commands

Dentro da sessão, os slash commands controlam tudo que não é conversa. Eles são a diferença entre “um chat no terminal” e “um ambiente de trabalho”. Aqui estão os principais:

Comando	O que faz
`/save`	Salva a conversa atual (contexto associado ao diretório)
`/load`	Restaura uma conversa salva anteriormente
`/usage`	Mostra o consumo de créditos da sessão
`/model`	Troca o modelo (Auto, Sonnet, Haiku, Opus…)
`/mcp`	Lista os servidores MCP carregados
`/agent`	Gerencia agentes (criar, trocar, listar)
`!`	Executa um comando shell direto, sem sair da sessão
`ctrl-j`	Entra em modo multi-linha (prompt longo, cola de código)
`ctrl-k`	Busca fuzzy (histórico e navegação rápida)
`/editor`	Abre seu `$EDITOR` para compor um prompt longo

Além desses, existem /prompts, /help, /issue e /quit. Um transcript ilustrativo de uma sessão típica:

$ cd api-pagamentos && kiro-cli

kiro › /model
  ● Auto (padrão)   Sonnet 4.6   Haiku 4.5   Opus 4.8
  → selecionado: Auto

kiro › explique como o retry de webhook está implementado

  Li src/webhooks/retry.ts e src/queue/worker.ts. O retry usa
  backoff exponencial (base 2s, teto 5 tentativas) e persiste o
  estado em Redis. Falhas após a 5ª tentativa vão para a DLQ...

kiro › ! git status
  On branch feat/webhook-idempotency
  Changes not staged for commit:
    modified:   src/webhooks/retry.ts

kiro › /usage
  Sessão atual: 3,42 créditos consumidos

kiro › /save
  Conversa salva para o diretório atual.

kiro › /quit

Repare no ! git status: você não precisa abrir outro terminal para rodar um comando shell — o ! executa e devolve a saída na mesma sessão. E o /save no fim é o que garante que essa investigação toda não evapora quando você fecha o terminal.

No terminal, o slash command é o seu painel de controle. ! para o shell, /model para o cérebro, /save para a memória.

Contexto por diretório

Este é o recurso que muda a ergonomia do dia a dia. O Kiro CLI associa o contexto da conversa ao diretório onde você está. Isso significa que a memória de trabalho é naturalmente segmentada por projeto: a conversa que você teve no api-pagamentos não se mistura com a do frontend-web.

O fluxo é direto:

cd api-pagamentos
kiro-cli
# ... investigação longa sobre o bug de idempotência ...
# dentro da sessão: /save
# fecha o terminal, vai almoçar, volta

cd api-pagamentos
kiro-cli
# dentro da sessão: /load
# a conversa anterior volta com todo o contexto

Além da persistência automática por diretório, você tem controle explícito com /save e /load: exporta o estado da conversa para um JSON e o recupera depois. Assim você constrói um histórico de investigações por projeto — cada codebase carrega sua própria linha de raciocínio. E, para trazer arquivos específicos ao contexto, o Kiro usa referências como #[[file:caminho/arquivo]] (o mesmo mecanismo do steering), ancorando o agente em artefatos vivos do repositório em vez de depender só do que ele já leu na conversa.

Na prática, isso troca o “recomeço do zero toda manhã” por uma continuidade real. O contexto persistido é o mesmo princípio das specs e do steering: a intenção e o raciocínio moram junto do projeto, não numa aba de chat que some.

Agentes customizados

O agente padrão é ótimo para uso geral, mas quando você tem um contexto recorrente — “sempre trabalhando só no backend”, “sempre revisando segurança” — vale criar um agente sob medida. Um custom agent define quais ferramentas existem, quais rodam sem pedir aprovação, quais recursos entram no contexto e qual prompt e modelo usar.

Você cria de três formas:

# assistido por IA (dentro da sessão) — descreve o que quer e ele monta o JSON
kiro › /agent create

# manual, dentro da sessão
kiro › /agent create backend-specialist --manual

# pelo terminal, fora da sessão
kiro-cli agent create backend-specialist

Também dá para criar a partir de um agente base (--from <base>) e escolher onde salvar (--directory workspace|global|/path). Agentes de workspace ficam em .kiro/agents/; os globais em ~/.kiro/agents/.

O JSON de configuração tem esta cara:

{
  "name": "backend-specialist",
  "description": "Especialista em backend Node/TS. Só lê e escreve em src/.",
  "tools": ["read", "write", "execute_bash"],
  "allowedTools": ["read"],
  "resources": [
    "file://README.md",
    "file://.kiro/steering/**/*.md",
    "skill://.kiro/skills/**/SKILL.md"
  ],
  "prompt": "Você é um especialista em backend. Siga o steering do projeto. Nunca altere arquivos fora de src/.",
  "model": "claude-sonnet-4",
  "mcpServers": {
    "fetch": { "command": "fetch3.1", "args": [] }
  },
  "includeMcpJson": false
}

A distinção mais importante está em tools versus allowedTools. O campo tools lista o que o agente pode usar; allowedTools lista o que ele executa sem pedir confirmação. Tudo que está em tools mas fora de allowedTools para e pede sua aprovação antes de rodar. No exemplo acima, o agente lê à vontade (read é auto-aprovado), mas write e execute_bash exigem seu OK. Isso é least-privilege na prática: você concede autonomia só onde o risco é baixo.

Para trocar de agente no meio da sessão, use /agent swap. Para já iniciar o CLI com um agente específico:

kiro-cli --agent backend-specialist

O campo resources (file://, skill://) injeta arquivos vivos no contexto do agente — steering, README, skills — então o agente já nasce sabendo as convenções do projeto sem você repetir nada.

MCP no CLI

O Model Context Protocol conecta o agente a ferramentas e fontes de dados externas — documentação da AWS, APIs internas, bancos de dados. No CLI, você adiciona um servidor de duas maneiras.

Pela linha de comando, com kiro-cli mcp add:

kiro-cli mcp add \
  --name "awslabs.aws-documentation-mcp-server" \
  --scope global \
  --command "uvx" \
  --args "awslabs.aws-documentation-mcp-server@latest" \
  --env "FASTMCP_LOG_LEVEL=ERROR"

Ou editando o mcp.json diretamente. Ele vive em <root>/.kiro/settings/mcp.json (workspace) ou ~/.kiro/settings/mcp.json (user):

{
  "mcpServers": {
    "aws-docs": {
      "command": "uvx",
      "args": ["awslabs.aws-documentation-mcp-server@latest"],
      "env": { "FASTMCP_LOG_LEVEL": "ERROR" },
      "disabled": false
    },
    "http-server": {
      "type": "http",
      "url": "https://api.example.com/mcp",
      "oauth": { "redirectUri": "127.0.0.1:8080", "oauthScopes": ["read"] }
    }
  }
}

O primeiro servidor roda um processo local via uvx; o segundo é um servidor HTTP remoto com fluxo OAuth. Dentro da sessão, o slash command /mcp lista todos os servidores carregados e o estado de cada um — útil para confirmar que a conexão subiu antes de contar com a ferramenta.

Planning agent: explorar sem quebrar nada

Nem toda tarefa começa com “escreva código”. Muitas vezes você precisa entender um sistema antes de mexer nele — e é aí que o planning agent entra. Ele explora o codebase e monta um plano de ação sem modificar nenhum arquivo. Você lê o plano, aprova (ou ajusta), e só então ele executa.

Isso é valioso em duas situações. Primeira: código legado ou desconhecido, onde uma mudança apressada pode ter efeito cascata. O planning agent mapeia dependências e propõe uma ordem segura antes de tocar em algo. Segunda: mudanças grandes, onde você quer revisar a estratégia inteira antes de gerar dezenas de arquivos — evitando o clássico “aprovar 300 linhas que você não acompanhou”.

O ganho é de controle: você separa a fase de raciocínio da fase de execução. O plano é revisável como qualquer artefato, e a execução só acontece com sua chancela. É o mesmo princípio das specs, aplicado a uma exploração pontual no terminal.

Mesma assinatura do IDE, agente Auto

Vale reforçar o que o CLI não é: não é um produto separado com features amputadas. É a mesma assinatura do Kiro — IDE, CLI, web e IDEs via ACP compartilham o cérebro. O agente Auto (padrão) mistura modelos de fronteira e especializados, com cache e roteamento por intenção, para equilibrar qualidade e custo automaticamente. Você pode fixar um modelo com /model quando quiser, mas o Auto costuma ser a escolha certa.

E os créditos são os mesmos: não existe preço separado para o CLI. O consumo independe da interface — o que você gasta numa tarefa no terminal é o que gastaria no IDE. Uma tarefa que custa X no Auto custa cerca de 1,3X no Sonnet 4.6, então o Auto tende a ser mais econômico para a maioria dos casos.

Principais aprendizados

Um comando instala, um comando abre. curl … | bash, depois cd projeto && kiro-cli. Você fica no terminal.
Slash commands são o painel de controle: /save//load para memória, /model para o modelo, /mcp e /agent para infra, ! para shell, ctrl-j/ctrl-k//editor para ergonomia de input.
Contexto por diretório transforma cada projeto numa linha de raciocínio contínua — nada de recomeçar do zero.
Custom agents com tools vs allowedTools dão least-privilege real: autonomia onde o risco é baixo, aprovação onde não é.
MCP entra por kiro-cli mcp add ou mcp.json; o planning agent separa raciocínio de execução, deixando você aprovar o plano antes de qualquer mudança.

Referências

Kiro CLI (visão geral): https://kiro.dev/cli/
Kiro CLI — documentação: https://kiro.dev/docs/cli/
Referência de comandos do CLI: https://kiro.dev/docs/cli/reference/cli-commands
Slash commands: https://kiro.dev/docs/cli/reference/slash-commands/
Custom agents (criação): https://kiro.dev/docs/cli/custom-agents/creating/
MCP no CLI: https://kiro.dev/docs/cli/mcp/
Permissões e ferramentas nativas: https://kiro.dev/docs/cli/chat/permissions/
Planning agent: https://kiro.dev/docs/cli/chat/planning-agent/

Este artigo foi publicado originalmente no Medium. Preços, nomes de modelos e detalhes de produto refletem o estado do Kiro em meados de 2026 e podem mudar — confirme em kiro.dev antes de tomar decisões. Este é um conteúdo educacional independente, sem vínculo oficial com a AWS.

Tags: kiro, cli, aws, terminal, mcp

Publicado originalmente em prompt.victorbatistax.com. Se você chegou por outra plataforma, esta é a versão canônica.