​
Visão Geral

O modo headless permite executar Claude Code programaticamente a partir de scripts de linha de comando e ferramentas de automação sem qualquer interface interativa.

​
Uso Básico

A interface de linha de comando principal para Claude Code é o comando claude. Use a flag --print (ou -p) para executar em modo não interativo e imprimir o resultado final:

claude -p "Prepare minhas alterações e escreva um conjunto de commits para elas" \
  --allowedTools "Bash,Read" \
  --permission-mode acceptEdits \
  --cwd /path/to/project

​
Opções de Configuração

O SDK aproveita todas as opções CLI disponíveis no Claude Code. Aqui estão as principais para uso do SDK:

FlagDescriçãoExemplo
--print, -pExecutar em modo não interativoclaude -p "consulta"
--output-formatEspecificar formato de saída (text, json, stream-json)claude -p --output-format json
--resume, -rRetomar uma conversa por ID de sessãoclaude --resume abc123
--continue, -cContinuar a conversa mais recenteclaude --continue
--verboseHabilitar log detalhadoclaude --verbose
--append-system-promptAnexar ao prompt do sistema (apenas com --print)claude --append-system-prompt "Instrução personalizada"
--allowedToolsLista separada por espaços de ferramentas permitidas, ou

string de lista separada por vírgulas de ferramentas permitidas		claude --allowedTools mcp__slack mcp__filesystem

claude --allowedTools "Bash(npm install),mcp__filesystem"
--disallowedToolsLista separada por espaços de ferramentas negadas, ou

string de lista separada por vírgulas de ferramentas negadas		claude --disallowedTools mcp__splunk mcp__github

claude --disallowedTools "Bash(git commit),mcp__github"
--mcp-configCarregar servidores MCP de um arquivo JSONclaude --mcp-config servers.json
--permission-prompt-toolFerramenta MCP para lidar com prompts de permissão (apenas com --print)claude --permission-prompt-tool mcp__auth__prompt

Para uma lista completa de opções CLI e recursos, consulte a documentação de referência CLI.

​
Conversas Multi-turno

Para conversas multi-turno, você pode retomar conversas ou continuar da sessão mais recente:

# Continuar a conversa mais recente
claude --continue "Agora refatore isso para melhor desempenho"

# Retomar uma conversa específica por ID de sessão
claude --resume 550e8400-e29b-41d4-a716-446655440000 "Atualize os testes"

# Retomar em modo não interativo
claude --resume 550e8400-e29b-41d4-a716-446655440000 "Corrija todos os problemas de linting" --no-interactive

​
Formatos de Saída

​
Saída de Texto (Padrão)

claude -p "Explique o arquivo src/components/Header.tsx"
# Saída: Este é um componente React mostrando...

​
Saída JSON

Retorna dados estruturados incluindo metadados:

claude -p "Como funciona a camada de dados?" --output-format json

Formato de resposta:

{
  "type": "result",
  "subtype": "success",
  "total_cost_usd": 0.003,
  "is_error": false,
  "duration_ms": 1234,
  "duration_api_ms": 800,
  "num_turns": 6,
  "result": "O texto da resposta aqui...",
  "session_id": "abc123"
}

​
Saída JSON em Streaming

Transmite cada mensagem conforme é recebida:

claude -p "Construa uma aplicação" --output-format stream-json

Cada conversa começa com uma mensagem inicial do sistema init, seguida por uma lista de mensagens do usuário e assistente, seguida por uma mensagem final do sistema result com estatísticas. Cada mensagem é emitida como um objeto JSON separado.

​
Formatos de Entrada

​
Entrada de Texto (Padrão)

# Argumento direto
claude -p "Explique este código"

# Do stdin
echo "Explique este código" | claude -p

​
Entrada JSON em Streaming

Um fluxo de mensagens fornecido via stdin onde cada mensagem representa um turno do usuário. Isso permite múltiplos turnos de uma conversa sem relançar o binário claude e permite fornecer orientação ao modelo enquanto está processando uma solicitação.

Cada mensagem é um objeto JSON ‘Mensagem do usuário’, seguindo o mesmo formato do esquema de mensagem de saída. As mensagens são formatadas usando o formato jsonl onde cada linha de entrada é um objeto JSON completo. A entrada JSON em streaming requer -p e --output-format stream-json.

echo '{"type":"user","message":{"role":"user","content":[{"type":"text","text":"Explique este código"}]}}' | claude -p --output-format=stream-json --input-format=stream-json --verbose

​
Exemplos de Integração de Agente

​
Bot de Resposta a Incidentes SRE

#!/bin/bash

# Agente automatizado de resposta a incidentes
investigate_incident() {
    local incident_description="$1"
    local severity="${2:-medium}"

    claude -p "Incidente: $incident_description (Severidade: $severity)" \
      --append-system-prompt "Você é um especialista SRE. Diagnostique o problema, avalie o impacto e forneça itens de ação imediatos." \
      --output-format json \
      --allowedTools "Bash,Read,WebSearch,mcp__datadog" \
      --mcp-config monitoring-tools.json
}

# Uso
investigate_incident "API de pagamento retornando erros 500" "high"

​
Revisão de Segurança Automatizada

# Agente de auditoria de segurança para pull requests
audit_pr() {
    local pr_number="$1"

    gh pr diff "$pr_number" | claude -p \
      --append-system-prompt "Você é um engenheiro de segurança. Revise este PR para vulnerabilidades, padrões inseguros e problemas de conformidade." \
      --output-format json \
      --allowedTools "Read,Grep,WebSearch"
}

# Uso e salvar em arquivo
audit_pr 123 > security-report.json

​
Assistente Jurídico Multi-turno

# Revisão de documento jurídico com persistência de sessão
session_id=$(claude -p "Iniciar sessão de revisão jurídica" --output-format json | jq -r '.session_id')

# Revisar contrato em múltiplas etapas
claude -p --resume "$session_id" "Revisar contract.pdf para cláusulas de responsabilidade"
claude -p --resume "$session_id" "Verificar conformidade com requisitos GDPR"
claude -p --resume "$session_id" "Gerar resumo executivo dos riscos"

​
Melhores Práticas

  • Use formato de saída JSON para análise programática de respostas:

    # Analisar resposta JSON com jq
result=$(claude -p "Gerar código" --output-format json)
code=$(echo "$result" | jq -r '.result')
cost=$(echo "$result" | jq -r '.cost_usd')

  • Trate erros graciosamente - verifique códigos de saída e stderr:

    if ! claude -p "$prompt" 2>error.log; then
    echo "Erro ocorreu:" >&2
    cat error.log >&2
    exit 1
fi

  • Use gerenciamento de sessão para manter contexto em conversas multi-turno

  • Considere timeouts para operações de longa duração:

    timeout 300 claude -p "$complex_prompt" || echo "Timeout após 5 minutos"

  • Respeite limites de taxa ao fazer múltiplas solicitações adicionando atrasos entre chamadas

​
Recursos Relacionados