Claude Code CLI：完整技術指南

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.
Aviso: o Claude Code é atualizado com frequência. Antes de usar este material como referência, confira as mudanças com /release-notes e claude --help.

📑 Índice

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
10. Subagents
11. Skills, comandos e plugins
12. MCP no terminal
13. Checkpoints e gestão de contexto
14. Modo não interativo (-p) e CI
15. Sessões em paralelo
16. Automação agendada
17. Trabalho remoto e entre dispositivos
18. ✅ O que só o CLI faz
19. ❌ O que o CLI não faz
20. 🤫 Recursos pouco conhecidos
21. 🏆 Fluxo de trabalho recomendado
22. ⚠️ Cuidados e limitações
23. 📚 Fontes oficiais

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. O agente trabalha em ciclo:

1. 🔍 Explora: lê e busca no repositório.
2. 🗺️ Planeja: propõe uma abordagem.
3. ✏️ Edita: altera os arquivos.
4. ▶️ Executa: roda testes, build e git.
5. ✅ Verifica: repete até o resultado estar certo.

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 valem em todas essas superfícies.

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)

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, Fedora, RHEL, Alpine).

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

Atualizações

O canal de atualização (latest ou stable) é definido pelo setting autoUpdatesChannel, ou em /config. O stable costuma estar cerca de uma semana atrás e pula versões com regressões graves.

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 é impresso no terminal e não fica salvo.

3. 🚪 Comandos de entrada

4. ⌨️ Atalhos de teclado e prefixos

Atalhos principais

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

Prefixos no início da linha

Exemplo de shell mode:

! npm test

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

5. ⚡ Slash commands essenciais

Digite / para ver a lista completa e filtrar.

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.
• /effort aceita low, medium, high, xhigh, max ou auto.
• /simplify revisa o código alterado com quatro agentes em paralelo.
• /ultrareview faz uma revisão profunda, com vários agentes, num sandbox na nuvem.
• /usage mostra o custo da sessão e os limites do plano. /cost é um apelido.

6. 🔐 Modos de permissão

Como trocar de modo:

• Durante a sessão: Shift+Tab. A partir de auto, o ciclo é auto → default → acceptEdits → plan.
• Ao iniciar: claude --permission-mode plan.
• 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. E regras deny bloqueiam em qualquer modo, inclusive bypassPermissions.

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.

Onde fica o CLAUDE.md

Se o repositório tem um AGENTS.md e nenhum CLAUDE.md (ou CLAUDE.local.md), o Claude Code lê o AGENTS.md no lugar dele.

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

Comandos úteis:

• /memory: edita os CLAUDE.md, liga ou desliga a auto memory e mostra o que o Claude anotou.
• /doctor prompt-audit: procura instruções desatualizadas, contraditórias ou que citam arquivos inexistentes.

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

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.
• 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.
• Prefere não editar JSON? /permissions abre um menu, e /fewer-permission-prompts analisa seu uso e propõe uma allowlist.

9. 🪝 Hooks

O que é: um comando seu (ou uma chamada HTTP, ferramenta MCP, prompt ou agente) que roda em pontos fixos do ciclo de vida da sessão. Ele não depende de o Claude decidir executá-lo.

Para que serve: formatar código depois de cada edição, bloquear comandos perigosos, registrar todo comando executado, notificar o time, carregar contexto no início da sessão.

Eventos mais usados

SessionStart, UserPromptSubmit, PreToolUse, PermissionRequest, PostToolUse, Stop, PreCompact, PostCompact (a documentação lista dezenas de eventos).

Exemplo: formatar após cada edição

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          { "type": "command", "command": "npm run format" }
        ]
      }
    ]
  }
}

Códigos de saída

Tipos de handler: command, http, mcp_tool, prompt e agent (este é experimental).

Dicas:

• /hooks mostra os hooks configurados (só leitura). A configuração fica no settings.json.
• Na maioria dos eventos, se o hook falhar ou estourar o tempo, a ação segue. Para bloquear nesse caso, use "onFailure": "block" em hooks command ou http (v2.1.295+; sem efeito em Stop, SubagentStop, TaskCompleted e TeammateIdle).
• Para reinjetar instruções depois de uma compactação, use um hook SessionStart com matcher compact.

10. 👥 Subagents

O que é: um assistente especializado que roda na sua própria janela de contexto, com prompt de sistema, ferramentas e permissões próprios. Ele devolve só um resumo, então logs e resultados de busca extensos não poluem a conversa principal.

Subagents nativos: Explore (busca rápida e só leitura), Plan (pesquisa no plan mode) e general-purpose (tarefas complexas com todas as ferramentas).

Criar o seu

Arquivo em .claude/agents/ (projeto) ou ~/.claude/agents/ (todos os projetos):

---
name: code-reviewer
description: Reviews code for quality and best practices
tools: Read, Glob, Grep
model: sonnet
---
You are a code reviewer. Give specific, actionable feedback.

Só name e description são obrigatórios. Outros campos: disallowedTools, model, permissionMode, skills, mcpServers, hooks, memory, isolation: worktree.

Como invocar

• Automático: o Claude delega com base na description.
• Explícito: cite o subagent no prompt ou mencione com @.
• Sessão inteira: claude --agent code-reviewer.
• Definição temporária, só para a sessão:

claude --agents '{"debugger": {"description": "Debugs errors", "prompt": "You are an expert debugger."}}'

Recursos extras:

• /subtask <tarefa> cria um subagent "forked", que herda a conversa inteira e trabalha em segundo plano.
• Ctrl+B manda um subagent em execução para segundo plano.
• Subagents num modelo mais barato reduzem custo, e um subagent sem Edit/Write só consegue ler.

11. 🧩 Skills, comandos e plugins

Skills

O que é: um arquivo SKILL.md com instruções (e arquivos de apoio opcionais) que ensina um procedimento. O Claude carrega a skill quando ela é relevante, ou você chama com /nome.

---
name: deploy
description: Deploy the application to production
disable-model-invocation: true
---

Deploy $ARGUMENTS to production:
1. Run the test suite
2. Build the application
3. Push to the deployment target

• disable-model-invocation: true: só você pode chamar (ideal para deploy).
• user-invocable: false: só o Claude pode chamar.
• $ARGUMENTS, $0, $1: recebem argumentos.
• Arquivos em .claude/commands/ continuam funcionando e também viram /nome; a skill acrescenta arquivos de apoio e controle de invocação.
• /skills lista as skills; /skill-doctor mostra o custo de contexto e o uso de cada uma.

Custo de contexto: a descrição de cada skill fica sempre no contexto (description + when_to_use são truncados em 1.536 caracteres na listagem). O conteúdo completo só carrega quando a skill é usada.

Skills que já vêm prontas: /code-review, /batch, /debug, /loop, /claude-api, /verify, /run, /simplify, entre outras.

Plugins

O que é: um diretório que empacota skills, agentes, hooks e servidores MCP para instalar como uma unidade.

• /plugin abre o menu; a aba Discover lista os plugins dos seus marketplaces.
• O marketplace oficial da Anthropic é adicionado na primeira sessão interativa.
• Pelo shell: claude plugin install <plugin>@<marketplace>.
• Escopos de instalação: usuário, projeto (via .claude/settings.json) ou local.

Atenção: um plugin ativo entra em todas as sessões, consome contexto e roda com as suas permissões. Revise antes de instalar.

12. 🔌 MCP no terminal

O MCP (Model Context Protocol) é um padrão aberto para conectar ferramentas de IA a fontes de dados externas.

Adicionar servidores

bash
# Remoto via HTTP (recomendado para servidores remotos)
claude mcp add --transport http notion https://mcp.notion.com/mcp

# Remoto com cabeçalho de autenticação
claude mcp add --transport http secure-api https://api.example.com/mcp \
  --header "Authorization: Bearer your-token"

# L