Claude Code CLI: A Referência Técnica Definitiva

Atualizado em 12 de dezembro de 2025

Atualização de Dezembro de 2025: O Claude Code agora alimenta fluxos de trabalho de engenharia empresarial com edição agentic de múltiplos arquivos, integração do protocolo MCP com mais de 300 serviços externos, subagentes especializados para tarefas complexas e sistema de hooks para automação de CI/CD. O sistema de permissões permite controles de segurança granulares. A alternância entre modelos Haiku (rápido/barato) e Opus (poderoso) otimiza o equilíbrio custo-desempenho.

Passei meses levando o Claude Code aos seus limites em codebases de produção, pipelines de CI/CD e implantações empresariais. Este guia destila essa experiência na referência abrangente que eu gostaria que existisse quando comecei. Cobre tudo, desde a primeira instalação até padrões avançados que a maioria dos usuários nunca descobre.

O Claude Code não é uma interface de chat que por acaso conhece programação. É um sistema agentic que lê sua codebase, executa comandos, modifica arquivos, gerencia fluxos de trabalho git, conecta-se a serviços externos e delega tarefas complexas a subagentes especializados—tudo através de uma interface de linha de comando que se integra à forma como os desenvolvedores realmente trabalham.

A diferença entre usar o Claude Code casualmente e usá-lo efetivamente está em entender sua arquitetura: a hierarquia de configuração que controla o comportamento, o sistema de permissões que controla operações, o sistema de hooks que permite automação determinística, o protocolo MCP que estende capacidades e o sistema de subagentes que lida com tarefas complexas de múltiplas etapas. Domine esses sistemas e o Claude Code se torna um multiplicador de força. Ignore-os e você estará deixando a maior parte do valor na mesa.

Este guia assume que você está confortável com ferramentas de linha de comando e quer o panorama completo. Cada recurso está documentado com sintaxe real, exemplos de configuração reais e os casos extremos que confundem usuários experientes. Seja você configurando seu primeiro projeto ou implantando em uma organização de engenharia empresarial, a informação está aqui.

Como o Claude Code Funciona: O Modelo Mental

Antes de mergulhar nos recursos, entenda como a arquitetura do Claude Code molda tudo o que você faz com ele. O sistema opera em três camadas:

┌─────────────────────────────────────────────────────────┐
│                    CAMADAS DO CLAUDE CODE                │
├─────────────────────────────────────────────────────────┤
│  CAMADA DE EXTENSÃO                                      │
│  ┌─────────┐  ┌─────────┐  ┌─────────┐  ┌─────────┐    │
│  │   MCP   │  │  Hooks  │  │ Skills  │  │ Plugins │    │
│  └─────────┘  └─────────┘  └─────────┘  └─────────┘    │
│  Ferramentas externas, automação determinística,        │
│  expertise de domínio, extensões empacotadas            │
├─────────────────────────────────────────────────────────┤
│  CAMADA DE DELEGAÇÃO                                     │
│  ┌─────────────────────────────────────────────────┐    │
│  │           Subagentes (até 10 em paralelo)        │    │
│  │   Explore | Plan | General-purpose | Custom      │    │
│  └─────────────────────────────────────────────────┘    │
│  Contextos isolados para trabalho focado, retorna       │
│  resumos                                                 │
├─────────────────────────────────────────────────────────┤
│  CAMADA CENTRAL                                          │
│  ┌─────────────────────────────────────────────────┐    │
│  │        Contexto da Conversa Principal            │    │
│  │   Tools: Read, Edit, Bash, Glob, Grep, etc.     │    │
│  └─────────────────────────────────────────────────┘    │
│  Sua interação principal; contexto limitado; custa      │
│  dinheiro                                                │
└─────────────────────────────────────────────────────────┘

Camada Central: Sua conversa principal. Cada mensagem, leitura de arquivo e saída de ferramenta consome contexto de uma janela compartilhada de 200K tokens (1M com premium). Quando o contexto enche, o Claude perde o controle de decisões anteriores e a qualidade degrada. Esta camada custa dinheiro por token.

Camada de Delegação: Subagentes iniciam com contextos limpos, fazem trabalho focado e retornam resumos. Os resultados de exploração não inflam sua conversa principal—apenas as conclusões retornam. Use subagentes Haiku para exploração (baratos, rápidos) e Sonnet para implementação.

Camada de Extensão: MCP conecta serviços externos (bancos de dados, GitHub, Sentry). Hooks garantem execução de comandos shell independentemente do comportamento do modelo. Skills codificam expertise de domínio que o Claude aplica automaticamente. Plugins empacotam tudo isso para distribuição.

O insight principal: A maioria dos usuários trabalha inteiramente na Camada Central, observando o contexto inflar e os custos subirem. Usuários avançados empurram exploração e trabalho especializado para a Camada de Delegação, mantêm a Camada de Extensão configurada para seu fluxo de trabalho e usam a Camada Central apenas para orquestração e decisões finais.

Índice

1. Instalação e Autenticação
2. Modos de Interação Principais
3. Sistema de Configuração em Profundidade
4. Seleção e Alternância de Modelos
5. Sistema de Permissões e Segurança
6. Sistema de Hooks
7. MCP (Model Context Protocol)
8. Subagentes e Delegação de Tarefas
9. Modo de Pensamento Estendido
10. Estilos de Saída
11. Comandos Slash
12. Skills
13. Sistema de Plugins
14. Memória e Gerenciamento de Contexto
15. Entrada de Imagem e Multimodal
16. Integração Git e Fluxos de Trabalho
17. Integração com IDE
18. Padrões de Uso Avançado
19. Claude Code Remote
20. Background Agents
21. Gerenciamento de Custos e Faturamento
22. Otimização de Desempenho
23. Solução de Problemas e Depuração
24. Implantação Empresarial
25. Referência de Atalhos de Teclado
26. Melhores Práticas

Instalação e Autenticação

Requisitos do Sistema

O Claude Code roda em macOS 10.15+, Ubuntu 20.04+/Debian 10+ e Windows 10+ através de WSL ou Git Bash. O sistema requer no mínimo 4 GB de RAM e conexão ativa com a internet. A compatibilidade de shell funciona melhor com Bash, Zsh ou Fish.

Para Windows, tanto WSL 1 quanto WSL 2 funcionam. Git Bash também funciona se você preferir Windows nativo. Alpine Linux e outros sistemas baseados em musl requerem pacotes adicionais:

apk add libgcc libstdc++ ripgrep
export USE_BUILTIN_RIPGREP=0

Métodos de Instalação

Instalação nativa (recomendada)

O binário nativo proporciona a experiência mais limpa sem dependência de Node.js:

# macOS e Linux
curl -fsSL https://claude.ai/install.sh | bash

# Alternativa Homebrew
brew install --cask claude-code

# Windows PowerShell
irm https://claude.ai/install.ps1 | iex

# Windows CMD
curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

Para instalação de versão específica:

# Instalar versão específica
curl -fsSL https://claude.ai/install.sh | bash -s 1.0.58

# Instalar latest explicitamente
curl -fsSL https://claude.ai/install.sh | bash -s latest

# Windows PowerShell - versão específica
& ([scriptblock]::Create((irm https://claude.ai/install.ps1))) 1.0.58

Instalação via NPM

Para ambientes onde npm é preferido:

npm install -g @anthropic-ai/claude-code

Nunca use sudo com instalação npm—isso cria problemas de permissão que complicam tudo posteriormente.

Migração de instalação existente

Se você tem uma instalação mais antiga baseada em npm, migre para o binário nativo:

claude install

Opções de Autenticação

O Claude Code suporta três caminhos de autenticação, cada um com diferentes compensações:

Claude Console (faturamento por API)

Conecte-se diretamente à API da Anthropic através do console.anthropic.com. Crie uma conta, configure o faturamento e autentique através da CLI. Isso fornece faturamento baseado em uso com acesso completo à API. Um workspace dedicado "Claude Code" é criado automaticamente—você não pode criar chaves de API para este workspace, mas pode monitorar o uso.

Assinatura Claude Pro ou Max

Use suas credenciais da conta claude.ai. A assinatura cobre tanto a interface web quanto o uso da CLI em um único plano mensal. Isso simplifica o faturamento para usuários individuais que querem custos previsíveis.

Plataformas empresariais

AWS Bedrock, Google Vertex AI e Microsoft Foundry fornecem acesso de nível empresarial com relacionamentos de faturamento de nuvem existentes:

# AWS Bedrock
export CLAUDE_CODE_USE_BEDROCK=1
export AWS_REGION=us-east-1
export AWS_PROFILE=your-profile

# Google Vertex AI
export CLAUDE_CODE_USE_VERTEX=1
export CLOUD_ML_REGION=us-east5
export ANTHROPIC_VERTEX_PROJECT_ID=your-project

# Microsoft Foundry
export CLAUDE_CODE_USE_FOUNDRY=1
export ANTHROPIC_FOUNDRY_RESOURCE=your-resource-name
# Opcional: autenticação por API key (caso contrário usa Entra ID)
export ANTHROPIC_FOUNDRY_API_KEY=your-key

Para implantações empresariais atrás de proxies ou através de gateways LLM:

# Proxy corporativo
export HTTPS_PROXY='https://proxy.example.com:8080'

# Gateway LLM (pular autenticação nativa)
export CLAUDE_CODE_USE_BEDROCK=1
export ANTHROPIC_BEDROCK_BASE_URL='https://your-gateway.com/bedrock'
export CLAUDE_CODE_SKIP_BEDROCK_AUTH=1

Verificação

claude doctor

Isso reporta tipo de instalação, versão, configuração do sistema e quaisquer problemas detectados.

Atualizações

O Claude Code atualiza automaticamente por padrão, verificando na inicialização e periodicamente durante as sessões. As atualizações são baixadas em segundo plano e aplicadas no próximo lançamento.

Desabilitar atualizações automáticas:

export DISABLE_AUTOUPDATER=1

Ou em settings.json:

{
  "env": {
    "DISABLE_AUTOUPDATER": "1"
  }
}

Atualização manual:

claude update

Desinstalação

Instalação nativa (macOS/Linux/WSL):

rm -f ~/.local/bin/claude
rm -rf ~/.claude-code

Instalação nativa (Windows PowerShell):

Remove-Item -Path "$env:LOCALAPPDATA\Programs\claude-code" -Recurse -Force
Remove-Item -Path "$env:LOCALAPPDATA\Microsoft\WindowsApps\claude.exe" -Force

Limpar configuração (remove todas as configurações):

rm -rf ~/.claude
rm ~/.claude.json
rm -rf .claude
rm -f .mcp.json

Modos de Interação Principais

REPL Interativo

Lance o Claude Code sem argumentos para entrar no loop interativo read-eval-print:

cd your-project
claude

O REPL mantém o contexto da conversa entre turnos. Digite consultas diretamente, receba respostas e continue até sair com /exit ou Ctrl+D.

Comece com um prompt inicial para focar a sessão:

claude "explique o fluxo de autenticação neste projeto"

Dica de especialista: O REPL persiste estado através de eventos de compactação. Quando o contexto cresce demais, o Claude automaticamente resume conversas mais antigas enquanto preserva decisões-chave e trechos de código. Você pode acionar isso manualmente com /compact ou adicionar instruções personalizadas para o que preservar.

Modo Não-Interativo

O modo print (-p) executa uma única consulta e encerra:

# Consulta direta
claude -p "liste todos os comentários TODO neste projeto"

# Processar entrada via pipe
cat error.log | claude -p "identifique a causa raiz dessas falhas"

# Encadear com outras ferramentas
claude -p "gere um README" > README.md

Para saída estruturada adequada para parsing em scripts:

claude -p "conte linhas por tipo de arquivo" --output-format json

A saída JSON inclui tudo que você precisa para automação:

{
  "type": "result",
  "subtype": "success",
  "total_cost_usd": 0.0034,
  "is_error": false,
  "duration_ms": 2847,
  "duration_api_ms": 1923,
  "num_turns": 4,
  "result": "Texto da resposta aqui...",
  "session_id": "abc-123-d

[Conteúdo truncado para tradução]