-p mit Ihrer Eingabeaufforderung und allen CLI-Optionen:
claude -p). Für die Python- und TypeScript-SDK-Pakete mit strukturierten Ausgaben, Tool-Genehmigungsrückrufen und nativen Nachrichtenobjekten siehe die vollständige Agent SDK-Dokumentation.
Grundlegende Verwendung
Fügen Sie das Flag-p (oder --print) zu jedem claude-Befehl hinzu, um ihn nicht interaktiv auszuführen. Alle CLI-Optionen funktionieren mit -p, einschließlich:
--continuezum Fortsetzen von Gesprächen--allowedToolszum automatischen Genehmigen von Tools--output-formatfür strukturierte Ausgabe
Schneller starten mit Bare-Modus
Fügen Sie--bare hinzu, um die Startzeit zu verkürzen, indem Sie die automatische Erkennung von hooks, skills, plugins, MCP-Servern, automatischem Speicher und CLAUDE.md überspringen. Ohne diese Option lädt claude -p den gleichen Kontext, den eine interaktive Sitzung hätte, einschließlich alles, was im Arbeitsverzeichnis oder in ~/.claude konfiguriert ist.
Der Bare-Modus ist nützlich für CI und Skripte, bei denen Sie auf jedem Computer das gleiche Ergebnis benötigen. Ein hook in der ~/.claude eines Teamkollegen oder ein MCP-Server in der .mcp.json des Projekts werden nicht ausgeführt, da der Bare-Modus diese nie liest. Nur Flags, die Sie explizit übergeben, haben Auswirkungen.
Dieses Beispiel führt eine einmalige Zusammenfassungsaufgabe im Bare-Modus aus und genehmigt das Read-Tool vorab, damit der Aufruf ohne Berechtigungsaufforderung abgeschlossen wird:
Der Bare-Modus überspringt OAuth und Keychain-Lesevorgänge. Die Anthropic-Authentifizierung muss von
ANTHROPIC_API_KEY oder einem apiKeyHelper in der an --settings übergebenen JSON stammen. Amazon Bedrock, Google Cloud’s Agent Platform und Microsoft Foundry verwenden ihre üblichen Anmeldedaten des Anbieters.
--bare ist der empfohlene Modus für skriptgesteuerte und SDK-Aufrufe und wird in einer zukünftigen Version zum Standard für -p.Hintergrundaufgaben beim Beenden
Wenn Claude während einerclaude -p-Ausführung eine Hintergrund-Bash-Aufgabe startet, beispielsweise einen Entwicklungsserver oder einen Watch-Build, wird diese Aufgabe etwa fünf Sekunden nach der Rückgabe des endgültigen Ergebnisses durch Claude und dem Schließen von stdin beendet. Die Kulanzfrist ermöglicht es einer Aufgabe, die direkt nach dem Ergebnis endet, ihre Ausgabe noch zu liefern. Vor v2.1.163 würde ein nie endender Hintergrundprozess die claude -p-Invokation auf unbestimmte Zeit offen halten.
Hintergrund-Subagenten und Workflows sind von der fünfsekündigen Kulanzfrist ausgenommen, da ihr Ergebnis Teil der endgültigen Ausgabe ist, daher wartet claude -p auf deren Abschluss. Ab v2.1.182 ist dieses Warten standardmäßig auf zehn Minuten begrenzt, damit ein feststeckender Hintergrund-Agent den Prozess nicht auf unbestimmte Zeit offen halten kann. Passen Sie die Obergrenze mit CLAUDE_CODE_PRINT_BG_WAIT_CEILING_MS an, oder setzen Sie sie auf 0, um unbegrenzt zu warten.
Beispiele
Diese Beispiele zeigen häufige CLI-Muster. Für CI und andere skriptgesteuerte Aufrufe fügen Sie--bare hinzu, damit sie nicht abhängig von lokalen Konfigurationen sind.
Daten durch Claude leiten
Der nicht-interaktive Modus liest stdin, sodass Sie Daten wie bei jedem anderen Befehlszeilentool einleiten und die Antwort umleiten können. Dieses Beispiel leitet ein Build-Protokoll in Claude ein und schreibt die Erklärung in eine Datei:--output-format json enthält die Antwort-Payload total_cost_usd und eine Kostenaufschlüsselung pro Modell, sodass skriptgesteuerte Aufrufer die Ausgaben pro Aufruf verfolgen können, ohne das Nutzungs-Dashboard zu konsultieren.
Ab Claude Code v2.1.128 ist eingeleiter stdin auf 10 MB begrenzt. Wenn Sie die Grenze überschreiten, beendet sich Claude Code mit einer klaren Fehlermeldung und einem Nicht-Null-Status. Um mit größeren Eingaben zu arbeiten, schreiben Sie den Inhalt in eine Datei und verweisen Sie auf den Dateipfad in Ihrer Eingabeaufforderung, anstatt ihn einzuleiten.
Claude zu einem Build-Skript hinzufügen
Sie können einen nicht-interaktiven Aufruf in einem Skript einbinden, um Claude als projektspezifischen Linter oder Reviewer zu verwenden. Diesespackage.json-Skript leitet den Diff gegen main in Claude ein und fordert ihn auf, Tippfehler zu melden. Das Einleiten des Diff bedeutet, dass Claude keine Bash-Berechtigung zum Lesen benötigt, und die maskierten doppelten Anführungszeichen halten das Skript portabel zu Windows:
Strukturierte Ausgabe abrufen
Verwenden Sie--output-format, um zu steuern, wie Antworten zurückgegeben werden:
text(Standard): einfache Textausgabejson: strukturiertes JSON mit Ergebnis, Sitzungs-ID und Metadatenstream-json: zeilengetrennte JSON für Echtzeit-Streaming
result befindet:
--output-format json mit --json-schema und einer JSON Schema-Definition. Die Antwort enthält Metadaten über die Anfrage (Sitzungs-ID, Nutzung usw.) mit der strukturierten Ausgabe im Feld structured_output.
Dieses Beispiel extrahiert Funktionsnamen und gibt sie als Array von Zeichenketten zurück:
claude mit Error: --json-schema is not a valid JSON Schema gefolgt von der Diagnose des Validators. Claude Code akzeptiert Schemas, die das Schlüsselwort format verwenden, wie "format": "email", behandelt aber format als Anmerkung und erzwingt es nicht. Vor v2.1.205 ignorierte Claude Code ein ungültiges Schema stillschweigend und gab unstrukturierten Text zurück, und behandelte jedes Schema, das format enthielt, als ungültig.
Antworten streamen
Verwenden Sie--output-format stream-json mit --verbose und --include-partial-messages, um Token zu empfangen, während sie generiert werden. Jede Zeile ist ein JSON-Objekt, das ein Ereignis darstellt:
result-Nachricht mit dem endgültigen Antworttext, den Kosten und den Sitzungsmetadaten. Vor v2.1.208 konnte das Piping einer großen Antwort die letzte Zeile abschneiden und die result-Nachricht weglassen.
Das folgende Beispiel verwendet jq, um nach Text-Deltas zu filtern und nur den Streaming-Text anzuzeigen. Das Flag -r gibt Rohzeichenketten aus (keine Anführungszeichen) und -j verbindet ohne Zeilenumbrüche, sodass Token kontinuierlich gestreamt werden:
system/api_retry-Ereignis vor dem erneuten Versuch aus. Sie können dies verwenden, um Wiederholungsfortschritt anzuzeigen oder benutzerdefinierte Backoff-Logik zu implementieren.
Das
system/init-Ereignis meldet Sitzungsmetadaten einschließlich des Modells, Tools, MCP-Server und geladener Plugins. Es ist das erste Ereignis im Stream, es sei denn, Startereignisse gehen ihm voraus:
plugin_install-Ereignisse, wennCLAUDE_CODE_SYNC_PLUGIN_INSTALLgesetzt ist.hook_started-,hook_progress- undhook_response-Ereignisse, während ein konfigurierterSessionStart- oderSetup-Hook ausgeführt wird. Diese werden gestreamt, während der Hook sie erzeugt. Claude Code v2.1.169 bis v2.1.203 lieferte sie in einem Batch nach Abschluss des Hooks, immer noch vorsystem/init; v2.1.204 stellte die Live-Lieferung wieder her.
capabilities von Zeichenketten, das die Protokollverhalten benennt, die diese Claude Code-Version implementiert, wie interrupt_receipt_v1. Überprüfen Sie es, um Funktionen zu erkennen, anstatt Versionsnummern zu vergleichen, und ignorieren Sie Werte, die Sie nicht erkennen. Das Feld erfordert Claude Code v2.1.205 oder später und fehlt in früheren Versionen. Siehe SDKSystemMessage für die Funktionsliste.
Verwenden Sie die Plugin-Felder, um CI fehlschlagen zu lassen, wenn ein Plugin nicht geladen wurde:
Wenn
CLAUDE_CODE_SYNC_PLUGIN_INSTALL gesetzt ist, gibt Claude Code system/plugin_install-Ereignisse aus, während Marketplace-Plugins vor dem ersten Zug installiert werden. Verwenden Sie diese, um Installationsfortschritt in Ihrer eigenen Benutzeroberfläche anzuzeigen.
Für programmgesteuertes Streaming mit Rückrufen und Nachrichtenobjekten siehe Antworten in Echtzeit streamen in der Agent SDK-Dokumentation.
Tools automatisch genehmigen
Verwenden Sie--allowedTools, um Claude die Verwendung bestimmter Tools ohne Aufforderung zu ermöglichen. Dieses Beispiel führt eine Test-Suite aus und behebt Fehler, wobei Claude Bash-Befehle ausführen und Dateien lesen/bearbeiten kann, ohne um Genehmigung zu fragen:
dontAsk verweigert alles, das nicht in Ihren permissions.allow-Regeln oder dem schreibgeschützten Befehlssatz enthalten ist, was für gesperrte CI-Läufe nützlich ist. AskUserQuestion, Connector-Tools die Ihre Organisation auf ask gesetzt hat und MCP-Tools, die mit requiresUserInteraction gekennzeichnet sind, werden verweigert, auch wenn eine Allow-Regel passt.
acceptEdits ermöglicht Claude, Dateien ohne Aufforderung zu schreiben, und genehmigt auch automatisch häufige Dateisystembefehle wie mkdir, touch, mv und cp. Andere Shell-Befehle und Netzwerkanfragen benötigen immer noch einen --allowedTools-Eintrag oder eine permissions.allow-Regel, andernfalls wird der Lauf abgebrochen, wenn einer versucht wird:
Einen Commit erstellen
Dieses Beispiel überprüft bereitgestellte Änderungen und erstellt einen Commit mit einer angemessenen Nachricht:--allowedTools verwendet Berechtigungsregelsyntax. Das nachfolgende * ermöglicht Präfix-Matching, sodass Bash(git diff *) jeden Befehl erlaubt, der mit git diff beginnt. Das Leerzeichen vor * ist wichtig: ohne es würde Bash(git diff*) auch git diff-index entsprechen.
Benutzer-aufgerufene skills und benutzerdefinierte Befehle funktionieren im
-p-Modus: Fügen Sie /skill-name in die Eingabeaufforderungszeichenkette ein und Claude Code erweitert sie vor dem Ausführen. Integrierte Befehle, die nur in der Terminalschnittstelle ausgeführt werden, wie /login, sind im -p-Modus nicht verfügbar. /model, /effort, /fast, /color und /rename akzeptieren den Wert als Argument, zum Beispiel /model sonnet, und /mcp ohne Argument gibt eine Textzusammenfassung des Serverstatus aus; diese Formen erfordern Claude Code v2.1.205 oder später und folgen den Verfügbarkeitshinweisen jedes Befehls. Um eine Einstellung von einer -p-Aufruf zu ändern, übergeben Sie key=value an /config, zum Beispiel /config thinking=false.System-Eingabeaufforderung anpassen
Verwenden Sie--append-system-prompt, um Anweisungen hinzuzufügen und dabei das Standardverhalten von Claude Code beizubehalten. Dieses Beispiel leitet einen PR-Diff an Claude weiter und weist ihn an, auf Sicherheitslücken zu überprüfen:
--system-prompt, um die Standardeingabeaufforderung vollständig zu ersetzen.
Gespräche fortsetzen
Verwenden Sie--continue, um das neueste Gespräch fortzusetzen, oder --resume mit einer Sitzungs-ID, um ein bestimmtes Gespräch fortzusetzen. Dieses Beispiel führt eine Überprüfung durch und sendet dann Folgeeingabeaufforderungen:
Nächste Schritte
- Agent SDK Schnellstart: Erstellen Sie Ihren ersten Agent mit Python oder TypeScript
- CLI-Referenz: alle CLI-Flags und Optionen
- GitHub Actions: Verwenden Sie das Agent SDK in GitHub-Workflows
- GitLab CI/CD: Verwenden Sie das Agent SDK in GitLab-Pipelines