Zum Hauptinhalt springen

Die claude-CLI: Flags, die das Ergebnis verändern

Fortgeschritten

Die meisten lernen über die Claude-Code-Kommandozeile drei Dinge — claude, claude -c und claude -p — und hören dann auf. Das ist ein vernünftiger Punkt zum Aufhören, solange du immer selbst davorsitzt. Sobald du Claude Code aber in ein Skript, einen CI-Job, eine Hintergrund-Queue oder in die Hände eines Teamkollegen legst, sind die Flags keine Annehmlichkeiten mehr, sondern der Unterschied zwischen einem Lauf, der einen Dollar kostet, und einem, der eine Stunde hängt.

Diese Seite ist keine zweite Kopie der Referenztabelle. Sie zeigt die Reihenfolge, in der du die Oberfläche lernen solltest, die Flags, die tatsächlich etwas verändern, und die vier Fallen, die echte Zeit kosten.

What you'll learn
  • Die sechs Arten von Sitzungen, die du starten kannst, und welches Flag welche auswählt
  • Der Fünf-Flag-Vertrag, der einen unbeaufsichtigten Lauf begrenzt, beantwortbar und maschinenlesbar macht
  • Warum das Bearbeiten von --append-system-prompt und ein erneutes --continue scheinbar nichts bewirkt — die Regel vom aufgezeichneten Prompt
  • Wie sich --bare, --safe-mode und --restricted unterscheiden und wann du welches wählst
  • Hintergrundsitzungen von der Shell steuern: agents, attach, logs, respawn, rm, daemon
  • Die Flag-Paare, die oft verwechselt werden: --tools vs. --allowedTools vs. --disallowedTools

Beginne mit der Frage: Was für eine Sitzung ist das?​

Jede weitere Entscheidung folgt aus dieser. Claude Code kann sechs grundverschiedene Dinge starten, und das Flag, das eines davon auswählt, tippst du meist als Erstes.

Du willstFlagDu bekommst
Eine Unterhaltung, die du verfolgst(keins)Interaktive Sitzung in diesem Terminal
Eine Antwort, dann Ende-p / --printNicht-interaktiver Lauf, Ausgabe auf stdout
Arbeit, die dieses Terminal überdauert--bg / --backgroundEine Hintergrundsitzung; sie gibt ihre ID aus und wie du sie verwaltest
Einen isolierten Branch zum Experimentieren-w / --worktreeEin Git-Worktree unter <repo>/.claude/worktrees/<name>
Arbeit auf Anthropics Maschinen--cloudEine Cloud-Sitzung oder eine Folgeaufgabe, die in eine bestehende eingereiht wird
Diese Sitzung vom Handy aus steuern--rc / --remote-controlEine interaktive Sitzung, die zusätzlich von claude.ai oder der Claude-App aus steuerbar ist

Zwei davon lassen sich nicht kombinieren: --bg und -p schließen sich aus, weil das eine sofort zurückkehrt und das andere auf eine Antwort wartet. Wenn du im Hintergrund einen Shell-Befehl statt einer Claude-Sitzung willst, kombiniere --bg mit --exec:

Die Testsuite als Hintergrundjob laufen lassen, nicht als Claude-Sitzung

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

Und --bg prüft vor dem Start das Workspace-Vertrauen für das Verzeichnis — eine Hintergrundsitzung in einem nicht vertrauenswürdigen Repo scheitert also gleich am Anfang statt auf halbem Weg.

Der Fünf-Flag-Vertrag für unbeaufsichtigte Läufe​

Das ist das Wertvollste auf dieser Seite. Ein unbeaufsichtigter claude -p-Lauf kann auf drei Arten schiefgehen, die es in einer interaktiven Sitzung schlicht nicht gibt: Er kann an Berechtigungsabfragen hängen bleiben, die niemand beantwortet, er kann viel länger loopen als erwartet, und er kann Fließtext ausgeben, wo dein Skript Daten brauchte. Fünf Flags schließen alle drei Risiken.

Guided walkthrough1 of 5
  1. `claude -p "query"` gibt die Antwort aus und beendet sich. Alles Folgende gilt nur im Print-Modus, dieses Flag ist also das Tor zu den übrigen.

Ein CI-Schritt, der nicht hängen, nicht endlos loopen und nicht zu viel ausgeben kann

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 ist eine Schätzung, nicht deine Rechnung
  • Claude Code prüft das Limit gegen seine eigene clientseitige Kostenschätzung, die von dem abweichen kann, was dir berechnet wird.
  • Wenn du mit --continue oder --resume zu einer Unterhaltung zurückkehrst, zählen die aus früheren Läufen wiederhergestellten Summen nicht zum Limit — drei fortgesetzte Läufe unter einem 2-$-Limit können also insgesamt mehr als 2 $ kosten.
  • Betrachte es als Sicherung für einen einzelnen Lauf. Für eine echte Obergrenze über ein ganzes Konto oder Projekt siehe Hard Spend Caps.

Zur gesamten Haltung beim Laufenlassen ohne Menschen — was erlauben, was maskieren, was protokollieren — siehe Autonome Läufe absichern und Headless-Modus und Agent SDK. Für Obergrenzen auf Anbieterebene: Hard Spend Caps.

Die System-Prompt-Familie und die Falle darin​

Fünf Flags formen den System-Prompt. Vier legen seinen Text fest; das fünfte entscheidet, ob die Unterhaltung den Text behält, mit dem sie begonnen hat.

FlagWas es tut
--system-promptErsetzt den gesamten Standard-Prompt durch deinen Text
--system-prompt-fileErsetzt ihn durch den Inhalt einer Datei
--append-system-promptHängt deinen Text an den Standard-Prompt an
--append-system-prompt-fileHängt den Inhalt einer Datei an den Standard-Prompt an
--system-prompt-snapshotoff baut den Prompt bei jeder Anfrage neu auf; on (der Standard) verwendet den aufgezeichneten wieder

Die Wahl zwischen anhängen und ersetzen ist eine Wahl über die Identität. Anhängen behält die Standard-Werkzeughinweise, Sicherheitsanweisungen und Coding-Konventionen von Claude Code und legt deine Regeln obendrauf — richtig für Anweisungen pro Lauf, Ausgabeformatierung oder Projektkontext. Ersetzen verwirft all das, einschließlich der Werkzeughinweise, und ist deshalb nur richtig, wenn die Oberfläche tatsächlich kein Coding-Assistent ist: ein nicht programmierender Agent in einer Pipeline, die niemand beobachtet. Wenn du ersetzt, gehört dir alles, was die Aufgabe noch braucht.

Du kannst beides kombinieren. Ein Append-Flag zusammen mit einem Replace-Flag ersetzt den Standard und hängt danach deinen Text an. Ab v2.1.283 kannst du außerdem ein Flag zusammen mit seiner eigenen Dateiform übergeben — --append-system-prompt und --append-system-prompt-file — und Claude Code verwendet beide, wobei der Dateiinhalt zuerst kommt, unabhängig von der getippten Reihenfolge.

Die Falle: Eine fortgesetzte Unterhaltung verwendet den Prompt wieder, mit dem sie geboren wurde
  • Claude Code baut den System-Prompt einmal bei der ersten Anfrage einer Unterhaltung auf und zeichnet ihn in der Sitzung auf.
  • Bis die Unterhaltung kompaktiert wird, verwendet jede spätere Anfrage diesen aufgezeichneten Prompt — auch nach --resume oder --continue.
  • Du bearbeitest also deinen --append-system-prompt-Text, startest claude --continue erneut, und nichts ändert sich. Das Flag ist nicht kaputt; die Unterhaltung nutzt noch die Aufzeichnung.
  • Neuer Text greift, sobald die Unterhaltung kompaktiert wird oder in einer ganz neuen Unterhaltung.
  • Um über mehrere --continue-Läufe an der Formulierung zu feilen, übergib --system-prompt-snapshot off, dann wird der Prompt bei jeder Anfrage neu aufgebaut. Erfordert v2.1.257 oder neuer.

Einen weiteren Kniff solltest du in einem Ersatz-Prompt kennen, der stabile Anweisungen mit Kontext pro Lauf mischt. Setze zwischen beide eine Zeile, die nur __SYSTEM_PROMPT_DYNAMIC_BOUNDARY__ enthält: Claude Code teilt an der ersten solchen Zeile und entfernt sie, sodass der Teil darüber im Cache bleibt, während sich der Teil darunter ändert. Erfordert v2.1.275 oder neuer. Warum das für deine Rechnung wichtig ist, steht in Prompt Caching.

Und für skriptgesteuerte Workloads mit mehreren Nutzern verschiebt --exclude-dynamic-system-prompt-sections Kontext pro Nutzer, etwa den Speicherort des Auto-Memorys, aus dem System-Prompt in die erste Nutzernachricht — so teilt dieselbe Aufgabe auf verschiedenen Maschinen einen einzigen gecachten Präfix. Es gilt nur für den Standard-Prompt und wird ignoriert, wenn du --system-prompt oder --system-prompt-file setzt.

Drei Flags, die Dinge abschalten — und sie sind nicht dasselbe​

Man greift gern wahllos zu diesen und wundert sich dann, warum das Symptom bleibt. Sie lösen drei verschiedene Probleme.

--bare--safe-mode--restricted
Das Problem, das es löstDer Start ist für einen skriptgesteuerten Aufruf zu langsamMeine Konfiguration ist kaputt und ich weiß nicht, welcher TeilEin Eval-Harness darf diese gemeinsam genutzte Maschine nicht anfassen
CLAUDE.md, Skills, Befehle, Subagenten, Plugins, MCP, Auto-MemoryWerden nicht gefundenWerden nicht geladenNur verwaltete Einstellungen und --settings werden geladen
Eingebaute WerkzeugeBash, Datei lesen, Datei bearbeitenFunktionieren normalWerkzeuge zum Ausführen von Befehlen/Code und WebFetch werden entfernt, sofern nicht einzeln in --tools genannt
DateizugriffNormalNormalAuf die Arbeitsverzeichnisse beschränkt
bypassPermissionsErlaubtErlaubtVerweigert
Verwaltete RichtlinieGiltGilt weiterhin, einschließlich Policy-Hooks und StatuszeileGilt
NebeneffektSetzt CLAUDE_CODE_SIMPLESetzt CLAUDE_CODE_SAFE_MODEVerweigert das Erstellen von Cloud-Sitzungen

Lies die Tabelle als Abfolge von Absichten: --bare zielt auf Geschwindigkeit, --safe-mode auf Diagnose, --restricted auf Eindämmung. Ein nützliches Detail: Skills in einem Verzeichnis, das du mit --add-dir übergibst, werden auch unter --bare geladen — so behältst du genau eine Fähigkeit in einem sonst abgespeckten Lauf.

--safe-mode ist das Flag, nach dem du zuerst greifst, wenn etwas nicht stimmt und du nicht weißt, ob es an Claude Code oder an deiner eigenen Konfiguration liegt — auch dann, wenn du herausfinden willst, ob eine Anpassung den automatischen Modell-Fallback auslöst. Kombiniere es mit claude doctor, das schreibgeschützte Installations- und Einstellungsdiagnosen ausgibt, ohne überhaupt eine Sitzung zu starten. (Der Befehl /doctor in der Sitzung ist etwas anderes: Er kann auch Korrekturen anwenden.) Mehr symptomorientiertes Debugging in Claude Code Fehlerbehebung. --restricted erfordert v2.1.248 oder neuer.

Hintergrundsitzungen von der Shell aus steuern​

Sobald du Sitzungen mit --bg startest, wird das Terminal zur Steuerzentrale. Der ganze Lebenszyklus hat einen Befehl, und nichts davon erfordert die interaktive Oberfläche.

Guided walkthrough1 of 6
  1. Öffnet die Agent-Ansicht, um parallele Hintergrundsitzungen zu überwachen und zu starten. Für Skripte gibt `--json` die aktiven Sitzungen als JSON-Array aus, und `--json --all` schließt abgeschlossene ein. `--cwd <path>` beschränkt auf Sitzungen, die unter diesem Verzeichnis gestartet wurden. Die Ansicht selbst braucht ein interaktives Terminal; die JSON-Form nicht.

Das Gegenstück dazu innerhalb einer Sitzung — wie Arbeit in den Hintergrund gelegt wird und was dabei mitgenommen wird — ist Hintergrundaufgaben, /loop und Zeitplanung.

Die Flag-Paare, die man falsch versteht​

Sechs Verwechslungen, denen man besser vorbeugt
  • --tools beschränkt, welche eingebauten Werkzeuge es überhaupt gibt. --allowedTools legt fest, welche Aufrufe die Berechtigungsabfrage überspringen. --disallowedTools lehnt Aufrufe ab. Das sind drei verschiedene Aufgaben, und das falsche Flag zu übergeben ist die häufigste Ursache für „warum fragt es immer noch“.
  • --tools hat auf MCP-Werkzeuge gar keine Wirkung. Um auch diese zu entfernen, füge --disallowedTools "mcp__*" hinzu.
  • Ein bloßer Name in --disallowedTools entfernt das Werkzeug aus Claudes Kontext; eine eingegrenzte Regel wie Bash(rm *) lässt das Werkzeug verfügbar und lehnt nur passende Aufrufe ab.
  • --dangerously-skip-permissions startet in bypassPermissions. --allow-dangerously-skip-permissions fügt diesen Modus nur dem Shift+Tab-Zyklus hinzu, sodass du im Plan Mode starten und später wechseln kannst. Das zweite ist fast immer das, was du eigentlich wolltest.
  • --add-dir gewährt Dateizugriff, aber Claude Code findet in diesen Verzeichnissen die meiste .claude/-Konfiguration nicht. Ein Verzeichnis hinzuzufügen heißt nicht, seine Konfiguration zu übernehmen.
  • --desktop nimmt keinen Prompt und keine anderen Flags außer --verbose und den --debug-Flags, weil die Desktop-App die Sitzung selbst startet. Erfordert v2.1.285 oder neuer.

Ein kleines Komfortdetail: Vertippst du dich bei einem Unterbefehl, schlägt Claude Code den nächstliegenden vor und beendet sich, ohne eine Sitzung zu starten — claude udpate gibt Did you mean claude update? aus, statt eine Unterhaltung zu öffnen, die du nicht wolltest.

Prüfe dich selbst​

Check yourself

0/3
  1. Dein nächtlicher Job führt `claude -p` in einer Agent-SDK-App aus, deren `canUseTool`-Callback einen Menschen fragt, und nachts hängt er bis zum Timeout. Welches Flag fehlt am wahrscheinlichsten?
  2. Du änderst deinen --append-system-prompt-Text, startest `claude --continue` erneut, und das Verhalten bleibt gleich. Warum?
  3. Eine Anpassung stört deine Sitzung und du weißt nicht, welche. Welches Flag isoliert sie, während deine Werkzeuge und Berechtigungen normal weiterarbeiten?
Drücke Enter oder die Leertaste, um die Karte umzudrehen. Nutze die Pfeiltasten links und rechts, um zwischen den Karten zu wechseln.Begriff angezeigt.
1 / 8
Key takeaways
  • Wähle zuerst die Sitzungsart — das Flag, das sie bestimmt, schränkt jedes weitere Flag ein, das du übergeben kannst.
  • Ein unbeaufsichtigter Lauf braucht fünf Flags, nicht eins: -p, --permission-prompts none, --max-turns, --max-budget-usd und ein strukturiertes Ausgabeformat.
  • Betrachte --max-budget-usd als Sicherung für einen einzelnen Lauf, nicht als Obergrenze deiner Rechnung. Es ist eine clientseitige Schätzung, und fortgesetzte Summen entgehen ihr.
  • Unterhaltungen zeichnen ihren System-Prompt bei der ersten Anfrage auf. Wenn eine Prompt-Änderung ignoriert scheint, liegt es daran — nutze --system-prompt-snapshot off, solange du iterierst.
  • --bare ist Geschwindigkeit, --safe-mode ist Diagnose, --restricted ist Eindämmung. Das falsche zu wählen kostet dich einen Nachmittag.
  • --help ist absichtlich unvollständig. Die CLI-Referenz ist die maßgebliche Quelle, und Mindestversionen zählen — prüfe claude -v, bevor du einem Flag die Schuld gibst.

Weiter​