⌨️ Série: Claude Code CLI: guia técnico — Parte 1: fundamentos e configuração

Versão do conteúdo: outubro de 2026
Fontes: exclusivamente a documentação oficial da Anthropic (code.claude.com/docs e support.claude.com). A lista completa está em Fontes oficiais (Parte 3).
Aviso: o Claude Code é atualizado com frequência. Antes de usar este material como referência, confira as mudanças com /release-notes e a referência oficial do CLI. O claude --help não lista todas as flags.

---

📑 Índice da série

1. 🧠 O que é o Claude Code CLI
2. 📦 Instalação e autenticação
3. 🚪 Comandos de entrada
4. ⌨️ Atalhos de teclado e prefixos
5. ⚡ Slash commands essenciais
6. 🔐 Modos de permissão
7. 📄 Memória: CLAUDE.md e auto memory
8. ⚖️ Configuração: settings.json
9. 🪝 Hooks (Parte 2)
10. 👥 Subagents (Parte 2)
11. 🧩 Skills, comandos e plugins (Parte 2)
12. 🔌 MCP no terminal (Parte 2)
13. ⏪ Checkpoints e gestão de contexto (Parte 2)
14. 🤖 Modo não interativo (-p) e CI (Parte 2)
15. 🔀 Sessões em paralelo (Parte 2)
16. ⏰ Automação agendada (Parte 2)
17. 📱 Trabalho remoto e entre dispositivos (Parte 3)
18. ✅ O que só o CLI faz (Parte 3)
19. ❌ O que o CLI não faz (Parte 3)
20. 🤫 Recursos pouco conhecidos (Parte 3)
21. 🏆 Fluxo de trabalho recomendado (Parte 3)
22. ⚠️ Cuidados e limitações (Parte 3)
23. 📚 Fontes oficiais (Parte 3)

---

1. 🧠 O que é o Claude Code CLI

O Claude Code é uma ferramenta de programação agêntica da Anthropic. Ela lê o seu código, edita arquivos, executa comandos e se integra às suas ferramentas de desenvolvimento. O CLI é a versão de terminal: você roda claude dentro de uma pasta de projeto e conversa com um agente que trabalha nesse projeto.

Não é um autocomplete. Segundo a documentação, o agente trabalha num ciclo de três fases, que se repete até a tarefa terminar:

1. 🔍 Reúne contexto: lê e busca no repositório.
2. ✏️ Age: edita arquivos, roda testes, build e git.
3. ✅ Verifica: confere o resultado e volta ao início se algo falhou.

Planejar antes de mexer no código não é uma fase do ciclo. É um modo de permissão (plan), que você ativa quando quer (veja a seção 6).

O que ele faz, segundo a documentação oficial:

• Escreve testes, corrige erros de lint, resolve conflitos de merge, atualiza dependências e escreve release notes.
• Implementa features e corrige bugs a partir de uma descrição em linguagem natural ou de uma mensagem de erro.
• Trabalha direto com git: faz stage, escreve mensagens de commit, cria branches e abre pull requests.
• Conecta-se a ferramentas externas via MCP (Google Drive, Jira, Slack ou ferramentas internas).
• Funciona em pipelines Unix, scripts e CI.

Onde o mesmo motor roda: terminal (CLI), VS Code/Cursor, JetBrains, aba Code do app desktop, web (claude.ai/code), app mobile e Slack. Arquivos CLAUDE.md, settings e servidores MCP do repositório são compartilhados entre as superfícies locais (CLI, IDEs e desktop).

A página oficial de plataformas descreve o CLI como a superfície mais completa para trabalho no terminal e diz que scripting e o Agent SDK só existem nele.

---

2. 📦 Instalação e autenticação

Requisitos

• Sistema operacional: macOS 13.0+, Windows 10 1809+ ou Windows Server 2019+, Ubuntu 20.04+, Debian 10+, Alpine Linux 3.19+
• Hardware: 4 GB+ de RAM, processador x64 ou ARM64
• Conta: Pro, Max, Team, Enterprise ou Console. O plano Free do claude.ai não inclui Claude Code.
• Alternativa: provedores terceiros (Amazon Bedrock, Google Cloud's Agent Platform, Microsoft Foundry)

Windows: o Bash tool usa o Git for Windows; sem ele, o Claude Code recorre à ferramenta de PowerShell. O sandbox não funciona no Windows nativo; só no WSL 2.
Alpine e distros com musl: instale bash, curl, libgcc, libstdc++ e ripgrep, e defina USE_BUILTIN_RIPGREP=0.

Instalar

# macOS, Linux, WSL — instalador nativo (recomendado)
curl -fsSL https://claude.ai/install.sh | bash

# 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

# Alternativas
brew install --cask claude-code          # Homebrew (canal stable)
brew install --cask claude-code@latest   # Homebrew (canal latest)
winget install Anthropic.ClaudeCode      # WinGet
npm install -g @anthropic-ai/claude-code # npm (Node.js 22+; nunca use sudo)

Também há repositórios assinados para apt, dnf e apk (Debian, Ubuntu, Fedora, RHEL, Alpine).

npm com Node antigo: a instalação conclui, mas mostra o aviso EBADENGINE. Use Node.js 22 ou superior.

Verificar

claude --version   # imprime a versão, ex.: 2.1.211 (Claude Code)
claude doctor      # diagnóstico da instalação e das configurações, sem abrir sessão

Os binários publicados vêm com um manifest.json assinado e checksums SHA256, verificáveis com a chave GPG divulgada na documentação.

Atualizações

Método de instalação	Atualiza sozinho?	Como atualizar
Instalador nativo	✅ Sim, em segundo plano	claude update para forçar
Homebrew	❌ Não, por padrão	brew upgrade claude-code
WinGet	❌ Não, por padrão	winget upgrade Anthropic.ClaudeCode
apt / dnf / apk	❌ Não	Pelo gerenciador do sistema
npm	✅ Sim, se o diretório global do npm for gravável	npm install -g @anthropic-ai/claude-code@latest (evite npm update -g)

• O canal de atualização (latest ou stable) é definido pelo setting autoUpdatesChannel, ou em /config. O padrão é latest. O stable costuma estar cerca de uma semana atrás e pula versões com regressões graves.
• Homebrew e WinGet passam a se atualizar sozinhos com CLAUDE_CODE_PACKAGE_MANAGER_AUTO_UPDATE=1.
• O setting minimumVersion define uma versão mínima, para que trocar para stable não faça downgrade.

Login

claude                      # primeira execução: login pelo navegador
claude auth login           # login explícito (--console para cobrança via API)
claude auth status          # status em JSON; código de saída 0 = logado, 1 = não
claude setup-token          # gera um token OAuth de longa duração para CI e scripts

claude setup-token exige assinatura Claude e abre o navegador uma vez para autorizar. O token vale um ano, é impresso no terminal e não fica salvo. Use-o na variável CLAUDE_CODE_OAUTH_TOKEN. Ele autentica só as chamadas ao modelo: não serve para Remote Control nem para connectors do claude.ai, e é ignorado com --bare.

Pegadinha de autenticação: uma ANTHROPIC_API_KEY que você aprovou tem prioridade sobre a assinatura. Confira o que está em uso com /status e rode unset ANTHROPIC_API_KEY para voltar à assinatura.

---

3. 🚪 Comandos de entrada

Comando	O que faz
claude	Abre uma sessão interativa
claude "pergunta"	Abre a sessão já com um prompt inicial
claude -p "pergunta"	Roda sem interface, imprime o resultado e sai
claude -c	Continua a conversa mais recente desta pasta
claude -r "<sessão>"	Retoma uma sessão por ID ou nome
claude -n "nome"	Dá nome à sessão (aparece em /resume e no título do terminal)
claude -w nome	Abre a sessão num git worktree isolado (seção 15, na Parte 2)
claude --bg "tarefa"	Inicia uma sessão em segundo plano (seção 15, na Parte 2)
claude update	Atualiza para a versão mais recente
claude mcp	Gerencia servidores MCP
claude plugin	Gerencia plugins
claude agents	Abre o painel de sessões em segundo plano (exige terminal interativo)

Para processar conteúdo recebido por pipe:

cat arquivo | claude -p "pergunta"

---

4. ⌨️ Atalhos de teclado e prefixos

Atalhos principais

Atalho	O que faz
Esc	Interrompe o Claude ou fecha um diálogo
Esc Esc	Com o campo vazio, abre o menu de rewind; com texto, limpa o campo e guarda o rascunho no histórico
Shift+Tab	Alterna o modo de permissão
Ctrl+C	Interrompe ou limpa o campo; com o Claude ocioso, o segundo toque sai
Ctrl+D	Sai da sessão: o primeiro toque mostra um aviso e o segundo, em até 800 ms, sai. Com texto no campo, apaga o próximo caractere
Ctrl+B	Manda comandos Bash e agentes em execução para segundo plano (no tmux, aperte duas vezes)
Ctrl+R	Busca reversa no histórico de comandos
Ctrl+G	Abre o prompt no seu editor de texto padrão
Ctrl+O	Liga e desliga o visualizador de transcrição
Ctrl+S	Guarda ou recupera o rascunho do prompt
Ctrl+T	Mostra ou oculta a lista de tarefas do Claude
Ctrl+V	Cola imagem da área de transferência (Cmd+V no iTerm2; Alt+V no Windows/WSL)
Ctrl+X Ctrl+K	Para todos os subagents em segundo plano e desliga as respostas automáticas a artifacts (aperte duas vezes em até 3 s)
Option+P / Alt+P	Troca o modelo
Option+T / Alt+T	Liga e desliga o pensamento estendido (sem efeito no Opus 5.5 e nos modelos Fable)
Option+O / Alt+O	Liga e desliga o fast mode
? (campo vazio)	Mostra o painel de atalhos

macOS: alguns atalhos com Option (como Option+P) exigem configurar Option como Meta no terminal. Option+T funciona sem essa configuração.

Mensagens na fila: dá para digitar enquanto o Claude trabalha. Enter coloca a mensagem na fila; Esc interrompe mas preserva a fila; Ctrl+Enter envia a fila na hora (v2.1.275+).

Prefixos no início da linha

Prefixo	Efeito
/	Comando ou skill
!	Shell mode: roda o comando direto, a saída entra na conversa e o Claude responde a ela
@	Menciona um arquivo (uma pasta mostra a listagem de arquivos, não o conteúdo)

Exemplo de shell mode:

! npm test

O teste roda e o Claude explica as falhas sem você precisar de um segundo prompt.

Atenção: comandos com ! rodam fora do sandbox na maioria das sessões, mesmo com o sandbox ligado. Para o Claude não responder à saída, defina respondToBashCommands como false.

---

5. ⚡ Slash commands essenciais

Digite / para ver a lista completa e filtrar.

Categoria	Comandos	Para quê
🏗️ Setup	/init, /memory, /permissions, /config, /doctor	Gerar CLAUDE.md, editar memória e regras, diagnosticar
🧠 Contexto	/context, /compact, /clear, /rewind, /btw	Ver, resumir e limpar o contexto; voltar no tempo; fazer pergunta paralela
🎛️ Modelo e consumo	/model, /effort, /fast, /usage	Trocar o modelo, o nível de esforço e o modo rápido; ver o consumo
🔍 Revisão	/diff, /code-review, /security-review, /simplify, /ultrareview	Revisar mudanças, buscar bugs e falhas de segurança
🗂️ Sessões	/resume, /branch, /fork, /rename, /export	Retomar, ramificar, copiar e exportar conversas
🚀 Escala	/batch, /background, /loop, /schedule, /remote-control	Paralelismo, segundo plano, recorrência, nuvem, controle remoto

Destaques:

• /init analisa o repositório e gera um CLAUDE.md inicial com comandos de build, testes e convenções. Se o arquivo já existir, sugere melhorias em vez de sobrescrever.
• /effort aceita low, medium, high, xhigh, max ou auto, além de status e ultracode.
• /simplify revisa o código alterado com quatro agentes em paralelo. Não procura bugs de corretude; para isso, use /code-review.
• /ultrareview faz uma revisão profunda, com vários agentes, num sandbox na nuvem. Pro e Max têm 3 execuções grátis; depois, exige créditos de uso.
• /usage mostra o custo da sessão, os limites do plano e estatísticas de uso. /cost e /stats são apelidos.
• /btw faz uma pergunta paralela que não entra no histórico. Ele vê a conversa inteira, mas não usa ferramentas.
• /branch cria uma ramificação da conversa e muda para ela; a original continua disponível em /resume. /fork copia a conversa para uma nova sessão em segundo plano e mantém você na atual.
• /background (apelido /bg) desanexa a sessão atual para rodar em segundo plano e libera o terminal.
• /doctor vai além do diagnóstico: aponta skills, servidores MCP e plugins sem uso, hooks lentos, e pode pré-aprovar comandos de leitura que você nega com frequência.

---

6. 🔐 Modos de permissão

Modo	O que roda sem perguntar	Indicado para
auto ⚡	Leituras e edições no diretório de trabalho seguem direto; as demais ações passam por um classificador de segurança	Tarefas longas, menos interrupções
default (Manual)	Só leituras	Trabalho sensível
acceptEdits	Leituras, edições e comandos comuns de arquivo (mkdir, touch, mv, cp)	Iterar no código que você está revisando
plan 🗺️	Leituras (mais comandos aprovados pelo classificador, quando o auto mode está disponível)	Explorar e planejar antes de mudar
dontAsk	Leituras e ferramentas pré-aprovadas; o resto é negado	CI e scripts travados
bypassPermissions ⚠️	Tudo	Apenas containers e VMs isoladas

Como trocar de modo:

• Durante a sessão: Shift+Tab. A partir de auto, o primeiro toque vai para default, e o ciclo segue default → acceptEdits → plan. Modos opcionais, como bypassPermissions, entram depois de plan.
• Ao iniciar: claude --permission-mode plan. manual é apelido de default.
• Plan mode num único prompt: comece o prompt com /plan.
• Como padrão: permissions.defaultMode no settings.json.
• dontAsk não entra no ciclo do Shift+Tab; ative com --permission-mode dontAsk.

Pouca gente sabe: desde a v2.1.283, auto é o modo inicial das sessões interativas no terminal e no VS Code. Regras deny bloqueiam em qualquer modo, inclusive bypassPermissions. Já as regras allow não têm efeito em bypassPermissions.

Limites que valem conhecer:

• permissions.defaultMode com auto ou bypassPermissions é ignorado em settings de projeto (.claude/settings.json) e local. Defina no settings de usuário, no managed, ou passe --permission-mode.
• permissions.disableAutoMode: "disable" remove o auto mode.
• Caminhos protegidos não têm escrita aprovada automaticamente; a exceção principal é bypassPermissions. Regras allow não liberam escrita neles. A lista inclui, entre outros, .git, .gitmodules, .config/git, .vscode, .idea, .husky, .devcontainer, .claude, .bashrc, .bash_profile, .zshrc, .gitconfig, .npmrc, .yarnrc, .mcp.json e .claude.json.
• A primeira leitura fora dos diretórios de trabalho pede confirmação, a menos que permissions.blockReadsOutsideWorkingDirectories esteja desligado.

---

7. 📄 Memória: CLAUDE.md e auto memory

O Claude Code tem dois sistemas de memória, e os dois são carregados como contexto, não como configuração obrigatória.

	CLAUDE.md	Auto memory
Quem escreve	Você	O Claude
Conteúdo	Instruções e regras	Aprendizados e padrões
Escopo	Projeto, usuário ou organização	Por repositório, compartilhado entre worktrees
Carregamento	Toda sessão	Toda sessão (primeiras 200 linhas ou 25 KB)

A auto memory fica em ~/.claude/projects/<projeto>/memory/, com um índice MEMORY.md; o limite de 200 linhas ou 25 KB vale para esse índice. Liga e desliga com o setting autoMemoryEnabled ou em /memory.

Onde fica o CLAUDE.md

Local	Escopo
~/.claude/CLAUDE.md	Você, em todos os projetos
./CLAUDE.md ou ./.claude/CLAUDE.md	O time, versionado no git
./CLAUDE.local.md	Só você, neste projeto (coloque no .gitignore)
./subpasta/CLAUDE.md	Carrega sob demanda, quando o Claude trabalha ali
Caminho gerenciado (managed)	A organização inteira

AGENTS.md: se não houver CLAUDE.md, .claude/CLAUDE.md nem CLAUDE.local.md no diretório de trabalho ou acima dele, o Claude Code lê o AGENTS.md no lugar (v2.1.277+).

Exemplo

# Projeto
- Build: ./gradlew build
- Testes: ./gradlew test
- Nunca editar arquivos em /generated
- Convenções de API: @docs/api-conventions.md

Boas práticas da documentação oficial:

• Mantenha cada arquivo abaixo de ~200 linhas. Arquivos longos consomem contexto e reduzem a aderência.
• Escreva instruções verificáveis: "use indentação de 2 espaços" em vez de "formate bem".
• @caminho/arquivo importa outro arquivo, com profundidade máxima de 4 níveis.
• Adicione uma linha quando o Claude cometer o mesmo erro pela segunda vez.
• Para regras que valem só em parte do código, use .claude/rules/ com escopo por caminho (paths). Regras em ~/.claude/rules/ valem em todos os projetos.
• Em monorepos, claudeMdExcludes ignora arquivos CLAUDE.md de pastas acima que não interessam.

Comandos úteis:

• /memory: edita os CLAUDE.md, liga ou desliga a auto memory e abre a pasta do que o Claude anotou.
• /doctor prompt-audit (v2.1.283+): procura instruções desatualizadas, contraditórias ou que citam arquivos inexistentes, no CLAUDE.md e nas skills.
• /context: mostra quais arquivos de memória foram carregados.

Pegadinha: CLAUDE.md é contexto, não regra obrigatória. Para impedir uma ação de verdade, use regras deny de permissão ou hooks.

---

8. ⚖️ Configuração: settings.json

Precedência, do mais forte para o mais fraco

Nível	Arquivo	Quem afeta
1. Managed	managed-settings.json, MDM ou console do claude.ai	A organização
2. Linha de comando	claude --settings	Esta sessão
3. Projeto local	.claude/settings.local.json	Você, neste projeto
4. Projeto compartilhado	.claude/settings.json	Todo o time
5. Usuário	~/.claude/settings.json	Você, em todos os projetos

Em geral, o nível mais alto vence. Mas listas como permissions.allow e permissions.deny se somam entre os níveis, em vez de uma substituir a outra.

Exemplo: liberar lint e testes, bloquear .env

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "permissions": {
    "allow": [
      "Bash(npm run lint)",
      "Bash(npm run test *)"
    ],
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)"
    ]
  }
}

Detalhes que fazem diferença:

• O arquivo é JSON estrito: comentário ou vírgula sobrando gera erro de configuração.
• Ordem de avaliação: deny, depois ask, depois allow. Um deny amplo vence um allow mais específico.
• O espaço antes do * importa: Bash(git diff *) casa com git diff e argumentos; sem o espaço, casaria também com git diff-index.
• .claudeignore não tem efeito. Para esconder arquivos, use regras Read(...) em deny.
• Prefere não editar JSON? /permissions abre um menu, e /fewer-permission-prompts analisa seu uso e propõe uma allowlist.
• Para saber de onde veio cada valor, /status mostra as fontes de configuração, e claude doctor aponta entradas descartadas.

---

Continua na Parte 2: hooks, subagents, skills, plugins, MCP, checkpoints, modo -p e CI, sessões em paralelo e automação agendada.