​
Panoramica

La modalità headless ti permette 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

​
Opzioni di configurazione

La modalità headless sfrutta tutte le opzioni CLI disponibili in Claude Code. Ecco quelle principali per automazione e scripting:
FlagDescrizioneEsempio
--print, -pEsegui in modalità non interattivaclaude -p "query"
--output-formatSpecifica il formato di output (text, json, stream-json)claude -p --output-format json
--resume, -rRiprendi una conversazione tramite ID sessioneclaude --resume abc123
--continue, -cContinua la conversazione più recenteclaude --continue
--verboseAbilita il logging verbosoclaude --verbose
--append-system-promptAggiungi al prompt di sistema (solo con --print)claude --append-system-prompt "Custom instruction"
--allowedToolsLista separata da spazi di strumenti consentiti, o

stringa di lista separata da virgole di strumenti consentiti		claude --allowedTools mcp__slack mcp__filesystem

claude --allowedTools "Bash(npm install),mcp__filesystem"
--disallowedToolsLista separata da spazi di strumenti negati, o

stringa di lista separata da virgole di strumenti negati		claude --disallowedTools mcp__splunk mcp__github

claude --disallowedTools "Bash(git commit),mcp__github"
--mcp-configCarica server MCP da un file JSONclaude --mcp-config servers.json
--permission-prompt-toolStrumento MCP per gestire i prompt di permesso (solo con --print)claude --permission-prompt-tool mcp__auth__prompt
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 mentre viene ricevuto: 
claude -p "Build an application" --output-format stream-json
Ogni conversazione inizia con un messaggio di sistema init iniziale, seguito da una lista 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 permette turni multipli 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 usando 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 a lunga durata: 
    timeout 300 claude -p "$complex_prompt" || echo "Timed out after 5 minutes"
  • Rispetta i limiti di velocità quando fai richieste multiple aggiungendo ritardi tra le chiamate

​
Risorse correlate