Modalità headless

​

Panoramica

La modalità headless ti consente di eseguire Claude Code programmaticamente da script da riga di comando e strumenti di automazione senza alcuna interfaccia utente interattiva.

​

Utilizzo di base

L’interfaccia principale da riga di comando per Claude Code è il comando claude. Usa il flag --print (o -p) per eseguire in modalità non interattiva e stampare il risultato finale:

claude -p "Stage my changes and write a set of commits for them" \
  --allowedTools "Bash,Read" \
  --permission-mode acceptEdits \
  --cwd /path/to/project

​

Opzioni di configurazione

L’SDK sfrutta tutte le opzioni CLI disponibili in Claude Code. Ecco quelle principali per l’utilizzo dell’SDK:

Per un elenco completo delle opzioni CLI e delle funzionalità, consulta la documentazione di riferimento CLI.

​

Conversazioni multi-turno

Per conversazioni multi-turno, puoi riprendere conversazioni o continuare dalla sessione più recente:

# Continua la conversazione più recente
claude --continue "Now refactor this for better performance"

# Riprendi una conversazione specifica tramite ID sessione
claude --resume 550e8400-e29b-41d4-a716-446655440000 "Update the tests"

# Riprendi in modalità non interattiva
claude --resume 550e8400-e29b-41d4-a716-446655440000 "Fix all linting issues" --no-interactive

​

Formati di output

​

Output di testo (Predefinito)

claude -p "Explain file src/components/Header.tsx"
# Output: This is a React component showing...

​

Output JSON

Restituisce dati strutturati inclusi i metadati:

claude -p "How does the data layer work?" --output-format json

Formato della risposta:

{
  "type": "result",
  "subtype": "success",
  "total_cost_usd": 0.003,
  "is_error": false,
  "duration_ms": 1234,
  "duration_api_ms": 800,
  "num_turns": 6,
  "result": "The response text here...",
  "session_id": "abc123"
}

​

Output JSON in streaming

Trasmette ogni messaggio man mano che viene ricevuto:

claude -p "Build an application" --output-format stream-json

Ogni conversazione inizia con un messaggio di sistema init iniziale, seguito da un elenco di messaggi utente e assistente, seguito da un messaggio di sistema result finale con le statistiche. Ogni messaggio viene emesso come oggetto JSON separato.

​

Formati di input

​

Input di testo (Predefinito)

# Argomento diretto
claude -p "Explain this code"

# Da stdin
echo "Explain this code" | claude -p

​

Input JSON in streaming

Un flusso di messaggi fornito tramite stdin dove ogni messaggio rappresenta un turno utente. Questo consente più turni di una conversazione senza rilanciare il binario claude e consente di fornire indicazioni al modello mentre sta elaborando una richiesta.

Ogni messaggio è un oggetto JSON ‘Messaggio utente’, seguendo lo stesso formato dello schema del messaggio di output. I messaggi sono formattati utilizzando il formato jsonl dove ogni riga di input è un oggetto JSON completo. L’input JSON in streaming richiede -p e --output-format stream-json.

echo '{"type":"user","message":{"role":"user","content":[{"type":"text","text":"Explain this code"}]}}' | claude -p --output-format=stream-json --input-format=stream-json --verbose

​

Esempi di integrazione agente

​

Bot di risposta agli incidenti SRE

#!/bin/bash

# Agente di risposta automatizzata agli incidenti
investigate_incident() {
    local incident_description="$1"
    local severity="${2:-medium}"

    claude -p "Incident: $incident_description (Severity: $severity)" \
      --append-system-prompt "You are an SRE expert. Diagnose the issue, assess impact, and provide immediate action items." \
      --output-format json \
      --allowedTools "Bash,Read,WebSearch,mcp__datadog" \
      --mcp-config monitoring-tools.json
}

# Utilizzo
investigate_incident "Payment API returning 500 errors" "high"

​

Revisione di sicurezza automatizzata

# Agente di audit di sicurezza per pull request
audit_pr() {
    local pr_number="$1"

    gh pr diff "$pr_number" | claude -p \
      --append-system-prompt "You are a security engineer. Review this PR for vulnerabilities, insecure patterns, and compliance issues." \
      --output-format json \
      --allowedTools "Read,Grep,WebSearch"
}

# Utilizzo e salvataggio su file
audit_pr 123 > security-report.json

​

Assistente legale multi-turno

# Revisione di documenti legali con persistenza della sessione
session_id=$(claude -p "Start legal review session" --output-format json | jq -r '.session_id')

# Revisiona il contratto in più passaggi
claude -p --resume "$session_id" "Review contract.pdf for liability clauses"
claude -p --resume "$session_id" "Check compliance with GDPR requirements"
claude -p --resume "$session_id" "Generate executive summary of risks"

​

Migliori pratiche

• Usa il formato di output JSON per l’analisi programmatica delle risposte:

  # Analizza la risposta JSON con jq
  result=$(claude -p "Generate code" --output-format json)
  code=$(echo "$result" | jq -r '.result')
  cost=$(echo "$result" | jq -r '.cost_usd')
  

• Gestisci gli errori con grazia - controlla i codici di uscita e stderr:

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

• Usa la gestione delle sessioni per mantenere il contesto nelle conversazioni multi-turno

• Considera i timeout per operazioni di lunga durata:

  timeout 300 claude -p "$complex_prompt" || echo "Timed out after 5 minutes"
  

• Rispetta i limiti di velocità quando fai più richieste aggiungendo ritardi tra le chiamate

​

Risorse correlate

• Utilizzo e controlli CLI - Documentazione CLI completa
• Flussi di lavoro comuni - Guide passo-passo per casi d’uso comuni