Manual de Referência da CLI (CLI Reference): Comandos e Flags

📚 Navegação da Série: O artigo anterior 33 Hooks (Gatilhos de Terminal) ensinou a automatizar lints e proteções no terminal. Este capítulo retorna ao básico da interface de linha de comando—mapeando todas as opções e flags de suporte que podem ser fornecidas ao comando claude. Comandos, flags, fluxos de pipelines e códigos de saída locais são explicados em tabelas de consulta rápida.

“O seu comando claude aceita parâmetros? Eu sempre digitei apenas claude no terminal.”

“Sim, aceita. Você pode rodar um script contendo claude -p 'Resuma este PR' para gravar o log diretamente em um arquivo local, sem precisar abrir o chat interativo.”

“Espere—o que faz a flag -p? Não consegui encontrar todos os parâmetros usando claude --help.”

Essa dúvida é frequente. Muitos usuários do Claude Code iniciam o terminal digitando apenas claude no console, desconhecendo a variedade de parâmetros disponíveis. A própria documentação oficial adverte: o comando claude --help não lista todas as flags do sistema. Confiar apenas no help nativo oculta uma parte importante da CLI.

Até o momento, focamos no modo interativo do Claude Code: abrindo o chat, enviando prompts e revisando arquivos. Contudo, o Claude Code é, essencialmente, um utilitário de CLI, que suporta redirecionamento de dados, pipelines lúdicos e análise de códigos de retorno em scripts. Este artigo atua como o manual da CLI, consolidando comandos, flags e códigos de erro.

Ao terminar este artigo, você obterá:

• Lista de comandos fundamentais da CLI do claude (inicialização, retomada, updates, logins)
• As principais flags utilitárias (-p, --model, -c, --resume, --permission-mode, --add-dir)
• Uso em modo headless (sem interface) e pipelines locales (como linter com jq)
• Códigos de saída do console para verificação em automações
• Um roteiro prático passo a passo em modo headless com redirecionamento de logs

---

01 Comandos versus Flags

Antes de consultar as tabelas, diferencie os dois tipos de parâmetros aceitos no console: comandos (commands) e flags.

Analogia: O despacho de encomendas. O comando base claude indica a ação de despacho; parâmetros como update ou mcp funcionam como sub-ações (comandos), determinando a finalidade do envio; flags como -p ou --model funcionan como opções adicionais (flags), modificando detalhes técnicos (como urgência ou o entregador encarregado). Você escolhe uma sub-ação e marca várias flags.

Exemplos de sintaxe:

claude update
claude -p "Explique esta função" --model sonnet

• Linha 1: O termo update é um comando (sub-ação avulsa que roda e encerra o console).
• Linha 2: A inicialização entra direto no chat; -p e --model são flags que alteram o prompt inicial e o processador.

Essa distinção é útil para consultas na documentação oficial: instruções de instalação, autenticação ou MCPs ficam na seção de comandos; otimizações de comportamento do terminal ou escolhas de modelo ficam na tabela de flags.

Se você digitar uma sub-comando incorretamente, o console exibirá sugestões de ajuste. A documentação indica:

如果您输入错误的子命令，Claude Code 会建议最接近的匹配项并退出而不启动会话。例如，claude udpate 会打印 Did you mean claude update?。

Se você digitar um subcomando incorretamente, o Claude Code sugerirá o termo mais próximo e encerrará sem iniciar uma sessão. Por exemplo, claude udpate exibirá Did you mean claude update?.

Esse ajuste automático de digitação evita que o console inicialize sessões inválidas devido a erros de digitação no terminal.

💡 Resumo em uma frase: Comandos representam sub-ações com encerramento do console (ex: update); flags alteram propriedades do console de chat (ex: --model).

---

02 Comandos básicos de inicialização

Mapeamos as formas mais recorrentes de uso del console, divididas por finalidade:

Grupo 1: Inicialização do console (recorrente)

Abertura clássica do chat:

# 1. Modo interativo padrão do console
claude

# 2. Inicializar passando um prompt de chat inicial
claude "Explique este repositório"

# 3. Rodar em modo headless (sem interface) imprimindo o resultado
claude -p "Explique esta função"

A terceira opção (claude -p) representa o modo headless (sem interface visual). Ele realiza a tarefa de forma direta no terminal e encerra, sendo indicado para automações locales. Detalharemos esse comportamento no Passo 4.

Grupo 2: Retomada de sessões (evitar perda de histórico)

Como vimos no Artigo 19, todo novo chat inicializa a IA sem histórico contextuais. Use estes comandos para recuperar sessões anteriores:

# Retomar a última sessão ativa no diretório atual
claude -c
# (Equivalente à flag por extenso: --continue)

# Restaurar uma sessão específica por identificador ou nome
claude -r "auth-refactor" "Finalize esta alteração"
# (Equivalente à flag por extenso: --resume)

Distinção técnica:

• -c (--continue): recupera a última sessão do diretório local (não exige IDs).
• -r (--resume): recupera uma conversa específica (indicando ID ou nome); se omitido, exibe a lista de sessões locais.

Analogia: Retomar o assunto. O comando -c é como dizer "vamos continuar de onde paramos há 5 minutos"—o assunto é óbvio e dispensa explicações. O comando -r é como dizer "vamos retomar o debate sobre aquela arquitetura de login de terça-feira"—você aponta exatamente qual tópico deseja ler.

Recomendação: use -c se estiver trabalhando em uma única tarefa rápida; use -r se alternar entre depurações de backend e testes em paralelo—nomeando as sessões via --name (-n) na criação para facilitar a busca posterior. Exemplo de fluxo:

# Inicializar nomeando a sessão de desenvolvimento
claude -n "login-refactor"

# Retomar a conversa de forma direta dias depois
claude -r "login-refactor"

O manual destaca que o parâmetro --name exibe identificadores amigáveis no console, substituindo chaves UUIDs complexas (como 550e8400-...) na lista de busca do /resume.

Você pode combinar as flags: claude -c -p "Verifique erros de tipagem" recupera o histórico local recente e executa a tarefa em modo headless (sem interface). Essa unificação ajuda a encadear validações lógicas em automações.

Grupo 3: Autenticação e atualizações de sistema

Sub-ações eventuais de manutenção:

# Atualizar para a versão estável mais recente
claude update

# Instalar ou forçar a versão local do executável
claude install stable

# Realizar autenticação na conta Anthropic
claude auth login

# Verificar status de login ativo (retorna exit 0 se logado e exit 1 se offline)
claude auth status

O instalador suporta chaves explícitas como 2.1.118, stable ou latest. Essa flexibilidade permite congelar a versão em builds homologados se alguma atualização quebrar Hooks de lints de equipe locais.

O código de saída do claude auth status (exit 0 para ativo e exit 1 para desconectado) é útil para lógicas de validação em scripts, que explicaremos no Passo 5.

Nota: Esses comandos exigem conexão com os servidores da Anthropic. Certifique-se de configurar proxies locais se encontrar falhas de rede.

💡 Resumo em uma frase: Comandos de CLI gerenciam inicializações (chat convencional ou -p headless), retomadas de sessões (último com -c ou pontual com -r) e tarefas de sistema (login, updates).

---

03 Principais flags utilitárias

Abaixo detalhamos o comportamento das flags indispensáveis para automações de console:

-p / --print: Modo headless de execução

O parâmetro mais importante da CLI: suprime a renderização do chat visual, enviando os dados do prompt e imprimindo as conclusões diretamente no console antes de encerrar.

claude -p "Qual a finalidade deste módulo de autenticação local?"

Representa a base para a criação de pipelines e acionamento de scripts. Analisaremos isso no Passo 4.

--model: Definição local de processador

Define qual versão do modelo processará a instrução, sobrescrevendo chaves do settings.json:

claude --model sonnet
claude --model opus

Aceita apelidos curtos (sonnet, opus) ou termos completos oficiais. A escolha do processador foi detalhada no Artigo 05.

--permission-mode: Restrição de permissões no boot

Configura a necessidade de confirmação humana para comandos locais antes da IA inicializar. Exemplo:

claude --permission-mode plan

Valores aceitos pela CLI:

Aceita default, acceptEdits, plan, auto, dontAsk ou bypassPermissions. Sobrescreve defaultMode no arquivo de configurações.

Destaques: plan (somente leitura sem edições), acceptEdits (autodeclaração de escrita física de arquivos) e bypassPermissions (permissão irrestrita). Analisaremos esses comportamentos no Artigo 35.

--dangerously-skip-permissions: Bypass irrestrito de segurança

Essa flag remove todos os prompts de confirmação locais de ferramentas, equivalente a configurar --permission-mode bypassPermissions:

claude --dangerously-skip-permissions

A presença da palavra dangerously serve para deencorajar o uso fora de propósitos específicos (como sandboxes locais ou containers efêmeros de CI). Nunca a utilize em ambientes de produção com acesso a bancos de dados (Artigo 20). Para segurança de automações, prefira --permission-mode acceptEdits ou use --allowedTools para liberar utilitários pontuais.

--add-dir: Escopos de visibilidade adicionais

Concede permissões de leitura e escrita físicas a pastas extras do seu disco fora do diretório de boot inicial:

claude --add-dir ..\apps ..\lib

Indicado para mapear interações de monorepositórios. Atenção à regra de visibilidade:

Concede acesso a arquivos; a maioria das configurações em .claude/ não será descoberta a partir desses diretórios.

Isso significa que o Claude lerá os arquivos externos, mas não importará as regras do CLAUDE.md ou Skills daqueles diretórios secundários.

--output-format: Formatação de logs de saída

Mapeia o formato do print do terminal (válido em modo -p headless):

claude -p "Mapeie este projeto" --output-format json

Opções: text (texto plano padrão), json (objeto estructurado contendo metadados de tokens, ID de sessão e custos) ou stream-json (logs em tempo real). Usar o formato json é essencial para processamentos em scripts com jq.

--allowedTools / --disallowedTools: Lista de ferramentas autorizadas

Autoriza ou rejeita previamente chamadas de terminal locais em rotinas headless:

claude -p "Rode a suíte de testes locais" --allowedTools "Bash,Read,Edit"

As ferramentas listadas em --allowedTools rodam silenciosamente sem confirmação manual. A flag aceita regras declarativas finas, como "Bash(git diff *)" (conforme visto no Artigo 20).

Flags de proteção para execuções automatizadas

Parâmetros de proteção adicionais do modo headless:

# Limitar o processamento do loop da IA a no máximo 3 rodadas
claude -p --max-turns 3 "Rode a verificação"

# Interromper o processo se o custo de tokens exceder US$ 5.00
claude -p --max-budget-usd 5.00 "Rode o script"

Use a flag --max-turns em scripts autônomos locais. Em caso de loops de erros recorrentes de compilação, o assistente consumiria tokens indefinidamente tentando refatorar arquivos. Limitar as rodadas de processamento garante a segurança orçamentária.

💡 Resumo em uma frase: As flags principais alteram a visualização (-p headless), o processador (--model), privilégios (--permission-mode), caminhos (--add-dir), saída (--output-format json) e liberações de APIs (--allowedTools); adote --max-turns como limite de proteção.

---

04 Integração em pipelines (Modo Headless)

O modo headless permite acionar o Claude Code como um componente em encadeamentos de comandos bash. A IA recebe entradas do console anterior e repassa as conclusões no console local de forma sequencial.

Analogia: A esteira transportadora. O chat interativo funciona como a bancada de um artesão que esculpe uma peça por vez manualmente. O modo headless funciona como uma esteira industrial: a máquina anterior corta o material (com cat ou git diff), o Claude processa a peça dinamicamente de forma intermediária e o duto de saída entrega o resultado para o empacotador (gravação de logs ou filtros de jq). O processo roda sozinho.

Entrada de pipelines

O Claude Code em modo headless lê dados diretamente do stdin, permitindo canalizar entradas usando o operador |:

Get-Content build-error.txt | claude -p 'Explique a causa raiz deste erro de compilação de forma concisa' > output.txt

O comando lê a pilha de logs locais, encaminha o texto ao Claude e salva o relatório técnico em output.txt de forma automática, sem interações de chat.

Nota técnica de limite: payloads transmitidos via pipeline (stdin) estão restritos a no máximo 10MB. Transmitir arquivos volumosos que excedam essa chave gerará erros locais de compilação. Para grandes volumes, indique os caminhos no prompt para leitura física.

Uso como validador de código local (Linter)

Você pode inscrever chamadas estáticas nos scripts do package.json do Node.js. Exemplo oficial para verificar erros ortográficos em commits locais:

{
  "scripts": {
    "lint:claude": "git diff main | claude -p \"you are a typo linter. for each typo in this diff, report filename:line on one line and the issue on the next. return nothing else.\""
  }
}

Executar npm run lint:claude audita os arquivos. Passar os diffs diretamente via pipeline (stdin) é seguro, pois evita que a IA precise de permissões de terminal para vasculhar o histórico do git local.

Filtragem de JSON com o jq

Mapear a saída JSON estruturada permite isolar parâmetros lúdicos usando o utilitário jq:

claude -p "Resuma as propriedades do repositório" --output-format json | jq -r ".result"

O JSON detalha as chaves de controle do console. Mapear o identificador de sessão (.session_id) permite encadear prompts consecutivos em automações locais:

# Capturar a ID do chat de boot
$SessionID = (claude -p "Inicialize a triagem" --output-format json | jq -r ".session_id")
# Continuar a conversa no mesmo canal em modo headless
claude -p "Consolide os relatórios" --resume "$SessionID"

Configuração temporária de personas

Para tarefas de auditoria locais rápidas, use --append-system-prompt para acrescentar chaves de comportamento temporárias ao system prompt, como exemplificado na documentação oficial:

git diff main | claude -p --append-system-prompt "You are a security engineer. Review for vulnerabilities." --output-format json

Entenda a distinção: --append-system-prompt adiciona dados ao final do system prompt padrão, preservando as ferramentas MCP e lints de terminal. A flag --system-prompt substitui inteiramente o bloco de instruções, desabilitando utilitários nativos locais (exige maior controle manual de caminhos). Prefira o uso de append.

--bare: Inicialização rápida em scripts

Para aumentar a eficiência de processamento em pipelines, use a flag --bare. Citação oficial:

Modo mínimo: ignora hooks, skills, plugins, servidores MCP, memória automática e autodescoberta de CLAUDE.md para que inicializações scriptadas rodem mais rapidamente.

O parâmetro suprime a varredura do diretório .claude/ (ignorando Skills locais, Hooks e CLAUDE.md), mantendo apenas privilégios básicos de terminal. Isso aumenta a velocidade de boot do Claude e evita flutuações de comportamento locais entre máquinas em servidores de CI. A documentação indica que esta flag se tornará o comportamento padrão do modo -p em versões futuras.

Propriedade	Modo Interativo (claude)	Modo Headless (claude -p)
Console Visual	✅ Sim (interface gráfica no console)	❌ Não (saída impressa em texto plano)
Operação	✅ Manual em tempo real	✅ Automatizada por scripts em segundo plano
Pipelines (stdin)	❌ Não suportado	✅ Sim (operadores `
Permissões locais	Prompts interativos automáticos	Configurado previamente com flags de segurança

💡 Resumo em uma frase: O modo headless -p suporta canais locais (stdin | claude -p > log.txt); use --bare para acelerar execuções de CI e capture propriedades de logs lúdicos formatados em JSON.

---

05 Códigos de retorno em scripts

O tratamento de códigos de erro (exit code) permite gerenciar interrupções em automações locais.

Analogia: O boletim escolar. Um programa retorna um código numérico ao encerrar: 0 indica sucesso técnico total, enquanto valores diferentes de 0 apontam falhas ou exceções. Scripts de PowerShell ou Bash lêem esse código para decidir se continuam a execução das rotinas seguintes.

Para verificar o código do último comando executado (PowerShell):

claude auth status
$LASTEXITCODE

O sistema exibirá a chave numérica do retorno (exit code).

Códigos de saída padrão mapeados:

Comando/Cenário técnico	Código de retorno	Significado técnico
claude auth status logado	0	Credenciais ativas locais.
claude auth status deslogado	1	Sem autenticação ativa local.
Limite de --max-turns alcançado	Diferente de 0	Processamento interrompido por excesso de rodadas.
Payload stdin superior a 10MB	Diferente de 0	Tamanho limite excedido, abortando processo.
claude daemon status inativo	1	Serviço local supervisor indisponível.

Uso em scripts: Verificação prévia de autenticação no script local:

# Interromper o processo no PowerShell caso deslogado
claude auth status
if ($LASTEXITCODE -ne 0) {
    Write-Error "Usuário deslogado na Anthropic. Abortando deploy."
    exit 1
}

Essa triagem no início de scripts automatizados evita que execuções longas falhem no meio devido a sessões expiradas, facilitando o gerenciamento de alertas locais.

Lógica de controle: retornos 0 autorizam os blocos seguintes; valores diferentes de 0 interrompem a execução. Esse é o padrão de sinalização da CLI.

💡 Resumo em uma frase: O código de saída (exit code) gerencia o fluxo operacional de scripts; 0 indica sucesso e valores diferentes sinalizam exceções a serem tratadas.

---

06 Tabela de consulta rápida de flags

Mapeamento das principais flags da CLI para referência rápida de desenvolvimento:

Inicialização e Sessões

Flag	Atalho	Comportamento no terminal
--print	-p	Modo headless de impressão de resultados direta
--continue	-c	Recupera o histórico local mais recente
--resume	-r	Restaura sessões específicas indicando ID ou nome
--name	-n	Nomeia a sessão ativa para facilitação de buscas
--fork-session	—	Cria uma cópia da ID da sessão para evitar sobreposição
--session-id	—	Vincula explicitamente a execução a uma ID UUID

Processadores e Permissões

Flag	Comportamento no terminal
--model	Define a versão do processador (Sonnet, Opus) local
--fallback-model	Modelo de emergência em caso de overload de servidores
--permission-mode	Altera o modo de acessos (plan, acceptEdits, bypassPermissions)
--allowedTools	Lista de ferramentas pré-autorizadas sem prompts
--disallowedTools	Lista de ferramentas bloqueadas declarativas
--dangerously-skip-permissions	Bypass irrestrito de segurança de console (use com cautela)

Diretórios e Configurações

Flag	Comportamento no terminal
--add-dir	Concede visibilidade de leitura/escrita a pastas extras
--settings	Carrega arquivo JSON alternativo ou regras inline de regras
--setting-sources	Define as origens físicas de carregamento (user, project, local)
--mcp-config	Carrega configurações locais de servidores MCP
--bare	Suprime Skills, Hooks e MCPs locais para agilização do boot

Parâmetros do modo Headless (recorrentes em -p)

Flag	Comportamento no terminal
--output-format	Formato da saída física (text, json, stream-json)
--input-format	Formato lúdico de entrada de dados
--max-turns	Limita o total de rodadas lúdicas permitidas por execução
--max-budget-usd	Teto orçamentário máximo de tokens consumidos na sessão
--verbose	Exibe logs detalhados de interações e processamentos
--append-system-prompt	Acrescenta diretrizes temporárias de comportamento
--system-prompt	Substitui integralmente a persona de engenharia padrão

Configurações Diversas

Flag	Atalho	Comportamento no terminal
--version	-v	Exibe a versão local instalada
--ide	—	Conexão automática ao editor compatível identificado
--debug	—	Ativa logs de depuração locais (ex: --debug "api,mcp")

💡 Resumo em uma frase: Mapeie as flags consultando a tabela estrutural; lembre-se de que o help local oculta parâmetros secundários descritos apenas nos manuais web.

---

07 Prática: Encadeando fluxos em pipelines

Vamos exercitar o modo headless: rodar chamada avulsa → alimentar via stdin pipeline → capturar campos JSON → analisar códigos de erro.

Passo 1: Execução básica em modo headless (PowerShell):

claude -p "Diferencie git rebase de git merge em uma única frase curta"

Saída esperada: O terminal imprimirá a resposta e devolverá o controle de escrita de forma direta, sem renderização de caixas de chat.

Passo 2: Canalizar dados de arquivo via pipeline

Gere um arquivo de código com um erro de escrita lógica e direcione-o ao input da IA:

Set-Content -Path "buggy.py" -Value "def add(a, b):`n    return a - b"
Get-Content buggy.py | claude -p "Identifique o erro neste trecho de código em uma única linha de resposta"

Saída esperada: A IA lerá o texto enviado via stdin e indicará a incoerência matemática do escopo, validando a integração por pipeline.

Passo 3: Mapear e ler chaves do log JSON

claude -p "O que é Python?" --output-format json

O console retornará um objeto estruturado contendo metadados técnicos. Execute a filtragem com o jq:

claude -p "O que é Python?" --output-format json | jq -r ".result"

Saída esperada: Apenas o texto limpo da explicação de Python será exibido, removendo os invólucros do JSON.

Passo 4: Validar os códigos de erro

claude auth status
$LASTEXITCODE

Saída esperada: O console retornará 0 se seu login estiver ativo ou 1 se estiver offline, servindo para lógicas de validação em scripts de deploy.

Essas quatro etapas validam a infraestrutura para criação de linters locais e automações em lote.

---

08 Resumo

Dominar os comandos e flags da CLI permite integrar o Claude Code como parte de suas rotinas e scripts de CI de forma autônoma.

Revisão das diretrizes:

Objetivo de automação	Flag/Comando	Ponto-chave a lembrar
Diferença conceitual	Ação vs Ajuste do console	Comandos encerram processos (ex: update); flags alteram propriedades do chat.
Retomar chats locais	-c ou -r	-c recupera a última conversa; -r carrega conversas nomeadas.
Execuções headless	Flag -p	Imprime resultados direto no console e encerra.
Sobrescrever preferências	--model e --permission-mode	Válido apenas na execução ativa do console.
Acionar encadeamentos	Pipelines (stdin) com jq	Conecte saídas do terminal usando pipelines locais.
Controle de fluxos	Códigos de saída (exit code)	0 indica sucesso técnico e valores diferentes apontam falhas.
Consultar chaves da CLI	Tabela do Passo 6 ou manuais web	O help local oculta parâmetros avançados.

Agora você deve ser capaz de: Classificar chaves em comandos e flags, recuperar chats nomeados, construir encadeamentos lúdicos via stdin, capturar metadados do JSON estruturado via jq e tratar códigos de saída no console. A CLI do Claude Code atua como um utilitário integrado de terminal.

---

No próximo artigo, 35 "Modos de Controle (Modes and Control)"—analisaremos as propriedades de segurança dos modos de acessos. Explicaremos as chaves lógicas de plan, acceptEdits e bypassPermissions de forma a ajustar a autonomia da IA na escrita física de arquivos locais, equilibrando produtividade e controle de segurança.

---

Leitura Recomendada

• Conceitos básicos de terminal e comandos do Claude Code
• Assinaturas locais e chaves de API do Claude Code
• Criação e restauração de commits de segurança com Checkpoints