Passa al contenuto principale

La CLI claude: i flag che cambiano i risultati

Intermedio

La maggior parte delle persone impara tre cose sulla riga di comando di Claude Code — claude, claude -c e claude -p — e si ferma lì. È un buon punto in cui fermarsi se lo usi sempre seduto davanti al terminale. Nel momento in cui metti Claude Code in uno script, in un job di CI, in una coda in background o nelle mani di un collega, i flag smettono di essere comodità e diventano la differenza tra un'esecuzione che costa un dollaro e una che resta appesa per un'ora.

Questa pagina non è una seconda copia della tabella di riferimento. È l'ordine in cui imparare la superficie, i flag che cambiano davvero ciò che accade e le quattro trappole che fanno perdere tempo vero.

What you'll learn
  • I sei tipi di sessione che puoi avviare, e quale flag sceglie ciascuno
  • Il contratto a cinque flag che rende un'esecuzione non presidiata limitata, risolvibile e analizzabile
  • Perché modificare --append-system-prompt e rilanciare --continue sembra non fare nulla — la regola del prompt registrato
  • Come differiscono --bare, --safe-mode e --restricted, e quando scegliere ciascuno
  • Gestire le sessioni in background dalla shell: agents, attach, logs, respawn, rm, daemon
  • Le coppie di flag che le persone confondono: --tools contro --allowedTools contro --disallowedTools

Parti dalla domanda: che tipo di sessione è?​

Ogni altra decisione discende da questa. Claude Code può avviare sei cose sostanzialmente diverse, e il flag che sceglie quella giusta è di solito la prima cosa che scrivi.

VuoiFlagOttieni
Una conversazione che segui(nessuno)Sessione interattiva in questo terminale
Una risposta, poi uscita-p / --printEsecuzione non interattiva, output su stdout
Lavoro che sopravvive a questo terminale--bg / --backgroundUna sessione in background; stampa il suo ID e come gestirla
Un ramo isolato su cui sperimentare-w / --worktreeUn git worktree in <repo>/.claude/worktrees/<name>
Lavoro sulle macchine di Anthropic--cloudUna sessione cloud, o un seguito accodato in una esistente
Pilotare questa sessione dal telefono--rc / --remote-controlUna sessione interattiva controllabile anche da claude.ai o dall'app Claude

Due di questi non si possono combinare: --bg e -p si escludono a vicenda, perché uno ritorna subito e l'altro attende una risposta. Se vuoi un comando shell in background invece di una sessione Claude, abbina --bg a --exec:

Esegui la suite di test come job in background, non come sessione Claude

claude --bg --exec 'pytest -x'

E --bg verifica l'attendibilità dell'area di lavoro per la directory prima di partire — quindi una sessione in background in un repository non attendibile fallisce subito invece che a metà strada.

Il contratto a cinque flag per le esecuzioni non presidiate​

È la cosa di maggior valore in questa pagina. Un claude -p non presidiato può andare storto in tre modi che una sessione interattiva semplicemente non ha: può bloccarsi su richieste di permesso a cui nessuno è presente a rispondere, può ciclare molto più a lungo del previsto e può emettere prosa quando il tuo script aveva bisogno di dati. Cinque flag chiudono tutti e tre i rischi.

Guided walkthrough1 of 5
  1. `claude -p "query"` stampa la risposta ed esce. Tutto ciò che segue vale solo in modalità print, quindi questo flag è la porta d'ingresso per il resto.

Uno step di CI che non può bloccarsi, ciclare all'infinito né spendere troppo

claude -p "Review the staged diff and list bugs" \
--permission-prompts none \
--allowedTools "Read" "Bash(git diff *)" \
--max-turns 6 \
--max-budget-usd 2.00 \
--output-format json
--max-budget-usd è una stima, non la tua fattura
  • Claude Code controlla il tetto rispetto alla propria stima di costo lato client, che può differire da ciò che ti viene fatturato.
  • Quando riprendi una conversazione con --continue o --resume, i totali ripristinati dalle esecuzioni precedenti non contano per il tetto — quindi tre esecuzioni riprese con un tetto di 2 $ possono spendere più di 2 $ in totale.
  • Trattalo come un interruttore di sicurezza per una singola esecuzione. Per un vero tetto su un intero account o progetto, vedi Tetti di spesa rigidi.

Per l'intera impostazione su come lasciar procedere un'esecuzione senza un umano — cosa consentire, cosa mascherare, cosa registrare — vedi Rendere robuste le esecuzioni autonome e Modalità headless e l'Agent SDK. Per i tetti a livello di provider, Tetti di spesa rigidi.

La famiglia del system prompt, e la trappola al suo interno​

Cinque flag modellano il system prompt. Quattro ne impostano il testo; il quinto decide se la conversazione conserva il testo con cui è partita.

FlagCosa fa
--system-promptSostituisce l'intero prompt predefinito con il tuo testo
--system-prompt-fileLo sostituisce con il contenuto di un file
--append-system-promptAggiunge il tuo testo in coda al prompt predefinito
--append-system-prompt-fileAggiunge in coda il contenuto di un file al prompt predefinito
--system-prompt-snapshotoff ricostruisce il prompt a ogni richiesta; on (il predefinito) riusa quello registrato

La scelta tra aggiungere e sostituire è una scelta sull'identità. Aggiungere mantiene le indicazioni predefinite di Claude Code sugli strumenti, le istruzioni di sicurezza e le convenzioni di programmazione, e ci sovrappone le tue regole — giusto per istruzioni per singola esecuzione, formattazione dell'output o contesto di progetto. Sostituire elimina tutto questo, comprese le indicazioni sugli strumenti, il che lo rende giusto solo quando la superficie non è davvero un assistente di programmazione: un agente non di programmazione in una pipeline che nessuno guarda. Se sostituisci, ti prendi la responsabilità di tutto ciò di cui il compito ha ancora bisogno.

Puoi combinarli. Passare un flag di aggiunta insieme a un flag di sostituzione sostituisce il predefinito e poi aggiunge il tuo testo. Dalla v2.1.283 puoi anche passare un flag insieme alla sua forma file — --append-system-prompt e --append-system-prompt-file — e Claude Code usa entrambi, con il contenuto del file per primo indipendentemente dall'ordine in cui li hai scritti.

La trappola: una conversazione ripresa riusa il prompt con cui è nata
  • Claude Code costruisce il system prompt una sola volta, alla prima richiesta di una conversazione, e lo registra nella sessione.
  • Finché la conversazione non viene compattata, ogni richiesta successiva usa quel prompt registrato — anche dopo --resume o --continue.
  • Quindi modifichi il testo di --append-system-prompt, rilanci claude --continue e non cambia nulla. Il flag non è rotto; la conversazione sta ancora usando la registrazione.
  • Il nuovo testo ha effetto quando la conversazione si compatta, o in una conversazione nuova di zecca.
  • Per iterare sulla formulazione tra esecuzioni --continue, passa --system-prompt-snapshot off e il prompt viene ricostruito a ogni richiesta. Richiede la v2.1.257 o successiva.

C'è un altro trucco da conoscere in un prompt sostitutivo che mescola istruzioni stabili e contesto per singola esecuzione. Metti tra le due parti una riga contenente solo __SYSTEM_PROMPT_DYNAMIC_BOUNDARY__: Claude Code divide alla prima riga di questo tipo e la rimuove, così la parte sopra resta in cache mentre quella sotto cambia. Richiede la v2.1.275 o successiva. Perché questo conta per la tua fattura è l'argomento di Prompt Caching e Ottimizzazione dei Costi.

E per i carichi di lavoro scriptati multiutente, --exclude-dynamic-system-prompt-sections sposta il contesto per singolo utente, come la posizione della memoria automatica, fuori dal system prompt e dentro il primo messaggio utente — così lo stesso compito su macchine diverse condivide un unico prefisso in cache. Si applica solo al prompt predefinito ed è ignorato quando imposti --system-prompt o --system-prompt-file.

Tre flag che spengono le cose, e non sono uguali​

Le persone li usano in modo intercambiabile e poi si chiedono perché il sintomo non si sia mosso. Risolvono tre problemi diversi.

--bare--safe-mode--restricted
Il problema che risolveL'avvio è troppo lento per una chiamata scriptataLa mia configurazione è rotta e non so quale parteUn harness di valutazione non deve toccare questa macchina condivisa
CLAUDE.md, skill, comandi, subagent, plugin, MCP, memoria automaticaNon rilevatiNon caricatiSi caricano solo le impostazioni gestite e --settings
Strumenti integratiBash, lettura file, modifica fileFunzionano normalmenteGli strumenti che eseguono comandi/codice e WebFetch sono rimossi a meno che non siano nominati singolarmente in --tools
Accesso ai fileNormaleNormaleConfinato alle directory di lavoro
bypassPermissionsConsentitoConsentitoRifiutato
Policy gestitaSi applicaSi applica ancora, inclusi gli hook di policy e la status lineSi applica
Effetto collateraleImposta CLAUDE_CODE_SIMPLEImposta CLAUDE_CODE_SAFE_MODERifiuta di creare sessioni cloud

Leggi la tabella come una progressione di intenti: --bare riguarda la velocità, --safe-mode la diagnosi, --restricted il contenimento. Un dettaglio utile: le skill in una directory passata con --add-dir si caricano comunque con --bare, ed è così che tieni esattamente una capacità in un'esecuzione altrimenti ridotta all'osso.

--safe-mode è quello da scegliere per primo quando qualcosa si comporta male e non riesci a capire se è Claude Code o la tua configurazione — anche quando stai cercando di capire se è una personalizzazione a innescare il fallback automatico del modello. Abbinalo a claude doctor, che stampa diagnostica di sola lettura su installazione e impostazioni senza avviare alcuna sessione. (Il comando /doctor dentro la sessione è un'altra cosa: può anche applicare correzioni.) Altro debugging a partire dai sintomi in Risoluzione dei problemi di Claude Code. --restricted richiede la v2.1.248 o successiva.

Gestire le sessioni in background dalla shell​

Una volta avviate le sessioni con --bg, il terminale diventa un piano di controllo. L'intero ciclo di vita ha un comando, e nulla richiede di aprire l'interfaccia interattiva.

Guided walkthrough1 of 6
  1. Apre la vista degli agenti per monitorare e assegnare sessioni in background parallele. Per lo scripting, `--json` stampa le sessioni attive come array JSON, e `--json --all` include quelle completate. `--cwd <path>` restringe alle sessioni avviate sotto quella directory. Aprire la vista richiede un terminale interattivo; la forma JSON no.

La controparte di tutto questo dall'interno di una sessione — come il lavoro viene messo in background e cosa si porta dietro quando succede — è Attività in background, /loop e pianificazione.

Le coppie di flag che le persone sbagliano​

Sei confusioni da prevenire
  • --tools limita quali strumenti integrati esistono. --allowedTools dice quali chiamate saltano il prompt di permesso. --disallowedTools nega le chiamate. Sono tre compiti diversi, e passare quello sbagliato è la causa più comune del "perché mi sta ancora chiedendo".
  • --tools non influisce affatto sugli strumenti MCP. Per rimuovere anche quelli, aggiungi --disallowedTools "mcp__*".
  • Un nome semplice in --disallowedTools rimuove lo strumento dal contesto di Claude; una regola con ambito come Bash(rm *) lascia lo strumento disponibile e nega solo le chiamate corrispondenti.
  • --dangerously-skip-permissions parte in bypassPermissions. --allow-dangerously-skip-permissions aggiunge solo quella modalità al ciclo di Shift+Tab, così puoi partire in modalità plan e passare dopo. Il secondo è quasi sempre ciò che volevi davvero.
  • --add-dir concede l'accesso ai file, ma Claude Code non rileva la maggior parte della configurazione .claude/ da quelle directory. Aggiungere una directory non equivale ad adottarne la configurazione.
  • --desktop non accetta prompt né altri flag tranne --verbose e i flag --debug, perché è l'app Desktop ad avviare la sessione. Richiede la v2.1.285 o successiva.

Un piccolo dettaglio di comodità: se sbagli a scrivere un sottocomando, Claude Code suggerisce quello più vicino ed esce senza avviare una sessione — claude udpate stampa Did you mean claude update? invece di aprire una conversazione che non volevi.

Verifica te stesso​

Check yourself

0/3
  1. Il tuo job notturno esegue `claude -p` dentro un'app Agent SDK la cui callback `canUseTool` interpella una persona, e di notte resta appeso fino al timeout. Quale flag manca più probabilmente?
  2. Modifichi il testo di --append-system-prompt, rilanci `claude --continue` e il comportamento non cambia. Perché?
  3. Una personalizzazione sta rompendo la tua sessione e non sai quale. Quale flag la isola mantenendo strumenti e permessi in funzione normalmente?
Premi Invio o Spazio per girare la carta. Usa le frecce sinistra e destra per spostarti tra le carte.Termine mostrato.
1 / 8
Key takeaways
  • Scegli prima il tipo di sessione — il flag che lo fa vincola ogni altro flag che puoi passare.
  • Un'esecuzione non presidiata richiede cinque flag, non uno: -p, --permission-prompts none, --max-turns, --max-budget-usd e un formato di output strutturato.
  • Tratta --max-budget-usd come un interruttore di sicurezza per una singola esecuzione, non come un tetto sulla fattura. È una stima lato client e i totali ripresi le sfuggono.
  • Le conversazioni registrano il proprio system prompt alla prima richiesta. Se una modifica al prompt sembra ignorata, è per questo — usa --system-prompt-snapshot off mentre iteri.
  • --bare è velocità, --safe-mode è diagnosi, --restricted è contenimento. Sceglierne uno sbagliato fa perdere un pomeriggio.
  • --help è incompleto per progetto. Il riferimento della CLI è la fonte di verità, e le versioni minime contano — controlla claude -v prima di dare la colpa a un flag.

Avanti​