Eine kurze Anmerkung dazu, wer hier schreibt: Wir sind Geonode und verkaufen Proxys, daher ist „curl“ das Tool, das wir unseren Kunden bei der Fehlerbehebung am häufigsten empfehlen. Um es für Anfänger ganz klar zu sagen: „curl“ ist kein Proxy-Tool, und man braucht keinen Proxy, um den Umgang damit zu erlernen. Alles, was im Folgenden beschrieben wird, funktioniert kostenlos über öffentliche Endpunkte von deiner eigenen Verbindung aus. Proxys werden erst viel später relevant, wenn du so viele Anfragen stellst, dass ein Ziel eine Ratenbegrenzung für dich einführt, oder wenn du sehen möchtest, wie eine Seite aus einem anderen Land aussieht. Beides ist kein Problem für Anfänger. Lerne zuerst das Tool kennen.
Was ist curl und wozu dient es?
curl ist ein Befehlszeilenprogramm zur Datenübertragung über URLs. Im eigenen Handbuch wird beschrieben, dass es „DICT, FILE, FTP, FTPS, GOPHER, GOPHERS, HTTP, HTTPS, IMAP, IMAPS, LDAP, LDAPS, MQTT, MQTTS, POP3, POP3S, RTSP, SCP, SFTP, SMB, SMBS, SMTP, SMTPS, TELNET, TFTP, WS und WSS“ – in der Praxis wird es jedoch fast ausschließlich für HTTP und HTTPS verwendet.
Wofür es sich eignet:
- Aufruf einer API über ein Terminal oder ein Skript
- Überprüfen, ob eine URL funktioniert und was sie zurückgibt
- Genau sehen, was ein Server zurücksendet, einschließlich aller Header
- Herunterladen von Dateien
- Debugging: Reproduzieren einer Anfrage außerhalb Ihrer Anwendung, um herauszufinden, ob das Problem bei Ihrem Code oder beim Server liegt
Was es nicht ist: ein Browser. Es führt kein JavaScript aus, es rendert nichts und es hält keine Sitzung aufrecht, es sei denn, man weist es dazu an. Eine Seite, die in einem Browser vollständig angezeigt wird, gibt bei curl möglicherweise ein fast leeres Skelett zurück, was jedoch zu erwarten ist und keinen Fehler darstellt.
Ihre ersten Anfragen
curl https://example.com
Dadurch wird ein GET-Aufruf ausgeführt und der Antworttext auf Ihrem Terminal angezeigt. Wenn die Ausgabe aus einer Unmenge an HTML-Code besteht, funktioniert curl.
Vier sofort nützliche Varianten:
Zeigen Sie sowohl die Header als auch den Antworttext an mit -i
, dokumentiert unter -i, --show-headers
: „Antwort-Header in der Ausgabe anzeigen.“
curl -i https://example.com
In eine Datei speichern mit -o
(ein Name Ihrer Wahl) oder -O
(der Name des Remote-Servers):
curl -o page.html https://example.com
curl -O https://example.com/file.zip
Weiterleitungen verfolgen mit -L
: „HTTP-Weiterleitungen verfolgen und Anfragen mit der ursprünglich angegebenen Methode wiederholen.“ Ohne diese Option stoppt curl bei der ersten Weiterleitung und zeigt Ihnen die Weiterleitungsseite anstelle des Ziels an.
curl -L https://example.com
Keine Meldungen ausgeben, aber dennoch Fehler melden mit -sS
. -s
unterdrückt die Fortschrittsanzeige, -S
behält Fehlermeldungen bei. Zusammen sind sie genau das, was Sie in jedem Skript benötigen.
curl -sS https://example.com
Wenn Sie sich eine Zeile aus diesem Artikel merken, dann sollte es diese sein:
curl -sSL https://example.com
Die Antwort lesen
Anfänger starren oft auf den Hauptteil der Antwort, obwohl die Antwort bereits in den Headern steht.
curl -i https://example.com
HTTP/2 200
content-type: text/html; charset=UTF-8
content-length: 1256
Die erste Zeile gibt den Status an. „200
“ bedeutet Erfolg. „301
“ und „302
“ sind Weiterleitungen – füge „-L
“ hinzu. „401
“ und „403
“ bedeuten, dass du keinen Zugriff hast. „404
“ bedeutet, dass die Seite nicht existiert. „429
“ bedeutet, dass du zu schnell bist. „500
“ und höhere Werte bedeuten, dass der Server ein Problem hat.
content-type
Das zeigt dir, was du tatsächlich erhalten hast, und klärt viele Unklarheiten. Wenn du eine API aufgerufen hast, in der Erwartung, JSON zu erhalten, und „text/html
“ siehst, hast du eine Fehlerseite oder eine Weiterleitung zur Anmeldung erhalten, und der Parsing-Fehler, auf den du gleich stoßen wirst, ist eher ein Symptom als die Ursache.
So rufst du die Header ohne den Body ab:
curl -sS -o /dev/null -D - https://example.com
Das führt einen normalen GET-Aufruf durch, verwirft den Body und gibt die Header aus. Es ist zuverlässiger als -I
, das eine HEAD
-Anfrage sendet und sich anders verhalten kann – ein Unterschied, der in unserem Leitfaden zu curl-HEAD-Anfragen behandelt wird.
Anstelle der rohen Header gibt -w
eine Zusammenfassung ausgewählter Werte aus:
curl -sS -o /dev/null -w 'status=%{response_code} time=%{time_total}s\n' https://example.com
Mehr zum korrekten Auslesen von Headern findest du unter Anzeigen von Antwort-Headern mit curl.
Daten senden
Die andere Hälfte der Aufgabe.
Ein POST-Request mit Formulardaten:
curl -d "name=Ada&role=engineer" https://api.example.com/users
Die Verwendung von -d impliziert einen POST-Request und setzt den Inhaltstyp auf Content-Type: application/x-www-form-urlencoded.
Ein POST-Request mit JSON – und das ist der mit Abstand häufigste Anfängerfehler, denn -d allein setzt keinen JSON-Inhaltstyp:
curl -X POST https://api.example.com/users \
-H "Content-Type: application/json" \
-d '{"name":"Ada","role":"engineer"}'
Wenn man diesen Header vergisst, geben viele APIs den Fehler „415 Unsupported Media Type“ zurück, was verwirrend ist, bis man weiß, dass sich dieser Fehler auf die „Content-Type“ bezieht und nicht auf die eigentlichen Daten. Wir haben über diesen speziellen Fehler in Was ist ein 415-Statuscode? geschrieben.
Daten aus einer Datei, wobei „@“ bedeutet: „Diese Datei lesen“:
curl -X POST https://api.example.com/users \
-H "Content-Type: application/json" \
-d @payload.json
Ein GET-Aufruf mit Abfrageparametern, die aus Schlüssel-Wert-Paaren aufgebaut sind, unter Verwendung von „-G“:
curl -G https://api.example.com/search -d "q=proxy" -d "limit=10"
Andere Methoden mit „-X“. Verwenden Sie dies nur für Methoden, für die es keine spezielle Option gibt – PUT, DELETE, PATCH. Beachten Sie den Hinweis im Handbuch, dass „-X“ „nur das tatsächlich in der HTTP-Anfrage verwendete Wort ändert, nicht aber das Verhalten von curl“, weshalb „-X HEAD“ nicht funktioniert und „-I“ existiert.
Header, Authentifizierung und Cookies
Benutzerdefinierte Header mit -H
, wiederholbar:
curl -H "Authorization: Bearer eyJhbG..." \
-H "Accept: application/json" \
https://api.example.com/me
Basic-Authentifizierung mit -u
:
curl -u username:password https://api.example.com/private
Wenn Sie das Passwort weglassen, fordert curl Sie zur Eingabe auf, wodurch es nicht in Ihrem Shell-Verlauf gespeichert wird:
curl -u username https://api.example.com/private
Ein User-Agent mit -A
, da sich curl standardmäßig als curl identifiziert und manche Server darauf unterschiedlich reagieren:
curl -A "Mozilla/5.0 (compatible; MyBot/1.0; +https://example.com/bot)" https://example.com
Wenn Sie einen automatisierten Client schreiben, ist ein ehrlicher User-Agent mit einer Kontakt-URL sowohl eine Frage der Höflichkeit als auch ein praktischer Vorteil – anonyme Automatisierung wird weitaus häufiger blockiert als identifizierte Automatisierung.
Cookies. curl behält diese zwischen den Aufrufen nicht bei, es sei denn, Sie fordern dies an:
curl -c cookies.txt -d "user=ada&pass=secret" https://example.com/login
curl -b cookies.txt https://example.com/dashboard
-c
schreibt ein Cookie-Jar, -b
liest eines aus. So handhaben Sie alles, was eine Sitzung erfordert.
Sehen, was tatsächlich über die Leitung ging
Die Gewohnheit, die diejenigen, die schnell debuggen, von denen unterscheidet, die nur raten.
curl -v https://example.com
Das Handbuch erklärt die Präfixe: „>
: von curl gesendeter Header, <
: von curl empfangener Header, }
: von curl gesendete Daten, {
: von curl empfangene Daten, *
: von curl bereitgestellte Zusatzinformationen.“
Um nur das zu sehen, was Sie gesendet haben:
curl -v https://example.com 2>&1 | grep '^>'
Dies beseitigt eine ganze Reihe von Unklarheiten, da der Header, den Sie im Code setzen, nicht immer der Header ist, der tatsächlich übertragen wurde. Bibliotheken fügen Standardwerte hinzu, überschreiben Werte und ordnen Dinge neu an. Wenn ein Server Ihren Header „ignoriert“, prüfen Sie zunächst, ob Sie ihn tatsächlich gesendet haben.
Die ausführliche Ausgabe erfolgt über stderr, weshalb vor der Weiterleitung „2>&1
“ erforderlich ist – dies ist beabsichtigt, damit der Textkörper auf stdout sauber bleibt.
Eine Warnung aus dem Handbuch, die es wert ist, wiederholt zu werden: Die ausführliche und die Trace-Ausgabe „können sensible Daten enthalten, darunter Benutzernamen, Anmeldedaten oder vertrauliche Inhalte“. Schwärzen Sie diese, bevor Sie sie in ein Ticket einfügen.
Die wichtigsten Flags
Alles oben Genannte lässt sich auf eine kleine Auswahl zusammenfassen.
| Flag | Funktion |
|---|---|
-i | Antwort-Header zusammen mit dem Body anzeigen |
-o file / -O | In eine benannte Datei / unter dem Remote-Namen speichern |
-L | Weiterleitungen verfolgen |
-sS | Im Hintergrund ausführen, aber Fehler dennoch melden |
-H | Einen Header hinzufügen |
-d | Daten senden (impliziert POST) |
-u | Basic-Authentifizierung |
-v | Den vollständigen Datenaustausch anzeigen |
--fail | HTTP-Fehler als Fehlschläge behandeln |
-m / --connect-timeout | Zeitlimits |
Die letzten beiden Optionen werden von Anfängern oft übersprungen, was sie später bereuen.
--fail ist wichtig, da curl eine 404 standardmäßig als erfolgreiche Übertragung behandelt – es lädt die Fehlerseite herunter und beendet den Vorgang mit dem Exit-Code 0. In einem Skript bedeutet das, dass Sie eine HTML-Fehlerseite unter dem Namen installer.dmg speichern und dann weitermachen. --fail sorgt dafür, dass HTTP-Fehler einen Exit-Code ungleich Null und keine Ausgabe erzeugen.
Timeouts sind wichtig, da curl standardmäßig kein allgemeines Zeitlimit hat. Eine hängende Anfrage lässt Ihr Skript auf unbestimmte Zeit hängen. Mit „--connect-timeout 5 -m 30“ wird dies begrenzt. Mehr dazu finden Sie unter Festlegen eines Timeouts mit curl.
Die Zeile, die in jedes Skript aufgenommen werden sollte: „
curl --fail --silent --show-error --location --connect-timeout 5 --max-time 30 "$URL"
```“
Ein Beispiel von Anfang bis Ende
Die einzelnen Schritte an einer realistischen Aufgabe zusammenführen: Aufruf einer öffentlichen API, Überprüfung, ob der Aufruf erfolgreich war, und Behandlung des Fehlerfalls.
Schritt 1 – Prüfen, was der Endpunkt zurückgibt. Beginnen Sie mit den Headern, nicht mit dem Body:
curl -sS -o /dev/null -D - https://api.github.com/repos/curl/curl
Sie erhalten eine Statuszeile und Header. Wenn der Status „200
“ lautet und unter „content-type
“ „JSON“ steht, kommunizieren Sie mit der richtigen Schnittstelle.
Schritt 2 – Sehen Sie sich den formatierten Hauptteil an. Rohes JSON in einer einzigen Zeile ist unlesbar, leiten Sie es daher über jq
weiter:
curl -sS https://api.github.com/repos/curl/curl | jq '{name, stargazers_count, language}'
Falls jq
nicht installiert ist, übernimmt python3 -m json.tool
die Formatierung ohne zusätzliche Abhängigkeiten.
Schritt drei – Überprüfen Sie, was Sie gesendet haben. Wenn etwas nicht wie erwartet funktioniert, schauen Sie sich die Anfrage an, anstatt zu raten:
curl -v https://api.github.com/repos/curl/curl 2>&1 | grep '^>'
Schritt vier – Machen Sie es sicher für ein Skript. Fügen Sie Fehlerbehandlung und Zeitlimits hinzu und erfassen Sie den Status getrennt vom Hauptteil:
#!/usr/bin/env bash
set -euo pipefail
URL="https://api.github.com/repos/curl/curl"
BODY=$(mktemp)
STATUS=$(curl --silent --show-error --location \
--connect-timeout 5 --max-time 30 \
--write-out '%{response_code}' --output "$BODY" \
"$URL")
case "$STATUS" in
200) jq -r '.stargazers_count' < "$BODY" ;;
404) echo "not found" >&2; exit 1 ;;
429) echo "rate limited, retry after: $(date)" >&2; exit 1 ;;
*) echo "unexpected status $STATUS" >&2; head -c 200 "$BODY" >&2; exit 1 ;;
esac
rm -f "$BODY"
Drei Dinge daraus lohnt es sich, in alles zu integrieren, was du schreibst. --write-out '%{response_code}'
mit --output
trennt den Status vom Hauptteil, sodass du entsprechend verzweigen kannst. Das Ausgeben der ersten 200 Zeichen des Hauptteils bei einem unerwarteten Status verwandelt ein Rätsel in einen lesbaren Fehler. Und --connect-timeout
mit --max-time
sorgt dafür, dass das Skript auch dann beendet wird, wenn die Netzwerkverbindung unterbrochen ist.
Schritt 5 – Halten Sie die Ratenbegrenzung ein. Öffentliche APIs geben ihre Begrenzungen in den Headern an. Das Auslesen dieser Angaben kostet nichts und verhindert die häufigste Ursache für eine Sperrung:
curl -sS -o /dev/null -D - https://api.github.com/repos/curl/curl | grep -i ratelimit
Häufige Anfängerfehler
Das Vergessen von „-L“. Man erhält eine kurze Antwort mit einem Weiterleitungshinweis und kommt zu dem Schluss, dass die URL defekt ist. Das ist sie jedoch nicht.
Das Vergessen von „--fail“ in Skripten. Ein „404“ führt zu einer gespeicherten Fehlerseite und einem Exit-Code von Null. Das läuft unbemerkt ab und wird später teuer.
Verwendung von -d mit JSON, ohne Content-Type zu setzen. Dies führt zu 415 oder einem verwirrenden Parsing-Fehler auf dem Server.
Shell-Quoting. Einfache Anführungszeichen behalten alles wörtlich bei; doppelte Anführungszeichen lassen die Shell $ und Backticks erweitern. Um einen JSON-Body mit doppelten Anführungszeichen zu erstellen, setzen Sie ihn in einfache Anführungszeichen. Wenn Ihre Daten auch einfache Anführungszeichen enthalten, speichern Sie sie in einer Datei und verwenden Sie „-d @file.json“.
Annahme, dass curl das sieht, was ein Browser sieht. curl führt kein JavaScript aus. Eine fast leere Antwort von einer Seite, die im Browser vollständig angezeigt wird, bedeutet, dass der Inhalt clientseitig gerendert wird und curl sich korrekt verhält.
Den Statuscode ignorieren. Ein Body mit der Meldung „Fehler“ und dem Status „200“ ist ein anderes Problem als ein Body mit der Meldung „Fehler“ und dem Status „500“. Lies beide.
Anmeldedaten in die Befehlszeile eingeben. Diese landen im Shell-Verlauf und sind in der Prozessliste für andere Benutzer auf dem Rechner sichtbar. Verwenden Sie „-u user“ und lassen Sie „curl“ nach den Anmeldedaten fragen oder diese aus einer Umgebungsvariablen lesen.
Die Zertifikatsüberprüfung deaktivieren, damit etwas funktioniert. „-k“ unterdrückt eine Warnung, die Ihnen etwas mitteilen wollte. Finden Sie zuerst heraus, was genau.
Wie geht es weiter?
Sobald Sie mit den Grundlagen vertraut sind, sind dies die logischen nächsten Schritte:
Korrekte Downloads – Unterbrochene Übertragungen fortsetzen, parallele Downloads, Ratenbegrenzung. Dies wird unter „Eine Datei mit curl herunterladen“ behandelt.
Timeouts und Wiederholungsversuche – damit werden Skripte robuster. Siehe Festlegen eines Timeouts mit curl.
Header als Daten lesen: Mit %{header_json} erhalten Sie eine JSON-Ausgabe anstelle von Text, den Sie parsen müssen.
curl versus wget: Da sich ihre Funktionen überschneiden und sie jeweils für unterschiedliche Aufgaben geeignet sind, erklärt curl vs. wget, wann welches Programm zum Einsatz kommen sollte.
Proxys, falls Sie sie irgendwann einmal benötigen: -x http://host:port leitet eine Anfrage über einen Proxy weiter. Wirklich nützlich für geografische Überprüfungen und zur Verteilung des Datenvolumens; für Lernzwecke oder bei geringem Nutzungsaufkommen hingegen völlig unnötig.
Das Handbuch. man curl ist umfangreich und gilt als maßgebliche Quelle. Den Eintrag zu einem Flag zu lesen, das man bereits verwendet, ist ein zuverlässiger Weg, um die Option zu entdecken, die man eigentlich gesucht hat.
Häufig gestellte Fragen
Wozu wird curl verwendet?
Zur Übertragung von Daten über URLs von der Befehlszeile oder aus einem Skript heraus – zum Aufrufen von APIs, zum Überprüfen der Serverantworten, zum Herunterladen von Dateien und zum Nachstellen einer Anfrage außerhalb einer Anwendung, um ein Problem einzugrenzen. Es unterstützt viele Protokolle, wird jedoch überwiegend für HTTP und HTTPS verwendet.
Wie stelle ich mit curl eine GET-Anfrage?
curl https://example.com. GET ist die Standardeinstellung, daher ist kein Flag erforderlich. Füge „-L“ hinzu, um Weiterleitungen zu verfolgen, und „-i“, um die Antwort-Header neben dem Hauptteil anzuzeigen.
Wie sende ich JSON mit curl?
curl -X POST -H "Content-Type: application/json" -d '{"key":"value"}' URL. Der Header ist unerlässlich – „-d“ allein sendet den Content-Type „form-encoded“, und APIs, die JSON erwarten, lehnen dies in der Regel mit einem 415-Fehler ab.
Warum gibt curl nichts zurück?
Es gibt mehrere Möglichkeiten: Der Antworttext ist tatsächlich leer, du bist einer Weiterleitung gefolgt, der du nicht gefolgt bist (füge „-L“ hinzu), der Inhalt wird von JavaScript gerendert, das curl nicht ausführt, oder die Anfrage ist fehlgeschlagen und du hast den Fehler nicht gesehen, weil du „-s“ ohne „-S“ verwendet hast. Führe den Befehl mit „-i“ aus, um den Statuscode anzuzeigen.
Was ist der Unterschied zwischen -o und -O in curl?
„-o filename“ speichert die Datei unter einem von Ihnen gewählten Namen. „-O“ speichert die Datei unter dem Dateinamen aus der URL und lässt dabei den Pfad weg. Verwenden Sie „-o“, wenn die URL keinen aussagekräftigen Dateinamen enthält oder wenn Sie einen bestimmten Namen benötigen.
Wie kann ich die von curl gesendete Anfrage einsehen?
Führen Sie „curl -v URL“ aus und suchen Sie nach Zeilen, die mit „>“ beginnen. Die ausführliche Ausgabe wird an stderr gesendet, fügen Sie daher vor der Weiterleitung „2>&1“ hinzu. Dies ist der schnellste Weg, um zu überprüfen, ob ein von Ihnen konfigurierter Header tatsächlich übertragen wurde.
Folgt curl standardmäßig Weiterleitungen?
Nein. Füge -L hinzu. Dies ist der häufigste Grund, warum der curl-Befehl eines Anfängers eine unerwartet kurze Antwort zurückgibt – du siehst die Weiterleitung, nicht das Ziel.
Brauche ich einen Proxy, um curl zu nutzen?
Nein. curl funktioniert problemlos mit öffentlichen Endpunkten über deine eigene Verbindung. Proxys werden erst dann relevant, wenn du so viele Anfragen stellst, dass eine Ratenbegrenzung greift, oder wenn du sehen möchtest, was eine Website in einem anderen Land bereitstellt. Beides ist kein Grund, während des Lernens etwas zu kaufen.
Fazit
curl verfügt über eine einschüchternde Anzahl an Optionen und einen sehr kleinen, nützlichen Kern. -i, um Header anzuzeigen, -L, um Weiterleitungen zu verfolgen, -o, um Daten zu speichern, -H, um Header hinzuzufügen, -d, um Daten zu senden, -u für die Authentifizierung, -v, um zu sehen, was passiert ist, und --fail sowie ein Timeout für alles, was unbeaufsichtigt läuft. Das ist für die meisten Nutzer bereits der gesamte Arbeitsumfang.
Die beiden Gewohnheiten, die wichtiger sind als jedes Flag: Lies den Statuscode und den „Content-Type“, bevor du den Body liest, denn diese benennen das Problem meist direkt; und verwende „-v“, um zu überprüfen, was du tatsächlich gesendet hast, anstatt was du senden wolltest, denn der Unterschied zwischen diesen beiden ist die Quelle einer überraschend großen Anzahl von Fehlern.
Alles darüber hinaus ist das Handbuch, das umfangreich und maßgeblich ist und in das es sich lohnt, einen Blick zu werfen, wann immer Sie eine Umgehungslösung schreiben. Die gewünschte Option ist in der Regel vorhanden.