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 interface padrão agora é uma Terminal UI rica: markdown com syntax highlight, painéis interativos, progresso das ferramentas e atalhos de teclado. Quer a antiga? kiro-cli --classic.
Slash commands são o painel de controle: /chat (sessões), /context, /model, /agent, /mcp, /tools, /plan (ou Shift+Tab), ! para shell e @arquivo para referenciar arquivos.
Sessões persistem por diretório e são salvas a cada turno: feche o terminal, volte amanhã e retome com kiro-cli chat --resume (ou /chat para escolher qual).
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 entra por kiro-cli mcp add ou mcp.json; o modo plano (/plan) explora e propõe sem tocar em nada até você aprovar.
Fora do chat: kiro-cli translate (linguagem natural → comando shell), /spawn para rodar agentes em paralelo e kiro-cli inline para sugestões (ghost text) no shell.

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
`/chat`	Gerencia sessões: `new`, `resume`, `save <arquivo>`, `load <arquivo>` (com seletor fuzzy)
`/context`	Mostra e edita o contexto, com % de tokens por arquivo (`add`, `remove`, `show`, `clear`)
`/model`	Troca o modelo ativo
`/effort`	Ajusta o nível de raciocínio (`low`/`medium`/`high`/`xhigh`/`max`)
`/agent`	Troca de agente
`/mcp`	Lista servidores MCP e o status de cada um
`/tools`	Vê e reseta permissões de ferramentas (`/tools reset` limpa os trusts)
`/plan`	Entra no modo plano (também `Shift+Tab`)
`/spawn`	Dispara uma sessão de agente em paralelo (subagente)
`/rewind`	Volta a conversa a um turno anterior para explorar outro caminho
`/editor`	Abre seu `$EDITOR` para compor um prompt longo
`!`	Executa um comando shell direto, com saída em tempo real

Ainda há /help, /prompts, /knowledge, /code, /hooks, /theme, /settings, /transcript (ou Ctrl+T), /copy, /usage e /exit. Muitos deles (/help, /context, /tools, /mcp…) abrem como painéis em overlay, pesquisáveis, que você fecha com Esc. 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 › /chat save investigacao-webhook
  Sessão salva.

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 (em tempo real) na mesma sessão. E como a sessão é salva automaticamente a cada turno, essa investigação não evapora quando você fecha o terminal — você retoma com kiro-cli chat --resume.

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

Terminal UI: painéis, atalhos e temas

Nas versões recentes, a Terminal UI passou a ser a interface padrão do kiro-cli — markdown renderizado com syntax highlight, painéis interativos e progresso visual de cada ferramenta. Se preferir a interface antiga, use kiro-cli --classic (ou fixe com kiro-cli settings chat.ui "classic"). A precedência é: flag --tui/--classic → variável KIRO_CHAT_UI → setting chat.ui → padrão tui.

O que muda no dia a dia:

Painéis em overlay: /help, /context, /tools, /mcp, /code, /knowledge abrem sobre a conversa, pesquisáveis, e fecham com Esc.
Saída colapsável: Ctrl+O alterna entre resumo e saída completa de cada ferramenta; comandos de shell transmitem linha a linha.
Atalhos que importam: Shift+Tab entra no modo plano · Ctrl+T abre o transcript no $PAGER · Ctrl+X mostra a bandeja de atividade · Ctrl+R faz busca reversa no histórico · Ctrl+G abre o monitor de subagentes · Esc cancela.
Entrada: @caminho referencia arquivos com autocomplete · Shift+Enter (ou Ctrl+J) quebra linha · /paste cola imagem · textos longos viram um “chip” que você expande com Tab.
Temas: dark, light e safe (fallback ANSI para SSH), com autodetecção; ajuste em /theme (e NO_COLOR é respeitado).
Aprovações: quando uma ferramenta pede permissão, aparecem Yes / Trust / No; o trust de shell pode ser por comando exato, por prefixo ou por comando base.

A interface clássica continua ali com --classic — útil em terminais restritos. Mas o padrão hoje é a TUI, e é ela que dá os painéis e atalhos acima.

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 ...
# a sessão é salva sozinha a cada turno
# fecha o terminal, vai almoçar, volta

cd api-pagamentos
kiro-cli chat --resume     # retoma a última conversa deste diretório
# (ou abra o kiro-cli e use /chat para escolher qual sessão retomar)
# a conversa anterior volta com todo o contexto

O Kiro salva a sessão a cada turno — nada se perde se o terminal fechar. Você retoma com kiro-cli chat --resume (a última do diretório), --resume-picker / /chat (escolhe qual) ou exporta e importa um arquivo com /chat save <arquivo> e /chat load <arquivo>. Cada codebase carrega assim sua própria linha de raciocínio. E, para trazer um arquivo específico ao contexto na hora, use @caminho/arquivo (com autocomplete) — enquanto #[[file:…]] é a sintaxe de resources/steering, que ancora artefatos de forma permanente no agente.

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

Na prática, você entra nesse modo com /plan (ou Shift+Tab) e sai quando aprova o plano. E quando a tarefa é grande demais para uma linha só, /spawn <tarefa> dispara subagentes em paralelo — acompanhe todos no monitor de crew com Ctrl+G.

Dicas e comandos que poupam tempo

Alguns recursos não são óbvios, mas mudam o dia a dia:

Traduzir linguagem natural em comando shell, sem abrir o chat: kiro-cli translate "compacte os logs com mais de 30 dias" devolve o comando pronto para revisar e rodar (-n gera até 5 opções).
Headless para scripts e CI: kiro-cli chat --no-interactive "…" imprime a resposta no STDOUT. Combine com --trust-tools para liberar só o necessário (ou --trust-all-tools, com cautela).
Nível de esforço do modelo: --effort high no launch (ou /effort na sessão) sobe o raciocínio para tarefas difíceis — de low a max.
Sugestões inline (ghost text) no seu shell: kiro-cli inline enable completa comandos enquanto você digita.
Fazer o kiro abrir o CLI (e não o IDE): kiro-cli integrations install kiro-command-router e depois kiro set-default cli. Aí kiro abre o CLI, kiro ide abre o IDE, e kiro-cli é sempre o CLI.
Manutenção: kiro-cli update atualiza o binário; kiro-cli doctor diagnostica e corrige problemas comuns de instalação.
Errou o rumo? /rewind volta a conversa a um turno anterior para tentar outro caminho, sem começar do zero.

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.
A Terminal UI é o padrão (markdown, painéis, atalhos como Ctrl+O, Shift+Tab, Ctrl+R); volte à clássica com --classic. Os slash commands são o painel: /chat para sessões, /context, /model, /mcp, /agent, /tools, ! para shell e @arquivo para referência.
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 modo plano (/plan / Shift+Tab) separa raciocínio de execução; e kiro-cli translate, /spawn (paralelo) e as sugestões inline poupam tempo no dia a dia.

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/
Terminal UI (interface padrão): https://kiro.dev/docs/cli/terminal-ui/
Gerenciamento de sessões: https://kiro.dev/docs/cli/chat/session-management/

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.