Was ist der curl-Befehl? Beispiele, Flags, HTTP-Requests

Was ist der curl-Befehl?

curl ist ein Kommandozeilen-Tool, das Daten anhand einer URL zu oder von einem Server überträgt. Die meisten Entwickler nutzen es, um HTTP-Requests aus dem Terminal zu senden: eine API aufrufen, Header und Statuscodes prüfen, eine Datei hochladen oder einen schnellen Check skripten. Ein kurzer Befehl zeigt genau, was ein Client gesendet und was der Server geantwortet hat.

Es entstand 1996 als kleines Tool namens HttpGet, wurde 1998 in curl umbenannt und wird von Daniel Stenberg gepflegt. Neben HTTP und HTTPS spricht es FTP, SFTP, SMTP, IMAP und viele weitere Protokolle. Alle Optionen stehen in der curl-Manpage.

Grundlegende curl-Syntax

Der einfachste Befehl sendet einen GET-Request und gibt den Response-Body aus:

curl https://api.example.com/users/42

Mit -i sehen Sie zusätzlich Statuszeile und Response-Header:

curl -i https://api.example.com/users/42

Wenn Sie curl mit -d Daten geben, wird standardmäßig ein POST gesendet, -X POST ist also optional. Die Daten gehen als application/x-www-form-urlencoded raus, für JSON müssen Sie den Header daher selbst setzen:

curl -X POST https://api.example.com/users -H "Content-Type: application/json" -d '{"name": "Alice", "email": "alice@example.com"}'

Seit curl 7.82.0 erledigt die Option --json das in einem Schritt: Sie sendet die Daten als POST mit den JSON-Headern Content-Type und Accept, ohne zu prüfen, ob das JSON gültig ist.

curl --json '{"name": "Alice"}' https://api.example.com/users

Die wichtigsten curl-Flags

Häufige curl-Rezepte

Einen API-Endpunkt testen

Rufen Sie einen API-Endpunkt auf und lesen Sie Statuszeile und Header:

curl -i https://api.example.com/health

Ein Token senden

Übergeben Sie ein Bearer-Token im Authorization-Header. Nutzen Sie doppelte Anführungszeichen, damit die Shell $TOKEN auflöst:

curl -H "Authorization: Bearer $TOKEN" https://api.example.com/orders/42

Eine Datei hochladen

-F sendet einen multipart/form-data-Request:

curl -F "avatar=@photo.jpg" -F "username=alice" https://api.example.com/upload

Nur den Statuscode ausgeben

curl -s -o /dev/null -w "%{http_code}\n" https://example.com

Antwortzeit messen

Die Write-out-Variablen liefern Zeiten für einen Request, einschließlich Time to First Byte:

curl -s -o /dev/null -w "ttfb %{time_starttransfer}s total %{time_total}s\n" https://example.com

Häufige curl-Fehler

• Den JSON-Content-Type vergessen. Mit einfachem -d geht der Body als Formulardaten raus, und viele APIs antworten mit 400 oder 415. Fügen Sie den Header hinzu oder nutzen Sie --json. Unser Beitrag dazu, wie Parameter in einem HTTP-POST-Request gesendet werden (englisch), erklärt die drei Body-Formate.
• -X POST bei jedem -d ergänzen. Das ist überflüssig, und -X behält die Methode auch nach einer Weiterleitung bei, was das tatsächliche Verhalten verschleiern kann.
• Anführungszeichen. In bash schützen einfache Anführungszeichen um JSON die doppelten darin, verhindern aber auch, dass $TOKEN aufgelöst wird. Die Windows-Eingabeaufforderung braucht doppelte Anführungszeichen mit Escaping.
• Geheimnisse in der History. Ein Token hinter -H landet in Ihrer Shell-History. Lesen Sie es aus einer Umgebungsvariable oder einer Datei.
• Dem Exit-Code trauen. Standardmäßig wertet curl ein 404 oder 500 als erfolgreiche Übertragung. Fügen Sie in Skripten --fail hinzu, und nutzen Sie --fail-with-body, wenn Sie auch den Body wollen.
• -k in einem Skript lassen. Es schaltet die Zertifikatsprüfung ab, sodass ein Man-in-the-Middle unbemerkt bleibt.
• -L vergessen. Ohne es bleibt curl beim ersten 301 oder 302 stehen.

curl bei API-Tests, CI und Monitoring

Weil curl auf den meisten Rechnern vorhanden ist, lässt sich damit ein fehlschlagender Aufruf am schnellsten nachstellen, und es ist der übliche Baustein für API-Tests in einer Pipeline. Ein Smoke-Test nach dem Deploy kann eine einzige Zeile sein, mit Timeout und --fail, damit ein schlechter Status den Build fehlschlagen lässt:

curl --fail --max-time 10 -s -o /dev/null https://example.com/health

• Kein Terminal zur Hand? Das kostenlose Tool curl Online funktioniert wie curl im Browser: Sie senden GET-, POST-, PUT-, PATCH-, DELETE-, HEAD- oder OPTIONS-Requests und sehen Status, Header, Body, Zertifikat und Zeitaufschlüsselung. Sichere Methoden laufen aus sechs AWS-Regionen, sodass Sie vergleichen können.
• Aus einem Befehl einen Test machen. Der cURL-zu-k6-Konverter macht aus einem curl-Befehl ein k6-Skript, und der Beitrag zum Import von cURL, HAR, Postman oder OpenAPI in Lasttests (englisch) behandelt die anderen Formate.
• Nach dem Deploy weiter prüfen. Ein curl im Cron ist schnell geschrieben und schnell vergessen. API-Monitoring führt den Request nach Zeitplan von mehreren Standorten aus, prüft Status, Body, Header und Antwortzeit und alarmiert Sie. Der kostenlose Plan prüft alle 5 Minuten beim LoadFocus API-Monitoring.
• Kein Load-Testing-Tool. --parallel (ab curl 7.66.0) führt Übertragungen gleichzeitig aus, standardmäßig bis zu 50 auf einmal. Es meldet jede Übertragung einzeln, nicht Perzentile, Ramp-up oder Ergebnisse nach Region, und es läuft von einem einzigen Rechner. Für echten Traffic nutzen Sie Load-Testing aus Cloud-Regionen.

Häufige Fragen: curl-Befehl

Was ist der Unterschied zwischen -d und --data-raw?

Bei -d wird ein Wert, der mit @ beginnt, als Dateiname gelesen. Bei --data-raw wird derselbe Wert unverändert gesendet. Nutzen Sie --data-raw, wenn Ihre Daten tatsächlich mit einem @ beginnen.

Wie sende ich eine eigene HTTP-Methode?

Mit -X, zum Beispiel curl -X PUT oder curl -X DELETE. Für GET, HEAD und POST brauchen Sie -X normalerweise nicht, weil curl die Methode aus den anderen Optionen ableitet.

Wie sehe ich genau, was curl sendet?

Fügen Sie -v für ausführliche Ausgabe hinzu. Sie zeigt die gesendeten Request-Header, die empfangenen Response-Header und Details zur TLS-Verbindung.

Wie behalte ich Cookies über mehrere curl-Aufrufe?

Speichern Sie sie beim ersten Aufruf mit -c cookies.txt (Cookie-Jar) und senden Sie sie bei den folgenden Aufrufen mit -b cookies.txt.

Kann curl Requests parallel ausführen?

Ja. Seit 7.66.0 führt die Option --parallel (-Z) mehrere Übertragungen gleichzeitig aus, standardmäßig 50 auf einmal, und --parallel-max ändert das. Das ist praktisch für Downloads, ersetzt aber keinen Lasttest.

Kann ich curl als Load-Testing-Tool nutzen?

Für eine Handvoll gleichzeitiger Requests ja. Es fasst Ergebnisse nicht zu Perzentilen zusammen, steigert die Nutzerzahl nicht schrittweise und läuft nicht aus mehreren Regionen. Wandeln Sie den Aufruf dafür in einen k6- oder JMeter-Test um und führen Sie ihn in der Cloud aus.