Vai al contenuto principale

Documentation Index

Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt

Use this file to discover all available pages before exploring further.

Starting June 15, 2026, Agent SDK and claude -p usage on subscription plans will draw from a new monthly Agent SDK credit, separate from your interactive usage limits. See Use the Claude Agent SDK with your Claude plan for details.
L’Agent SDK ti fornisce gli stessi strumenti, il ciclo dell’agente e la gestione del contesto che alimentano Claude Code. È disponibile come CLI per script e CI/CD, oppure come pacchetti Python e TypeScript per il controllo programmatico completo. Per eseguire Claude Code in modalità non interattiva, passa -p con il tuo prompt e qualsiasi opzione CLI: 
claude -p "Find and fix the bug in auth.py" --allowedTools "Read,Edit,Bash"
Questa pagina copre l’utilizzo dell’Agent SDK tramite la CLI (claude -p). Per i pacchetti SDK Python e TypeScript con output strutturati, callback di approvazione degli strumenti e oggetti messaggio nativi, consulta la documentazione completa dell’Agent SDK.

​
Utilizzo di base

Aggiungi il flag -p (o --print) a qualsiasi comando claude per eseguirlo in modo non interattivo. Tutte le opzioni CLI funzionano con -p, incluse: Questo esempio chiede a Claude una domanda sulla tua base di codice e stampa la risposta: 
claude -p "What does the auth module do?"

​
Inizia più velocemente con la modalità bare

Aggiungi --bare per ridurre il tempo di avvio saltando l’auto-discovery di hooks, skills, plugins, server MCP, memoria automatica e CLAUDE.md. Senza di esso, claude -p carica lo stesso contesto che una sessione interattiva avrebbe, incluso tutto ciò che è configurato nella directory di lavoro o in ~/.claude. La modalità bare è utile per CI e script dove hai bisogno dello stesso risultato su ogni macchina. Un hook nel ~/.claude di un collega o un server MCP nel .mcp.json del progetto non verranno eseguiti, perché la modalità bare non li legge mai. Solo i flag che passi esplicitamente hanno effetto. Questo esempio esegue un’attività di riepilogo una tantum in modalità bare e pre-approva lo strumento Read in modo che la chiamata si completi senza un prompt di autorizzazione: 
claude --bare -p "Summarize this file" --allowedTools "Read"
In modalità bare Claude ha accesso agli strumenti Bash, lettura file e modifica file. Passa qualsiasi contesto di cui hai bisogno con un flag:
Per caricareUtilizza
Aggiunte al prompt di sistema--append-system-prompt, --append-system-prompt-file
Impostazioni--settings <file-or-json>
Server MCP--mcp-config <file-or-json>
Agenti personalizzati--agents <json>
Un plugin--plugin-dir <path>, --plugin-url <url>
La modalità bare salta le letture OAuth e keychain. L’autenticazione Anthropic deve provenire da ANTHROPIC_API_KEY o da un apiKeyHelper nel JSON passato a --settings. Bedrock, Vertex e Foundry utilizzano le loro credenziali provider usuali.
--bare è la modalità consigliata per le chiamate con script e SDK, e diventerà l’impostazione predefinita per -p in una versione futura.

​
Esempi

Questi esempi evidenziano i modelli CLI comuni. Per CI e altre chiamate con script, aggiungi --bare in modo che non raccolgano qualsiasi cosa sia configurata localmente.

​
Inviare dati attraverso Claude

La modalità non interattiva legge stdin, quindi puoi inviare dati e reindirizzare la risposta come qualsiasi altro strumento da riga di comando. Questo esempio invia un log di compilazione a Claude e scrive la spiegazione in un file: 
cat build-error.txt | claude -p 'concisely explain the root cause of this build error' > output.txt
Con --output-format json, il payload della risposta include total_cost_usd e una suddivisione dei costi per modello, quindi i chiamanti con script possono tracciare la spesa per invocazione senza consultare il dashboard di utilizzo.
A partire da Claude Code v2.1.128, stdin inviato tramite pipe è limitato a 10MB. Se superi il limite, Claude Code esce con un errore chiaro e uno stato diverso da zero. Per lavorare con input più grandi, scrivi il contenuto in un file e fai riferimento al percorso del file nel tuo prompt invece di inviarlo tramite pipe.

​
Aggiungere Claude a uno script di compilazione

Puoi avvolgere una chiamata non interattiva in uno script per utilizzare Claude come linter o revisore specifico del progetto. Questo script package.json invia il diff rispetto a main a Claude e gli chiede di segnalare i refusi. Inviare il diff tramite pipe significa che Claude non ha bisogno del permesso Bash per leggerlo, e le virgolette doppie sfuggite mantengono lo script portabile su Windows: 
{
  "scripts": {
    "lint:claude": "git diff main | claude -p \"you are a typo linter. for each typo in this diff, report filename:line on one line and the issue on the next. return nothing else.\""
  }
}

​
Ottenere output strutturato

Utilizza --output-format per controllare come vengono restituite le risposte:
  • text (predefinito): output di testo semplice
  • json: JSON strutturato con risultato, ID sessione e metadati
  • stream-json: JSON delimitato da newline per lo streaming in tempo reale
Questo esempio restituisce un riepilogo del progetto come JSON con metadati della sessione, con il risultato del testo nel campo result: 
claude -p "Summarize this project" --output-format json
Per ottenere output conforme a uno schema specifico, utilizza --output-format json con --json-schema e una definizione JSON Schema. La risposta include metadati sulla richiesta (ID sessione, utilizzo, ecc.) con l’output strutturato nel campo structured_output. Questo esempio estrae i nomi delle funzioni e li restituisce come array di stringhe: 
claude -p "Extract the main function names from auth.py" \
  --output-format json \
  --json-schema '{"type":"object","properties":{"functions":{"type":"array","items":{"type":"string"}}},"required":["functions"]}'
Utilizza uno strumento come jq per analizzare la risposta ed estrarre campi specifici:
# Extract the text result
claude -p "Summarize this project" --output-format json | jq -r '.result'

# Extract structured output
claude -p "Extract function names from auth.py" \
  --output-format json \
  --json-schema '{"type":"object","properties":{"functions":{"type":"array","items":{"type":"string"}}},"required":["functions"]}' \
  | jq '.structured_output'

​
Streaming delle risposte

Utilizza --output-format stream-json con --verbose e --include-partial-messages per ricevere i token mentre vengono generati. Ogni riga è un oggetto JSON che rappresenta un evento: 
claude -p "Explain recursion" --output-format stream-json --verbose --include-partial-messages
L’esempio seguente utilizza jq per filtrare i delta di testo e visualizzare solo il testo in streaming. Il flag -r restituisce stringhe non elaborate (senza virgolette) e -j si unisce senza newline in modo che i token fluiscano continuamente: 
claude -p "Write a poem" --output-format stream-json --verbose --include-partial-messages | \
  jq -rj 'select(.type == "stream_event" and .event.delta.type? == "text_delta") | .event.delta.text'
Quando una richiesta API non riesce con un errore ritentabile, Claude Code emette un evento system/api_retry prima di ritentare. Puoi utilizzarlo per visualizzare il progresso del tentativo o implementare una logica di backoff personalizzata.
CampoTipoDescrizione
type"system"tipo di messaggio
subtype"api_retry"identifica questo come un evento di tentativo
attemptintegernumero del tentativo corrente, a partire da 1
max_retriesintegertentativi totali consentiti
retry_delay_msintegermillisecondi fino al prossimo tentativo
error_statusinteger o nullcodice di stato HTTP, o null per errori di connessione senza risposta HTTP
errorstringcategoria di errore: authentication_failed, oauth_org_not_allowed, billing_error, rate_limit, invalid_request, server_error, max_output_tokens, o unknown
uuidstringidentificatore evento univoco
session_idstringsessione a cui appartiene l’evento
L’evento system/init segnala i metadati della sessione inclusi il modello, gli strumenti, i server MCP e i plugin caricati. È il primo evento nel flusso a meno che CLAUDE_CODE_SYNC_PLUGIN_INSTALL non sia impostato, nel qual caso gli eventi plugin_install lo precedono. Utilizza i campi plugin per far fallire CI quando un plugin non è stato caricato:
CampoTipoDescrizione
pluginsarrayplugin che sono stati caricati con successo, ognuno con name e path
plugin_errorsarrayerrori di caricamento del plugin, ognuno con plugin, type e message. Include versioni di dipendenza non soddisfatte e errori di caricamento di --plugin-dir come un percorso mancante o un archivio non valido. I plugin interessati vengono declassati e assenti da plugins. La chiave viene omessa quando non ci sono errori
Quando CLAUDE_CODE_SYNC_PLUGIN_INSTALL è impostato, Claude Code emette eventi system/plugin_install mentre i plugin del marketplace si installano prima del primo turno. Utilizza questi per visualizzare il progresso dell’installazione nella tua interfaccia utente.
CampoTipoDescrizione
type"system"tipo di messaggio
subtype"plugin_install"identifica questo come un evento di installazione plugin
status"started", "installed", "failed", o "completed"started e completed racchiudono l’installazione complessiva; installed e failed segnalano i singoli marketplace
namestring, opzionalenome del marketplace, presente su installed e failed
errorstring, opzionalemessaggio di errore, presente su failed
uuidstringidentificatore evento univoco
session_idstringsessione a cui appartiene l’evento
Per lo streaming programmatico con callback e oggetti messaggio, consulta Stream responses in real-time nella documentazione dell’Agent SDK.

​
Approvare automaticamente gli strumenti

Utilizza --allowedTools per consentire a Claude di utilizzare determinati strumenti senza chiedere. Questo esempio esegue una suite di test e corregge i guasti, consentendo a Claude di eseguire comandi Bash e leggere/modificare file senza chiedere il permesso: 
claude -p "Run the test suite and fix any failures" \
  --allowedTools "Bash,Read,Edit"
Per impostare una linea di base per l’intera sessione invece di elencare i singoli strumenti, passa una modalità di autorizzazione. dontAsk nega qualsiasi cosa non sia nelle tue regole permissions.allow o nel set di comandi di sola lettura, utile per esecuzioni CI bloccate. acceptEdits consente a Claude di scrivere file senza chiedere e approva automaticamente anche i comandi del filesystem comuni come mkdir, touch, mv e cp. Gli altri comandi shell e le richieste di rete hanno ancora bisogno di una voce --allowedTools o di una regola permissions.allow, altrimenti l’esecuzione si interrompe quando uno viene tentato: 
claude -p "Apply the lint fixes" --permission-mode acceptEdits

​
Creare un commit

Questo esempio esamina le modifiche in staging e crea un commit con un messaggio appropriato: 
claude -p "Look at my staged changes and create an appropriate commit" \
  --allowedTools "Bash(git diff *),Bash(git log *),Bash(git status *),Bash(git commit *)"
Il flag --allowedTools utilizza la sintassi delle regole di autorizzazione. Lo spazio finale * abilita la corrispondenza dei prefissi, quindi Bash(git diff *) consente qualsiasi comando che inizia con git diff. Lo spazio prima di * è importante: senza di esso, Bash(git diff*) corrisponderebbe anche a git diff-index.
Le skills richiamate dall’utente come /commit e i comandi incorporati sono disponibili solo in modalità interattiva. In modalità -p, descrivi invece l’attività che desideri completare.

​
Personalizzare il prompt di sistema

Utilizza --append-system-prompt per aggiungere istruzioni mantenendo il comportamento predefinito di Claude Code. Questo esempio invia un diff PR a Claude e gli istruisce di esaminarlo per vulnerabilità di sicurezza: 
gh pr diff "$1" | claude -p \
  --append-system-prompt "You are a security engineer. Review for vulnerabilities." \
  --output-format json
Consulta i flag del prompt di sistema per ulteriori opzioni incluso --system-prompt per sostituire completamente il prompt predefinito.

​
Continuare le conversazioni

Utilizza --continue per continuare la conversazione più recente, oppure --resume con un ID sessione per continuare una conversazione specifica. Questo esempio esegue una revisione, quindi invia prompt di follow-up: 
# First request
claude -p "Review this codebase for performance issues"

# Continue the most recent conversation
claude -p "Now focus on the database queries" --continue
claude -p "Generate a summary of all issues found" --continue
Se stai eseguendo più conversazioni, acquisisci l’ID sessione per riprendere una specifica: 
session_id=$(claude -p "Start a review" --output-format json | jq -r '.session_id')
claude -p "Continue that review" --resume "$session_id"

​
Passaggi successivi