HandyTools Hub

← Alle Anleitungen

Der komplette curl-Befehlsleitfaden: Jedes Flag, das Sie wirklich nutzen

2026-08-17

curl https://example.com ist der meistinstallierte HTTP-Client des Planeten, und er versteckt sich in aller Öffentlichkeit: das einzelne nützlichste Debugging-Werkzeug eines Entwicklers, überstrahlt nur von der Dokumentationslücke darum. Haben Sie ein Dutzend Flags gelernt, wird curl der schnellste Weg, eine API zu sondieren, einen Bug zu reproduzieren und einen Fix zu testen, ohne einen Browser zu öffnen oder ein Wegwerfskript zu schreiben. Diese Anleitung geht die Flags in der Reihenfolge durch, in der Sie sie tatsächlich brauchen.

Die Anatomie eines curl-Befehls

Ein curl-Aufruf ist eine URL plus null oder mehr Flags:

curl [flags] URL

Standardmäßig sendet curl eine GET-Anfrage und schreibt den Antwort-Body auf die Standardausgabe. Die Flags sind es, die diesen nackten Befehl in einen vollwertigen HTTP-Client verwandeln — und da Flags reihenfolgeunabhängig sind, lässt sich derselbe Befehl auf mehrere Weisen schreiben. Verstehen Sie je das Verhalten eines Flags falsch, listet curl --help alles auf und curl --help all zeigt das vollständige Handbuch.

Antworten lesen: -i, -I, -L, -s

Der Body allein sagt selten genug. Drei Flags machen die Antwort lesbar:

curl -i https://api.example.com/users          # Antwort-Header einschließen
curl -I https://api.example.com/users          # nur HEAD: Header, kein Body
curl -L https://example.com/login              # Weiterleitungen folgen (3xx)
  • -i / --include — druckt Statuszeile und Header über dem Body. Das Erste, was man hinzufügt, wenn eine Anfrage „nicht funktioniert“, weil der Statuscode ist, wo die Antwort beginnt.
  • -I / --head — sendet eine HEAD-Anfrage (was das bedeutet, erklärt die HTTP-Methoden-Anleitung) und druckt nur Header. Großartig, um Existenz, Größe oder Content-Type einer Ressource zu prüfen, ohne sie herunterzuladen.
  • -L / --location — stellt die Anfrage an jedem Weiterleitungsziel erneut. Ohne es druckt ein 301/302 nur die Weiterleitungsantwort und stoppt — ein klassischer „warum gibt mein curl HTML für einen API-Aufruf zurück?“-Stolperstein.
  • -s / --silent — unterdrückt den Fortschrittsbalken. Paaren Sie es mit -S (--show-error), damit Fehler weiter ausgegeben werden: -sS ist die leise-aber-informative Kombination für Skripte.

Header und Methoden: -H, -X

Eigene Header und explizite Methoden sind, wo curl sich wie ein echter Client anfühlt:

curl -X POST https://api.example.com/users
curl -H "Content-Type: application/json" \
     -H "Authorization: Bearer $TOKEN" \
     https://api.example.com/users/7
  • -H "Name: value" — setzt einen Anfrage-Header. Wiederholen Sie das Flag für mehrere Header; nutzen Sie -H mit leerem Wert, um einen Standard zu entfernen.
  • -X METHOD — setzt die HTTP-Methode. Häufiger Stolperstein: curls -X POST überschreibt nur die Methode, nicht die impliziten Verhaltensweisen, die -d oder -F auslösen (etwa Content-Type zu setzen). In der Praxis brauchen Sie -X selten — -d impliziert bereits POST, und -F impliziert Multipart-POST —, aber -X PUT, -X PATCH und -X DELETE sind, wozu Sie greifen.

Daten senden: -d, JSON, —data-binary

curl -d "name=ada&role=admin" https://api.example.com/users          # form-kodiert
curl -H "Content-Type: application/json" \
     -d '{"name": "ada", "role": "admin"}' \
     https://api.example.com/users                                    # JSON
curl --data-binary @body.json https://api.example.com/users          # roher Datei-Body
  • -d "key=value" / --data — sendet form-kodierte Daten (application/x-www-form-urlencoded) und impliziert POST. Mehrere -d-Flags werden automatisch mit & verkettet.
  • Mit -H "Content-Type: application/json" und einem JSON-String sendet dasselbe -d einen JSON-Body — das ist das Arbeitstier jedes API-Aufrufs, den Sie je machen werden.
  • --data-binary @file — sendet den Dateiinhalt wortgetreu als Anfrage-Body (kein Entfernen von Zeilenumbrüchen). Stellen Sie @ voran, wann immer der Body aus einer Datei kommt.
  • Um die exakte Anfrage zu protokollieren, die curl baut, fügen Sie -v hinzu (unten) — Body und Header werden sichtbar.

Dateien: -o, -O, -F, -T

curl -o report.pdf https://example.com/report.pdf   # Body in eine benannte Datei speichern
curl -O https://example.com/report.pdf              # mit Remote-Dateinamen speichern
curl -F "avatar=@photo.png" https://example.com/upload     # Multipart-Datei-Upload
curl -F "avatar=@photo.png;type=image/png" https://example.com/upload
curl -T backup.zip https://example.com/uploads/     # eine Datei per PUT hochladen
  • -o file / -O — schreibt den Body in eine Datei statt auf stdout. Nutzen Sie -o /dev/null, um einen großen Body zu verwerfen, während die Header sichtbar bleiben.
  • -F "field=@file" — Multipart/form-data-Upload, das Äquivalent eines HTML-<input type="file">-Formulars. Fügen Sie ;type= hinzu, um den Content-Type des hochgeladenen Teils zu erzwingen.
  • -T file / --upload-file — PUT den Dateiinhalt an die URL. Kombinieren Sie es mit einem Download-Flag für einen schnellen Backup-Roundtrip.

Cookies, Auth und Sessions

curl -b "session=abc123" https://example.com/me            # einen Cookie manuell senden
curl -c cookies.txt https://example.com/login              # Cookies in ein Glas speichern
curl -b cookies.txt https://example.com/me                 # später wiederverwenden
curl -u user:pass https://api.example.com/private          # HTTP-Basic-Auth
curl -H "Authorization: Bearer $TOKEN" https://api.example.com/private
  • -b — sendet Cookies, entweder als Inline-"name=value"-String oder aus einer Datei (Cookie-Jar-/Netscape-Format). -c schreibt die von einer Antwort gesetzten Cookies in ein Glas.
  • Der klassische Session-Tanz: -c, um das Login-Cookie einzufangen, dann -b, um es bei Folgefragen wiederzuspielen — das Terminal-Äquivalent eines angemeldeten Browser-Tabs.
  • -u user:pass — HTTP-Basic-Auth (im Header base64-kodiert). Für Token-APIs ist der Authorization: Bearer-Header üblicher.

Debugging: -v, -w, -f

curl -v https://api.example.com/users            # verbose: vollständige Anfrage/Antwort
curl -w "\n%{http_code} in %{time_total}s\n" https://api.example.com/users
curl -f https://api.example.com/users/404        # Exit ungleich null bei HTTP-Fehlern
  • -v / --verbose — druckt die ganze Anfragezeile, Anfrage-Header, TLS-Handshake-Details und Antwort-Header. Wenn nichts anderes Sinn ergibt, zeigt -v genau, was über die Leitung ging. --trace-ascii - zeigt sogar die rohen Bytes.
  • -w 'format' / --write-out — druckt nach der Antwort zusätzliche Infos. %{http_code}, %{time_total} und %{size_download} sind die, mit denen Sie API-Latenz messen oder einen Status bestätigen, ohne den Body zu parsen. %{redirect_url} zeigt, wohin ein 3xx wollte.
  • -f / --fail — lässt curl bei HTTP 4xx/5xx mit einem Exit-Code ungleich null (22) beenden statt die Fehlerseite zu drucken und „zu gelingen“. Unentbehrlich für Skripte, die wissen müssen, dass eine Anfrage tatsächlich fehlschlug.

Timeouts und Retries

curl --connect-timeout 5 https://api.example.com     # fehlschlagen, wenn TCP-Verbindung stockt
curl -m 30 https://api.example.com/slow              # harte Gesamtzeit-Obergrenze
curl --retry 3 --retry-delay 2 https://api.example.com/jittery
  • --connect-timeout begrenzt nur die Verbindungsphase — nutzen Sie es, um bei unerreichbaren Hosts schnell zu scheitern.
  • -m / --max-time begrenzt die ganze Operation — die Leitplanke für Endpunkte, die hängen.
  • --retry N wiederholt bei vorübergehenden Fehlern (mit Verzögerung zwischen den Versuchen); kombiniert mit einer nicht-idempotenten Methode bedenken Sie, dass Sie womöglich ein POST erneut abspielen — die HTTP-Methoden-Anleitung erklärt, warum das zählt.

Praktische Tipps

  • Minimal beginnen, nach Bedarf ergänzen: zuerst curl -i, dann -L für Weiterleitungen, dann -H und -d, sobald Sie die Form der Anfrage kennen.
  • Niemals Geheimnisse in geteilte Chats einfügen — legen Sie Tokens in eine Umgebungsvariable ($TOKEN) und referenzieren Sie sie, wie in den Beispielen oben.
  • curl in Code verwandeln: Haben Sie bestätigt, dass eine Anfrage funktioniert, wandelt das curl-Konverter-Tool den exakten Befehl in JavaScript fetch, Python, Go und andere Sprachen um — kein Übersetzen von Hand nötig.
  • Schlagen Sie den gerade erhaltenen Statuscode nach mit der HTTP-Statusreferenz — zu wissen, dass 405 „falsche Methode“ bedeutet (und dass der Allow-Header die richtigen listet), löst die meisten API-Rätsel.
  • Speichern Sie Ihre meistgenutzten Beschwörungsformeln als Shell-Aliase oder kleines Skript; ein cget()-/cjson()-Wrapper deckt 90 % der täglichen API-Arbeit ab.

Kurzreferenz

  • curl -i URL — Status + Header sehen. curl -L URL — Weiterleitungen folgen. curl -sS URL — leise, aber Fehler zeigen.
  • -H "Name: value" für Header; wiederholen für mehr. -X PUT / -X PATCH / -X DELETE zum Ändern der Methode.
  • -d "k=v" = Formular-POST; -d '{"json":...}' + -H "Content-Type: application/json" = JSON-POST; --data-binary @file = roher Body.
  • -o file speichern, -O nach Remote-Namen speichern, -F "field=@file" Multipart-Upload, -T file PUT-Upload.
  • -b Cookies senden, -c Cookies speichern, -u user:pass Basic-Auth, Bearer per -H "Authorization: ...".
  • -v Verbose-Leitungsdump, -w '%{http_code}' Status drucken, -f bei HTTP-Fehlern scheitern.
  • --connect-timeout, -m (Max-Zeit), --retry N halten wackelige Anfragen davon ab, ewig zu hängen.

Verwandte Tools