Einstieg
Grundlegende Anfragen
curl macht HTTP-Anfragen von der Kommandozeile. Standardmäßig GET. -v zeigt ausführliche Ausgabe, -o speichert in eine benannte Datei, -O behält den entfernten Dateinamen, -L folgt Weiterleitungen, -I holt nur Header (HEAD-Anfrage).
# GET request (default)
curl https://example.com
# with verbose output
curl -v https://example.com
# save output to file
curl -o output.html https://example.com
curl -O https://example.com/file.zip # keep remote filename
# follow redirects
curl -L https://example.com/redirect
# show only headers
curl -I https://example.com
curl --head https://example.comAusgabe & Speichern
-o schreibt den Body in eine benannte Datei; -O nutzt den entfernten Dateinamen. --output-dir setzt das Zielverzeichnis. -s (silent) unterdrückt Fortschrittsanzeige und Fehler — mit -S paaren, um Fehler dennoch zu sehen. Mit -D Header in eine Datei ausgeben und den Body mit -o /dev/null verwerfen.
# print body to stdout (default)
curl https://example.com
# save body to file
curl -o page.html https://example.com
# save with remote filename
curl -O https://example.com/file.zip
# save to specific dir with remote name
curl -O --output-dir /tmp https://example.com/file.zip
# append to file
curl https://example.com >> log.txt
# discard body, keep headers
curl -o /dev/null -D headers.txt https://example.com
# silent (no progress, no errors)
curl -s https://example.comVerbose & Header
-v (verbose) druckt die gesamte Konversation: '>' ist die Anfrage, '<' die Antwort, '*' sind curl-Infos — alles auf stderr, sodass stdout für den Body sauber bleibt. -I sendet eine HEAD-Anfrage und druckt Header. -D gibt Header in eine Datei oder '-' für stdout aus; mit -o /dev/null kombinieren, um Header ohne Speichern des Bodys zu inspizieren.
# verbose: shows request + response, sent to stderr
curl -v https://example.com
# > lines are the request, < lines are the response
# * lines are curl's internal info
# headers only (HEAD request)
curl -I https://example.com
# dump response headers to file
curl -D headers.txt -o body.html https://example.com
# dump headers to stdout, body to file
curl -D - -o body.html https://example.com
# show only response headers (no HEAD)
curl -s -o /dev/null -D - https://example.comWeiterleitungen folgen
-L folgt HTTP-3xx-Weiterleitungen; standardmäßig bis zu 50 Hops (--max-redirs zum Begrenzen). RFC 301/302 wandelt POST üblicherweise in GET — mit --post301/--post302 die Methode erhalten. Standardmäßig werden Credentials nicht an umgeleitete Hosts gesendet; --location-trusted sendet sie überall (Sicherheitsrisiko).
# follow 3xx redirects
curl -L https://example.com/old
# limit number of redirects
curl -L --max-redirs 5 https://example.com
# treat redirects as POST (default resends as GET)
curl -L --post301 --post302 https://example.com
# show each hop in a redirect chain
curl -L -v https://short.url/abc 2>&1 | grep -i location
# follow only http/https redirects
curl -L --proto-redir http,https https://example.com
# send credentials only on first request
curl -L --location-trusted -u user:pass https://example.comURL-Syntax & Globbing
curl expandiert URL-'globbing'-Muster: [1-10]-Bereiche, {a,b,c}-Listen, mit optionalem :step. Jede Expansion ist eine eigene Anfrage. -g (--globoff) behandelt Klammern wörtlich — wichtig für URLs mit JSON-Arrays oder IPv6-Adressen wie http://[::1]:8080/.
# range glob: requests file1, file2, file3
curl -O https://example.com/file[1-3].zip
# range with step
curl -O https://example.com/file[1-10:2].zip # 1,3,5,7,9
# list glob: a, b, c
curl -O https://example.com/{a,b,c}.zip
# combined globs
curl -O https://example.com/{v1,v2}/file[1-2].txt
# output each URL as it is fetched
curl -O https://example.com/file[1-3].zip --write-out "%{url} -> %{filename}\n"
# disable globbing (literal brackets/braces)
curl -g "https://example.com/file[1].zip"Hilfe & Version
--version zeigt die curl-Version, unterstützte Protokolle (HTTP, HTTPS, FTP usw.) und einkompilierte Features (HTTP2, SSL, brotli). --help all listet jede Option — praktisch, wenn man sich an einen Teil eines Flag-Namens erinnert. Features hängen vom Build ab (z. B. braucht HTTP/3 einen Spezialbuild).
# version and supported features
curl --version
# short help (one-line per option)
curl --help
# long help (all options with details)
curl --help all
# search help for a keyword
curl --help all | grep -i cookie
# list supported protocols
curl --version | head -1
# check if a feature is built in
curl --version | grep -i http2HTTP-Methoden
GET-Anfragen
GET ist die Standardmethode. URLs mit & oder ? immer quoten, damit die Shell sie nicht in den Hintergrund schickt oder expandiert. -X setzt die Methode explizit, ist für GET meist unnötig. Bei APIs Accept setzen, um das Antwortformat auszuhandeln.
# simple GET (default method)
curl https://api.example.com/data
# GET with query string
curl "https://api.example.com/search?q=curl&page=2"
# explicit method
curl -X GET https://example.com
# GET with headers
curl -H "Accept: application/json" https://api.example.com/data
# GET with auth
curl -u user:pass https://api.example.com/secretPOST-Anfragen
Das Senden von -d schaltet die Methode automatisch auf POST, daher ist -X POST redundant (aber harmlos und verdeutlichend). Um eine Datei zu POSTen, -d @filename verwenden (das @ liest die Datei). Der Default-Content-Type für -d ist application/x-www-form-urlencoded; mit -H für JSON überschreiben.
# POST with form data (application/x-www-form-urlencoded)
curl -X POST -d "name=Alice&age=30" https://api.example.com/users
# -d implies POST, so -X is optional
curl -d "name=Alice" https://api.example.com/users
# POST with no body
curl -X POST https://api.example.com/trigger
# POST JSON
curl -X POST -H "Content-Type: application/json" \
-d '{"name":"Alice"}' https://api.example.com/users
# POST with data from a file
curl -X POST -d @form.txt https://api.example.com/usersPUT & PATCH
PUT ersetzt eine ganze Ressource; PATCH wendet ein Teilupdate an. Beide brauchen -X, weil curl dafür keinen -d-Kurzbefehl hat. -T (upload-file) streamt eine Datei als Request-Body und ist ideal für PUT-Uploads. Statt -d --data-binary verwenden, um beim Senden roher Dateien Zeilenumbrüche zu erhalten.
# PUT (replace entire resource)
curl -X PUT -H "Content-Type: application/json" \
-d '{"name":"Alice","age":31}' \
https://api.example.com/users/1
# PATCH (partial update)
curl -X PATCH -H "Content-Type: application/json" \
-d '{"age":32}' \
https://api.example.com/users/1
# PUT a file as body
curl -X PUT --data-binary @config.json \
-H "Content-Type: application/json" \
https://api.example.com/config
# PUT with upload file
curl -X PUT -T localfile.txt https://example.com/remote.txtDELETE
DELETE entfernt eine Ressource. Die meisten APIs verlangen Authentifizierung, also -u oder einen Authorization-Header mitgeben. Manche APIs akzeptieren einen Body (Grund, Cascade-Flags) — -d und einen Content-Type-Header ergänzen. Mit -w '%{http_code}' das Ergebnis prüfen: 204 (No Content) und 200 sind typische Erfolge.
# delete a resource
curl -X DELETE https://api.example.com/users/1
# delete with auth
curl -X DELETE -H "Authorization: Bearer TOKEN" \
https://api.example.com/users/1
# delete with confirmation check
curl -X DELETE -w "%{http_code}" -o /dev/null -s \
https://api.example.com/users/1
# delete with request body (some APIs require it)
curl -X DELETE -H "Content-Type: application/json" \
-d '{"reason":"spam"}' \
https://api.example.com/users/1HEAD & OPTIONS
-I sendet eine HEAD-Anfrage (nur Header, kein Body) — nützlich, um Größe (Content-Length), Typ (Content-Type) und last-modified ohne Download zu prüfen. OPTIONS zeigt erlaubte Methoden (der Allow-Header) und wird von Browsern für CORS-Preflight genutzt. Origin- und Access-Control-Request-Method-Header ergänzen, um einen echten Preflight zu simulieren.
# HEAD: headers only, no body
curl -I https://example.com
curl --head https://example.com
# OPTIONS: discover allowed methods
curl -X OPTIONS https://api.example.com/users
# OPTIONS with CORS preflight headers
curl -X OPTIONS \
-H "Origin: https://mysite.com" \
-H "Access-Control-Request-Method: POST" \
https://api.example.com/users
# check allowed methods from Allow header
curl -X OPTIONS -s -D - -o /dev/null https://api.example.com | grep -i allowHeader
Header setzen (-H)
-H (--header) ergänzt einen Request-Header. -H für mehrere Header wiederholen. Ein nachgestelltes Semikolon (X-Empty;) sendet einen leeren Wert. @headers.txt liest Header aus einer Datei (ein 'Name: value' pro Zeile) — praktisch, um Authorization-Tokens aus der Shell-History zu halten.
# single header
curl -H "Accept: application/json" https://api.example.com/data
# multiple headers
curl -H "Accept: application/json" \
-H "Authorization: Bearer TOKEN" \
-H "X-Custom: value" \
https://api.example.com/data
# header with empty value
curl -H "X-Empty;" https://example.com
# headers from a file (one per line)
curl -H @headers.txt https://example.com
# Content-Type for POST
curl -X POST -H "Content-Type: application/json" \
-d '{"a":1}' https://api.example.comHäufige Header
Die häufigsten Header: Accept sagt dem Server, welches Format du willst; Content-Type beschreibt den Request-Body; Authorization trägt Credentials. --compressed lässt curl komprimierte Antworten anfordern (gzip, br) und automatisch entpacken, sodass Encoding manuell entfällt.
# Accept: negotiate response format
curl -H "Accept: application/json" https://api.example.com
curl -H "Accept: text/html" https://example.com
# Content-Type: describe request body
curl -H "Content-Type: application/json" -d '{"a":1}' https://api.example.com
curl -H "Content-Type: application/x-www-form-urlencoded" -d "a=1" https://api.example.com
# Authorization: credentials
curl -H "Authorization: Bearer TOKEN" https://api.example.com
# Accept-Encoding: ask for compression
curl -H "Accept-Encoding: gzip, br" --compressed https://example.com
# Cache-Control
curl -H "Cache-Control: no-cache" https://api.example.comUser-Agent
Manche Server blockieren den Default-curl-User-Agent. -A (--user-agent) setzt ihn; ein leeres -A entfernt ihn ganz. Die Langform ist -H 'User-Agent: ...'. Viele Scrape-blockierende Seiten prüfen echte Browser-Signaturen, daher ist eine realistische Browser-UA oft nötig.
# default User-Agent looks like: curl/8.7.1
curl -v https://example.com 2>&1 | grep -i user-agent
# set a custom User-Agent
curl -A "Mozilla/5.0 (Windows NT 10.0; Win64; x64)" https://example.com
curl -H "User-Agent: MyBot/1.0" https://example.com
# empty User-Agent
curl -A "" https://example.com
# fake a real browser (some sites require it)
curl -A "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) \
AppleWebKit/537.36 (KHTML, like Gecko) \
Chrome/120.0 Safari/537.36" https://example.com
# per-site default via config
# user-agent = "MyBot/1.0" in ~/.curlrcReferer & Host
-e (--referer) setzt den Referer-Header. Host zu überschreiben ist essenziell beim Testen von Virtual Hosts per IP: der Server wählt die richtige Site anhand von Host. CORS-bewusste Endpunkte verlangen oft Origin; X-Forwarded-For/Proto simulieren Anfragen hinter einem Proxy oder Load Balancer.
# set Referer header
curl -H "Referer: https://google.com" https://example.com/page
curl -e https://google.com https://example.com/page
# set Host header (override DNS)
curl -H "Host: api.example.com" https://192.168.1.10/users
# combined: test a vhost by IP with custom Host
curl -H "Host: api.example.com" \
-H "X-Forwarded-Proto: https" \
http://10.0.0.5/health
# Origin header (for CORS/POST forms)
curl -H "Origin: https://mysite.com" \
-X POST -d "x=1" https://api.example.com/form
# X-Forwarded-For (debugging proxies)
curl -H "X-Forwarded-For: 1.2.3.4" https://api.example.comHeader entfernen
-H 'Header-Name:' (mit Doppelpunkt, ohne Wert) sagt curl, für diesen Header keinen Wert zu senden, und entfernt damit effektiv einen Default-Header wie User-Agent oder Accept-Encoding. curl ersetzt einen Header bei erneuter Angabe desselben Namens statt Duplikate zu senden. Praktisch für minimalistische Anfragen.
# remove a header by giving it no value
curl -H "User-Agent:" https://example.com
# remove Accept-Encoding (disable compression)
curl -H "Accept-Encoding:" https://example.com
# remove all auto-added headers and send minimal request
curl -H "Host:" -H "User-Agent:" -H "Accept:" https://example.com
# prevent curl from adding Accept-Encoding
curl --no-keepalive https://example.com
# replace a default header instead of adding a duplicate
# (curl replaces, doesn't duplicate, when -H name matches)
curl -H "Accept: text/plain" https://example.comPOST-Daten & Formulare
Formular-Daten (-d)
-d (--data) sendet URL-kodierte Formulardaten und schaltet auf POST. Mehrere -d-Flags werden mit & zusammengefügt. -d entfernt führenden/nachgestellten Whitespace und Zeilenumbrüche; --data-binary erhält sie; --data-raw schaltet die @file-Funktion ganz ab (ein Literwert mit @ wird unverändert gesendet).
# URL-encoded form data
curl -d "name=Alice&age=30" https://api.example.com/form
# explicit POST (same result; -d implies POST)
curl -X POST -d "name=Alice" https://api.example.com/form
# multiple -d are joined with &
curl -d "name=Alice" -d "age=30" https://api.example.com/form
# -d strips newlines; use --data-binary to preserve them
curl --data-binary "line1\nline2" https://api.example.com
# raw data, no content-type added
curl --data-raw "name=Alice&age=30" https://api.example.com
# default Content-Type: application/x-www-form-urlencoded
curl -v -d "a=1" https://api.example.com 2>&1 | grep -i content-typeURL-Encoding
--data-urlencode percent-kodiert den Wert (oder das ganze name=value), sodass Leerzeichen, &, = oder Nicht-ASCII nicht manuell kodiert werden müssen. Mit name@file werden die Dateiinhalte als Wert URL-kodiert. Für nutzergelieferte Daten immer verwenden, um die Formularstruktur nicht zu brechen.
# spaces and special chars must be encoded
curl -d "name=Alice%20Smith" https://api.example.com
curl -d "name=Alice+Smith" https://api.example.com
# --data-urlencode encodes the value for you
curl --data-urlencode "name=Alice Smith" https://api.example.com
curl --data-urlencode "[email protected]" https://api.example.com
# encode name=value pair (both encoded)
curl --data-urlencode "name=Alice & Bob" https://api.example.com
# encode only the value after =, with explicit content-type
curl --data-urlencode "query=SELECT * FROM users" \
-H "Content-Type: application/x-www-form-urlencoded" \
https://api.example.com/search
# encode content of a file
curl --data-urlencode [email protected] https://api.example.comBinärdaten
--data-binary sendet eine Datei bytegenau (mit Zeilenumbrüchen und Null-Bytes), anders als -d, das sie entfernt. -T streamt die Datei, sodass der Speicher bei großen Uploads flach bleibt. Um vorkomprimierte Daten zu senden, mit -H 'Content-Encoding: gzip' hineinpipen — der Server muss das unterstützen; sonst Transfer-Encoding: chunked.
# send a binary file as the body
curl --data-binary @image.png https://api.example.com/upload
# upload with explicit content type
curl --data-binary @image.png \
-H "Content-Type: image/png" \
https://api.example.com/upload
# raw bytes (no @ expansion, no stripping)
curl --data-raw "$(printf '\x00\x01\x02')" https://api.example.com
# stream a large file without buffering in memory
curl -T bigfile.iso https://api.example.com/upload
# send gzipped body
gzip -c data.json | curl --data-binary @- \
-H "Content-Encoding: gzip" \
-H "Content-Type: application/json" \
https://api.example.com/dataAus Datei lesen (@file)
-d @file liest den Request-Body aus einer Datei (das @ triggert das Lesen). --data-binary @file erhält die Bytes. -d @- liest von stdin — perfekt, um jq, curl oder andere Transformationen hineinzupipen. Beginnt ein Literwert mit @ und soll nicht als Datei expandiert werden, --data-raw verwenden.
# read body from a file
curl -d @data.txt https://api.example.com/form
# read JSON body from a file
curl -H "Content-Type: application/json" \
-d @payload.json https://api.example.com
# binary-safe file read
curl --data-binary @image.png https://api.example.com/upload
# read from stdin
echo '{"a":1}' | curl -d @- https://api.example.com
# pipe through curl (transform then send)
jq '{name, age}' input.json | \
curl -H "Content-Type: application/json" -d @- https://api.example.com
# file name starting with @ (use --data-raw)
curl --data-raw "@mention" https://api.example.comContent-Type & Formulare
Content-Type immer an das Body-Format anpassen: application/x-www-form-urlencoded (Default für -d), application/json (mit -H), multipart/form-data (automatisch durch -F), text/xml für SOAP. charset=utf-8 zu ergänzen ist gute Praxis bei Nicht-ASCII-Daten. Abweichungen lassen Server den Body ablehnen oder falsch parsen.
# default for -d: application/x-www-form-urlencoded
curl -d "name=Alice" https://api.example.com
# JSON body
curl -H "Content-Type: application/json" \
-d '{"name":"Alice"}' https://api.example.com
# multipart form (file upload, see File Upload section)
curl -F "[email protected]" https://api.example.com/upload
# text/plain body
curl -H "Content-Type: text/plain" -d "hello" https://api.example.com
# XML body (SOAP)
curl -H "Content-Type: text/xml" \
-d '<?xml version="1.0"?><env:Envelope/>' \
https://api.example.com/soap
# set charset explicitly
curl -H "Content-Type: application/json; charset=utf-8" \
-d '{"name":"éàç"}' https://api.example.comJSON-Anfragen
Einfacher JSON-POST
JSON-Anfragen brauchen -H 'Content-Type: application/json' plus -d mit einem JSON-String. JSON in einfache Anführungszeichen setzen, damit die Shell die doppelten innen nicht anfasst. Die Antwort durch jq '.' pipen für lesbare Ausgabe, oder jq '.field' für einen konkreten Wert.
# JSON POST request
curl -X POST \
-H "Content-Type: application/json" \
-d '{"name":"Alice","age":30}' \
https://api.example.com/users
# -d already implies POST, so -X is optional
curl -H "Content-Type: application/json" \
-d '{"name":"Alice"}' \
https://api.example.com/users
# ask for JSON back
curl -H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{"name":"Alice"}' \
https://api.example.com/users
# pretty-print the JSON response (pipe to jq)
curl -s -H "Accept: application/json" \
https://api.example.com/users/1 | jq .JSON aus Datei
Bei komplexem JSON in einer .json-Datei ablegen und -d @file verwenden (oder --data-binary @file, um exakte Bytes inkl. Zeilenumbrüchen zu erhalten). Mit jq -n pipen lässt sich JSON programmatisch bauen ohne fummeliges Escaping. Vorher immer mit jq . validieren — ein Syntaxfehler verschwendet eine Anfrage.
# POST JSON body from a file
curl -H "Content-Type: application/json" \
-d @payload.json https://api.example.com/users
# binary-safe (preserves exact bytes)
curl -H "Content-Type: application/json" \
--data-binary @payload.json https://api.example.com/users
# generate JSON with jq, then POST
jq -n '{name: "Alice", age: 30}' | \
curl -H "Content-Type: application/json" \
-d @- https://api.example.com/users
# validate JSON before sending
jq . payload.json && \
curl -H "Content-Type: application/json" \
-d @payload.json https://api.example.com/users
# send a JSON array
curl -H "Content-Type: application/json" \
-d '[{"id":1},{"id":2}]' https://api.example.com/batchJSON mit Variablen
Variablen in JSON-Strings zu interpolieren scheitert an Anführungszeichen und Sonderzeichen. Das sichere Muster ist jq --arg/--argjson: es baut gültiges JSON und escapet Werte korrekt. --arg für Strings, --argjson für Zahlen/Booleans. Für Secrets lieber eine Header-Datei (-H @file) als Kommandozeilen-Argumente, um Leaks über ps zu vermeiden.
# interpolate a shell variable into JSON (risky for special chars)
NAME="Alice"
curl -H "Content-Type: application/json" \
-d "{\"name\":\"$NAME\"}" https://api.example.com
# safer: build JSON with jq
NAME="Alice"
jq -n --arg name "$NAME" '{name: $name}' | \
curl -H "Content-Type: application/json" -d @- https://api.example.com
# multiple variables
NAME="Alice"; AGE=30
jq -n --arg name "$NAME" --argjson age "$AGE" \
'{name: $name, age: $age}' | \
curl -H "Content-Type: application/json" -d @- https://api.example.com
# read secret from env, hide from ps
TOKEN="$API_TOKEN" curl -H "Authorization: Bearer $API_TOKEN" \
-d '{"x":1}' https://api.example.comGraphQL-Anfragen
GraphQL nutzt einen einzelnen POST-Endpunkt mit JSON-Body, der einen 'query'-String und optional 'variables' enthält. Inline-Queries erfordern Escaping innerer doppelter Anführungszeichen, daher komplexe Queries in einer .json-Datei ablegen und -d @file nutzen. Introspection (die __schema-Query) listet die Typen der API und ist ideal zum Erkunden.
# GraphQL query as JSON body
curl -X POST \
-H "Content-Type: application/json" \
-H "Authorization: Bearer TOKEN" \
-d '{"query":"{ user(id:1) { name email } }"}' \
https://api.example.com/graphql
# query with variables
curl -X POST \
-H "Content-Type: application/json" \
-d '{"query":"query($id:Int!){ user(id:$id){name} }","variables":{"id":1}}' \
https://api.example.com/graphql
# query from a file (multi-line, no escaping pain)
curl -X POST \
-H "Content-Type: application/json" \
-d @query.json https://api.example.com/graphql
# introspection: list all types
curl -s -X POST -H "Content-Type: application/json" \
-d '{"query":"{ __schema { types { name } } }"}' \
https://api.example.com/graphql | jqContent Negotiation
Accept verhandelt das Antwortformat; viele REST-APIs liefern standardmäßig JSON, unterstützen aber XML- oder CSV-Alternativen. --compressed fordert gzip/brotli an und entpackt automatisch. APIs versionieren oft über Accept (z. B. GitHub: application/vnd.github+json). Den tatsächlich zurückgegebenen Content-Type prüfen, um die Negotiation zu bestätigen.
# request JSON
curl -H "Accept: application/json" https://api.example.com/users
# request XML
curl -H "Accept: application/xml" https://api.example.com/users
# request a specific version
curl -H "Accept: application/vnd.api+json; version=2" \
https://api.example.com/users
# request anything (default is */*)
curl -H "Accept: */*" https://example.com
# request compression and auto-decompress
curl --compressed -H "Accept-Encoding: gzip, br" https://example.com
# inspect what the server actually returns
curl -s -o /dev/null -D - https://api.example.com/users | grep -i content-typeDatei-Upload
Multipart-Upload (-F)
-F (--form) baut eine multipart/form-data-Anfrage — der Standard für Datei-Uploads. -F file=@path liest die Datei. ;filename= überschreibt den Namen, den der Server sieht, und ;type= setzt den Content-Type des Parts. Mehrere Dateien im selben Feldnamen (mit [] in vielen Frameworks) brauchen mehrere -F-Flags.
# upload a file as a multipart form field
curl -F "[email protected]" https://api.example.com/upload
# -F sets POST + multipart/form-data automatically
# the @ prefix reads the file
# add a text field alongside the file
curl -F "[email protected]" -F "description=My photo" \
https://api.example.com/upload
# rename the uploaded file (server sees "avatar.jpg")
curl -F "[email protected];filename=avatar.jpg" \
https://api.example.com/upload
# set explicit content-type for the file part
curl -F "[email protected];type=image/jpeg" \
https://api.example.com/upload
# upload multiple files in one field
curl -F "[email protected]" -F "[email protected]" \
https://api.example.com/uploadMehrere Dateien & Felder
Multipart-Formulare können Dateien und Textfelder mischen. [] in Feldnamen für Array-artige Uploads verwenden (Frameworks wie Rails/PHP parsen diese in Arrays). Ein Feld kann JSON tragen, indem ;type=application/json gesetzt wird — der Server liest es als strukturierte Daten statt als Datei. Curl kann Verzeichnisse nativ nicht hochladen; vorher tar-en.
# upload two files and a caption
curl -F "[email protected]" \
-F "[email protected]" \
-F "caption=Summer trip" \
https://api.example.com/gallery
# array-style field names (PHP/Rails style)
curl -F "files[][email protected]" -F "files[][email protected]" \
https://api.example.com/upload
# send a file's contents as a regular text field
curl -F "[email protected];type=application/json" \
https://api.example.com/upload
# mix file and JSON fields
curl -F "[email protected]" \
-F "options={\"priority\":\"high\"};type=application/json" \
https://api.example.com/upload
# upload a directory as a tar (workaround)
tar -cf - mydir/ | curl -F "tar=@-;filename=dir.tar" \
https://api.example.com/uploadStreaming-Upload (-T)
-T (--upload-file) nutzt PUT und streamt die Datei, sodass der Speicher selbst bei riesigen Uploads flach bleibt — deutlich besser als -d @file bei großen Datenmengen. -T - liest von stdin. -C - nimmt eine unterbrochene Übertragung wieder auf. Mit nachgestelltem Schrägstrich an der URL hängt curl den lokalen Dateinamen an (wie HTTP-PUT-Spiegelung).
# upload a file with PUT (streaming, low memory)
curl -T localfile.txt https://example.com/upload/remote.txt
# upload to a URL with the local filename
curl -T localfile.txt https://example.com/upload/
# stream from stdin (pipe into PUT body)
cat data.json | curl -T - https://api.example.com/data
# upload with authentication
curl -T file.zip -u user:pass \
https://example.com/upload/file.zip
# upload with progress bar
curl -T bigfile.iso --progress-bar \
https://example.com/upload/bigfile.iso
# resume an interrupted upload
curl -T bigfile.iso -C - https://example.com/upload/bigfile.isoUpload mit Fortschritt
Standardmäßig zeigt curl eine Fortschrittsanzeige auf stderr. --progress-bar wechselt auf einen einfacheren Balken. -s (silent) versteckt ihn; S ergänzen (-sS), um Fehler trotzdem zu sehen. Fortschrittsinfos gehen an stderr, also bleibt stdout (der Body) sauber — praktisch beim Pipen. Mit -w und %{size_upload} sowie %{time_total} eine Einzeiler-Zusammenfassung bekommen.
# default progress meter (terminal)
curl -T file.zip https://example.com/upload
# simple progress bar
curl -T file.zip --progress-bar https://example.com/upload
# no progress at all (silent)
curl -T file.zip -s https://example.com/upload
# show progress but only errors (silent + show-error)
curl -T file.zip -sS https://example.com/upload
# custom progress with --write-out
curl -T file.zip -w "Uploaded %{size_upload} bytes in %{time_total}s\n" \
-o /dev/null https://example.com/upload
# redirect progress to stderr, body to file
curl -T file.zip --progress-bar 2> progress.log \
-o response.txt https://example.com/uploadUpload-Felder & Typen
Curl rät den MIME-Typ aus der Datei-Extension. Mit ;type= überschreiben. ;filename= ändert, was der Server sieht — praktisch für bereinigte Namen. Das <-Präfix liest Dateiinhalte in ein Textfeld (statt sie als Datei zu senden) — hilfreich, wenn die API einen String erwartet, die Daten aber in einer Datei liegen.
# specify MIME type explicitly
curl -F "[email protected];type=text/csv" https://api.example.com/import
# let curl guess from the extension (default)
curl -F "[email protected]" https://api.example.com/upload
# force generic type
curl -F "[email protected];type=application/octet-stream" \
https://api.example.com/upload
# send a file with a custom filename visible to server
curl -F "upload=@/tmp/abc123;filename=report.pdf;type=application/pdf" \
https://api.example.com/upload
# send a string as if it were a file
curl -F "file=hello world" https://api.example.com/upload
# send a string as a file with a filename
curl -F "file=<inline.txt" https://api.example.com/uploadAuthentifizierung
Basic Auth (-u)
-u (--user) sendet HTTP-Basic-Auth (base64-kodiertes user:pass). Passwort weglassen, um danach gefragt zu werden (sicherer — bleibt aus der Shell-History). --netrc liest Credentials aus ~/.netrc, sodass sie nie auf der Kommandozeile auftauchen. Basic ist unsicher über plain HTTP; immer HTTPS. Jeder mit Shell-Zugriff kann -u-Argumente über ps sehen.
# HTTP Basic authentication
curl -u user:pass https://api.example.com/secret
curl --user user:pass https://api.example.com/secret
# prompt for password (don't put it on the command line)
curl -u user https://api.example.com/secret
# basic auth with explicit method (curl picks the safest by default)
curl -u user:pass --basic https://api.example.com/secret
# use a .netrc file instead of -u
echo "machine example.com login user password pass" > ~/.netrc
curl --netrc https://example.com/secret
# base64-encode credentials manually (equivalent)
curl -H "Authorization: Basic $(echo -n user:pass | base64)" \
https://api.example.com/secretBearer-Token
Bearer-Tokens (OAuth2, JWT) gehören in den Authorization-Header. Tokens nicht auf die Kommandozeile legen — ps exponiert sie an andere Nutzer. Aus einer Datei (-H @file) oder Umgebungsvariable lesen, und für sensible Werte eine Header-Datei nutzen. Das Refresh-Token-Snippet zeigt den Standard-OAuth2-Client-Credentials-Fluss.
# Bearer token (OAuth2 / JWT)
curl -H "Authorization: Bearer ACCESS_TOKEN" \
https://api.example.com/protected
# token from an environment variable
curl -H "Authorization: Bearer $TOKEN" \
https://api.example.com/protected
# token from a file (avoids shell history and ps)
curl -H "Authorization: Bearer $(cat ~/.token)" \
https://api.example.com/protected
# headers from a file (cleanest for secrets)
echo "Authorization: Bearer $TOKEN" > /tmp/hdr.txt
curl -H @/tmp/hdr.txt https://api.example.com/protected
rm /tmp/hdr.txt
# refresh token flow (simplified)
TOKEN=$(curl -s -u client:secret -d "grant_type=refresh_token" \
-d "refresh_token=$REFRESH" \
https://auth.example.com/token | jq -r .access_token)
curl -H "Authorization: Bearer $TOKEN" https://api.example.com/dataAPI-Key im Header
API-Keys erscheinen in eigenen Headern (X-API-Key, X-Client-Id) oder als Query-Parameter. Query-Strings leaken in Server-Logs und Browser-History, also Header bevorzugen. Für AWS signiert --aws-sigv4 die Anfrage mit deinen access/secret keys. GitHub nutzt Bearer mit einem personal access token (ghp_...).
# API key in a custom header (varies by service)
curl -H "X-API-Key: abc123" https://api.example.com/data
# API key as a query parameter
curl "https://api.example.com/data?api_key=abc123"
# GitHub personal access token
curl -H "Authorization: Bearer ghp_TOKEN" \
https://api.github.com/user
# AWS-style signature v4 (use the AWS CLI or aws-sigv4)
curl --aws-sigv4 "aws:amz:us-east-1:service" \
-u "ACCESS:SECRET" https://service.amazonaws.com/
# multiple keys
curl -H "X-API-Key: abc123" \
-H "X-Client-Id: my-app" \
https://api.example.com/dataNetrc-Dateien
--netrc liest Credentials aus ~/.netrc, das Hosts auf login/password-Paare mappt. Die Datei muss chmod 600 haben, sonst verweigert curl die Nutzung. --netrc-file zeigt auf einen eigenen Ort. Der 'default'-Eintrag gilt für jeden Host ohne konkreten machine-Eintrag. Der sauberste Weg, Secrets von der Kommandozeile fernzuhalten.
# ~/.netrc stores credentials per host
# format:
# machine api.example.com
# login alice
# password secret
# machine github.com
# login alice
# password ghp_TOKEN
# use netrc automatically
curl --netrc https://api.example.com/data
# use a custom netrc file
curl --netrc-file ~/.netrc.work https://api.example.com/data
# ignore netrc for this request
curl --netrc-optional -u user:pass https://api.example.com/data
# secure the file (required by curl on some systems)
chmod 600 ~/.netrc
# machine + default for any host
# default
# login anonymous
# password guestDigest & NTLM
Basic sendet Credentials im Klartext (über HTTPS ist das okay). Digest sendet einen Hash, nie das Passwort. NTLM und Negotiate behandeln Windows-/Kerberos-SSO. --anyauth lässt curl anhand des WWW-Authenticate-Headers des Servers wählen. Der Server muss die Methode unterstützen; -v zeigt, welche Challenges er stellt.
# digest authentication (challenge-response, more secure than Basic)
curl -u user:pass --digest https://api.example.com/secret
# NTLM (Windows auth)
curl -u user:pass --ntlm https://intranet.example.com/
# negotiate (Kerberos/SPNEGO)
curl -u user:pass --negotiate https://intranet.example.com/
# anyauth: let curl pick the method
curl -u user:pass --anyauth https://api.example.com/secret
# specify the service principal for negotiate
curl -u user:pass --negotiate --service-name HTTP/intranet.example.com \
https://intranet.example.com/
# show which method the server requested
curl -v -u user:pass --anyauth https://api.example.com 2>&1 | grep -i www-authenticateOAuth & Tokens
OAuth2 hat mehrere Grant-Typen: client_credentials (Server-zu-Server), authorization_code (nach Browser-Login), password (Legacy). Der Token-Endpunkt gibt ein access_token (und oft ein refresh_token); das access_token als Bearer-Header für Folgerequests nutzen. App-Passwörter (GitLab, GitHub) funktionieren mit -u und umgehen 2FA-Einschränkungen.
# OAuth2 client credentials grant
curl -u client_id:client_secret \
-d "grant_type=client_credentials" \
-d "scope=read write" \
https://auth.example.com/oauth/token
# OAuth2 authorization code (after browser redirect)
curl -d "grant_type=authorization_code" \
-d "code=AUTH_CODE" \
-d "redirect_uri=https://app.example.com/callback" \
-u client_id:client_secret \
https://auth.example.com/oauth/token
# OAuth2 password grant (deprecated but still seen)
curl -d "grant_type=password" \
-d "username=user" -d "password=pass" \
-u client_id:client_secret \
https://auth.example.com/oauth/token
# use the access token
curl -H "Authorization: Bearer $ACCESS_TOKEN" \
https://api.example.com/me
# basic auth with username and app password (e.g., GitLab)
curl -u "user:app_password" https://gitlab.example.com/api/v4/userProxy
HTTP/HTTPS-Proxy
-x (--proxy) leitet die Anfrage durch einen Proxy. Die Umgebungsvariablen http_proxy/https_proxy/no_proxy werden automatisch beachtet. Für HTTPS-Ziele durch einen HTTP-Proxy nutzt curl CONNECT zum Tunneln. no_proxy setzen, um interne Hosts am Proxy vorbei zu leiten — kommasepariert, ein führender Punkt bedeutet Subdomains.
# use a proxy for all requests
curl -x http://proxy.example.com:8080 https://example.com
curl --proxy http://proxy.example.com:8080 https://example.com
# HTTPS proxy (proxy connection itself is TLS)
curl -x https://proxy.example.com:8443 https://example.com
# proxy via environment variable
export https_proxy=http://proxy.example.com:8080
curl https://example.com
# proxy for a specific scheme only
curl --proxy http://proxy:8080 http://example.com
curl --proxy https://secure-proxy:8443 https://example.com
# bypass proxy for specific hosts
export no_proxy="localhost,127.0.0.1,.internal.example.com"
curl https://internal.example.com # direct, no proxySOCKS-Proxy
SOCKS5 ist protokollagnostisch, tunnel also HTTP, HTTPS und mehr. --socks5-hostname lässt den Proxy das DNS auflösen (praktisch, um Hosts zu erreichen, die deine Maschine nicht auflösen kann). Ein üblicher Trick: ssh -D 1080 erzeugt einen lokalen SOCKS-Proxy, der Traffic durch einen entfernten SSH-Server tunnel — großartig für sicheres Browsen in untrusteten Netzen.
# SOCKS5 proxy
curl -x socks5://proxy.example.com:1080 https://example.com
curl --socks5 proxy.example.com:1080 https://example.com
# SOCKS5 with local DNS resolution (server resolves)
curl --socks5-hostname proxy.example.com:1080 https://example.com
# SOCKS4 proxy
curl --socks4 proxy.example.com:1080 https://example.com
# SSH tunnel as a SOCKS proxy (run separately)
# ssh -D 1080 user@remote -N
curl -x socks5://localhost:1080 https://example.com
# SOCKS proxy with authentication
curl -x socks5://user:[email protected]:1080 https://example.comProxy-Authentifizierung
Proxies verlangen oft Authentifizierung. -U (--proxy-user) liefert Credentials; --proxy-ntlm/--proxy-digest/--proxy-anyauth wählen das Schema. user:pass in der -x-URL einzubetten ist äquivalent. Für NTLM (Windows-Unternehmens-Proxies) übernimmt --proxy-ntlm den mehrstufigen Handshake. -U user (ohne Passwort) fragt interaktiv ab.
# proxy with username/password
curl -x http://user:[email protected]:8080 https://example.com
# separate proxy auth flag
curl -x http://proxy.example.com:8080 -U user:pass https://example.com
curl --proxy-user user:pass -x http://proxy.example.com:8080 https://example.com
# prompt for proxy password
curl -U user -x http://proxy.example.com:8080 https://example.com
# NTLM-authenticated proxy
curl -U user:pass --proxy-ntlm \
-x http://proxy.example.com:8080 https://example.com
# digest-authenticated proxy
curl -U user:pass --proxy-digest \
-x http://proxy.example.com:8080 https://example.com
# anyauth for proxy
curl -U user:pass --proxy-anyauth \
-x http://proxy.example.com:8080 https://example.comNo Proxy & Bypass
--noproxy (oder die no_proxy-Umgebungsvariable) listet Hosts, die den Proxy umgehen. Ein führender Punkt bedeutet 'diese Domain und alle Subdomains'. '*' umgeht den Proxy für alles. CIDR-Bereiche funktionieren in aktuellen curl-Versionen. Essenziell, wenn ein externer Proxy interne Unternehmens-Hosts nicht erreicht.
# bypass proxy for specific hosts
curl --noproxy "localhost,127.0.0.1,.internal.com" \
-x http://proxy:8080 https://example.com
# via environment variable
export no_proxy="localhost,127.0.0.1,.internal.com,10.0.0.0/8"
curl https://internal.com # direct
# wildcard match for a domain and all subdomains
export no_proxy=".example.com"
curl https://api.example.com # bypasses proxy
# disable proxy entirely for one request
curl --noproxy "*" -x http://proxy:8080 https://example.com
# ignore *_proxy env vars for one request
curl --noproxy "*" https://example.com
# CIDR ranges (curl 7.86+)
export no_proxy="192.168.0.0/16,10.0.0.0/8"Proxy-Header & Tunneling
--proxy-header ergänzt Header, die für den Proxy selbst bestimmt sind (wie Proxy-Authorization), nicht für das Ziel weitergeleitet. -p (--proxytunnel) zwingt curl, CONNECT auch für plain HTTP zu nutzen (normalerweise nur für HTTPS). Nützlich, wenn der Proxy plain HTTP abfängt und man einen End-to-End-Tunnel will.
# add a header sent only to the proxy (not the target)
curl -x http://proxy:8080 \
--proxy-header "Proxy-Authorization: Bearer xyz" \
https://example.com
# custom header to proxy + normal header to target
curl -x http://proxy:8080 \
--proxy-header "X-Proxy-Tag: abc" \
-H "X-Target-Tag: def" \
https://example.com
# force CONNECT tunneling even for HTTP
curl -p -x http://proxy:8080 http://example.com
curl --proxytunnel -x http://proxy:8080 http://example.com
# inspect the CONNECT request to the proxy
curl -v -x http://proxy:8080 https://example.com 2>&1 | grep -i connect
# disable proxy tunneling (send HTTP directly through proxy)
curl --proxytunnel -p -x http://proxy:8080 http://example.comSSL/TLS
Verifikation überspringen (--insecure)
-k (--insecure) überspringt die Zertifikatsverifikation — nur für selbstsignierte Dev-Zertifikate, nie in Produktion, da es MITM-Angriffe erlaubt. Standardmäßig werden Kette und Hostname verifiziert. --resolve pinnt eine IP bei korrektem Host/SNI — nützlich, um ein konkretes Backend hinter einem Load Balancer zu testen.
# skip certificate verification (DANGEROUS)
curl -k https://self-signed.example.com
curl --insecure https://self-signed.example.com
# verify normally (default)
curl https://example.com
# show the cert chain
curl -v https://example.com 2>&1 | grep -E "SSL|cert"
# only verify the cert, not the hostname
curl --insecure https://example.com # both off
# (no built-in flag to verify cert but skip hostname;
# use a custom CA bundle instead)
# connect to a host with a mismatched certificate
curl -k --resolve example.com:443:1.2.3.4 https://example.com
# debug TLS handshake
curl -v https://example.com 2>&1 | grep -E "TLS|SSL|cert|cipher"Client-Zertifikate
Mutual TLS (mTLS) verlangt sowohl ein Client-Zertifikat (--cert) als auch seinen privaten Schlüssel (--key). PEM ist Default; --cert-type P12 behandelt PKCS#12-Bundles. --pass liefert das Schlüsselpasswort. --cacert überschreibt die vertrauenswürdige CA-Liste (Default: System-Store) — praktisch für interne CAs. mTLS ist verbreitet in Zero-Trust- und Service-Mesh-Setups.
# client certificate + private key (mTLS)
curl --cert client.pem --key client.key \
https://mtls.example.com/api
# PKCS#12 bundle (combined cert + key)
curl --cert client.p12 --cert-type P12 \
https://mtls.example.com/api
# password-protected key
curl --cert client.pem --key client.key \
--pass secret https://mtls.example.com/api
# PEM cert with password
curl --cert client.pem:secret https://mtls.example.com/api
# specify CA bundle to verify the server
curl --cacert custom-ca.pem https://internal.example.com
# mutual TLS with custom CA
curl --cert client.pem --key client.key \
--cacert internal-ca.pem \
https://mtls.internal.example.comTLS-Version
--tlsv1.X setzt die Mindestversion; --tls-max begrenzt sie. 1.2+ zu erzwingen deaktiviert Legacy-Protokolle (SSLv3, TLS 1.0/1.1) mit bekannten Schwächen. Standardmäßig wird die höchstmögliche gemeinsam unterstützte Version ausgehandelt. -v zeigt die ausgehandelte Version und Cipher in der Zeile 'SSL connection using'.
# force a minimum TLS version
curl --tlsv1.2 https://example.com
curl --tlsv1.3 https://example.com
# force an exact TLS version
curl --tls-max 1.2 https://example.com # cap at 1.2
curl --tls-max 1.3 https://example.com
# negotiate the highest version both support (default)
curl https://example.com
# disable specific versions
curl --tlsv1.2 --tls-max 1.2 https://example.com # only 1.2
# list versions curl supports
curl --version | grep -i tls
# debug which version was negotiated
curl -v https://example.com 2>&1 | grep -i "SSL connection"Ciphers & CA-Bundle
--ciphers beschränkt die Cipher-Suite (OpenSSL-Syntax). --cacert zeigt auf ein eigenes CA-Bundle, um Server mit internen/privaten CAs zu verifizieren — das System-Bundle (/etc/ssl/certs oder macOS-Keychain) wird standardmäßig genutzt. Ist das CA-Bundle veraltet, können Server mit gültigen Zertifikaten abgelehnt werden; ein Update von curl (oder des ca-certificates-Pakets) behebt das.
# specify allowed ciphers
curl --ciphers "AES256-GCM-SHA384:AES128-GCM-SHA256" \
https://example.com
# use a custom CA bundle to verify the server
curl --cacert /etc/ssl/certs/internal-ca.pem \
https://internal.example.com
# use the system CA store (default)
curl https://example.com
# use Mozilla's CA bundle (download separately)
curl --cacert cacert.pem https://example.com
# show the cipher used
curl -v https://example.com 2>&1 | grep -i cipher
# disable certificate revocation checks (CRL/OCSP)
curl --cacert ca.pem --no-clobber https://example.comZertifikats-Inspektion
Mit -v das Zertifikat des Servers inspizieren (subject, issuer, Gültigkeit). --pinnedpubkey erzwingt Certificate Pinning — die Anfrage scheitert, wenn der öffentliche Schlüssel des Servers nicht passt, und entlarvt so rogue CAs. Für tiefes TLS-Debugging gibt --trace-ascii den kompletten Handshake aus. openssl s_client ist eine mächtigere Alternative zur Zertifikats-Inspektion.
# show the server certificate in verbose mode
curl -v https://example.com 2>&1 | grep -A1 "server certificate"
# extract certificate details (subject, issuer, dates)
curl -v https://example.com 2>&1 | grep -E "subject|issuer|start date|expire date"
# download the server certificate (PEM)
curl -v https://example.com 2>&1 | \
awk '/-----BEGIN CERT/,/-----END CERT/' > server.pem
# verify cert only, don't transfer body
curl -I https://example.com
# pin a specific certificate (fingerprint)
curl --pinnedpubkey sha256//BASE64= https://example.com
# check OCSP stapling
curl -v https://example.com 2>&1 | grep -i ocsp
# show full TLS trace
curl --trace-ascii - https://example.com | grep -i certDownloads
In Datei speichern (-o/-O)
-o schreibt in einen gewählten Dateinamen; -O nutzt den entfernten Dateinamen (aus dem URL-Basename). --output-dir setzt den Zielordner für -O. Mehrere -O-Flags laden mehrere Dateien in einem Aufruf. -o /dev/null verwirft den Body — nützlich, um Webhooks auszulösen oder Timing zu messen, ohne Daten zu speichern.
# save with a custom name
curl -o page.html https://example.com/index.html
# save with the remote filename
curl -O https://example.com/file.zip
# save to a specific directory
curl -O --output-dir /tmp/downloads https://example.com/file.zip
# save with remote name to a specific dir
curl -o /tmp/file.zip https://example.com/file.zip
# download multiple files with remote names
curl -O https://example.com/a.zip -O https://example.com/b.zip
# save to /dev/null (just trigger the request)
curl -o /dev/null https://example.com/webhookDownloads fortsetzen (-C)
-C - (--continue-at -) nimmt einen Download wieder auf, wobei die bestehende Dateigröße als Byte-Offset dient. Der Server muss Range-Anfragen unterstützen (Accept-Ranges: bytes prüfen). Mit --retry kombinieren, um flakige Verbindungen zu behandeln — curl wiederholt und setzt fort und spart Bandbreite.
# resume a partial download
curl -C - -o file.zip https://example.com/file.zip
curl --continue-at - -o file.zip https://example.com/file.zip
# resume with -O (remote name)
curl -C - -O https://example.com/file.zip
# start download at a specific byte offset
curl -C 1024 -o file.zip https://example.com/file.zip
# server must support Range requests
curl -I https://example.com/file.zip | grep -i accept-ranges
# resume an interrupted large download
curl -C - --progress-bar -O https://example.com/bigfile.iso
# combine with retry for unreliable connections
curl -C - --retry 5 --retry-all-errors -O \
https://example.com/bigfile.isoFortschrittsbalken
--progress-bar zeigt einen einfacheren ###-Balken statt der Default-Anzeige. -s schaltet allen Fortschritt aus; -sS behält Fehler. Fortschritt geht an stderr, also verschmutzt er nicht den Body auf stdout — beides separat erfassbar. -w mit %{size_download} und %{time_total} liefert eine saubere Einzeiler-Zusammenfassung für Skripte.
# default progress meter
curl -O https://example.com/file.zip
# simple progress bar (alternative style)
curl --progress-bar -O https://example.com/file.zip
# silent (no progress, no body output)
curl -s -O https://example.com/file.zip
# silent but still show errors
curl -sS -O https://example.com/file.zip
# show only errors (no progress, body to file)
curl -sS -o file.zip https://example.com/file.zip
# custom one-line progress
curl -o file.zip -w "%{size_download} bytes in %{time_total}s\n" \
https://example.com/file.zip
# redirect progress to a file, body to another
curl -o file.zip --progress-bar 2> progress.log \
https://example.com/file.zipDownload-Bereich
-r (--range) fordert einen Byte-Bereich an und erhält 206 Partial Content. Nützlich zum Vorschauen großer Dateien, zum Fortsetzen oder parallelen Multi-Connection-Downloads. Der Server muss Accept-Ranges: bytes anbieten. Mit Shell-Hintergrundprozessen (&) kombinieren, um Bereiche parallel zu laden, dann zusammenzufügen — die Basis von Download-Beschleunigern wie aria2.
# download bytes 0-1023 (first 1KB)
curl -r 0-1023 -o part1.bin https://example.com/file.zip
# download from byte 1024 to end
curl -r 1024- -o rest.bin https://example.com/file.zip
# download last 500 bytes
curl -r -500 -o tail.bin https://example.com/file.zip
# check if server supports ranges
curl -I https://example.com/file.zip | grep -i accept-ranges
# Accept-Ranges: bytes -> supported
# parallel range download (split a large file)
curl -r 0-49999999 -o part1.bin https://example.com/big.iso &
curl -r 50000000-99999999 -o part2.bin https://example.com/big.iso &
wait
cat part1.bin part2.bin > big.iso
# HTTP/1.1 206 Partial Content confirms success
curl -r 0-100 -v https://example.com/file.zip 2>&1 | grep HTTPMehrere Dateien & Globbing
URL-Globbing ([1-3], {a,b,c}) stellt eine Anfrage pro Expansion. --output-dir legt fest, wo -O sie speichert. Für echte Parallelität (curl selbst ist sequenziell) URLs an xargs -P N pipen, um N curls gleichzeitig laufen zu lassen. Das beschleunigt das Laden vieler kleiner Dateien vom selben Host drastisch (die Rate-Limits des Servers respektieren).
# download file1.zip, file2.zip, file3.zip
curl -O https://example.com/file[1-3].zip
# download with a step (1, 3, 5, 7, 9)
curl -O https://example.com/file[1-9:2].zip
# download from multiple paths
curl -O https://example.com/{a,b,c}.zip
# download to a specific directory
curl -O --output-dir /tmp/downloads \
https://example.com/file[1-3].zip
# sequential download (one at a time)
for url in https://example.com/{a,b,c}.zip; do
curl -O "$url"
done
# parallel download with xargs
echo "https://example.com/{a,b,c}.zip" | tr ' ' '\n' | \
xargs -n1 -P3 curl -OMirror & Rekursion
Curl ist von Design her Single-URL — es rekursiert nicht. Um eine Site zu spiegeln, wget --mirror oder Link-Extraktion per Skript mit grep verwenden. Für Batch-Downloads URLs in einer Datei listen und an xargs -P N füttern. Das Sitemap-Beispiel lädt jede von einer Site indexierte Seite — praktisch für Offline-Snapshots.
# curl doesn't recurse like wget, but you can script it
# download a page and extract its links
curl -s https://example.com/ | \
grep -oP 'href="\K[^"]+' | grep '^http' > urls.txt
# download all linked PDFs
curl -s https://example.com/docs | \
grep -oP 'href="\K[^"]+\.pdf' | \
while read pdf; do curl -O "https://example.com/$pdf"; done
# use wget instead for true mirroring
# wget --mirror --convert-links --page-requisites https://example.com/
# download a list of URLs from a file
xargs -n1 -P4 curl -O < urls.txt
# fetch a sitemap and download every URL
curl -s https://example.com/sitemap.xml | \
grep -oP '<loc>\K[^<]+' | xargs -n1 -P4 curl -OTimeouts & Retries
Verbindungs-Timeout
--connect-timeout begrenzt die Zeit zum Aufbau der TCP/TLS-Verbindung (nicht der Übertragung). Ohne ihn kann curl bei unerreichbaren Hosts minutenlang hängen (OS-Default ~2 Minuten). In Skripten immer beides setzen: --connect-timeout (schnell fehlschlagen bei toten Hosts) und --max-time (die ganze Operation begrenzen), um Hängern zu vermeiden.
# max time to establish the connection (seconds)
curl --connect-timeout 10 https://example.com
# connect timeout in milliseconds (curl 7.32+)
curl --connect-timeout 2.5 https://example.com
# connect timeout + overall max time
curl --connect-timeout 10 --max-time 30 https://example.com
# DNS resolution timeout (curl 7.88+, otherwise OS-controlled)
curl --happy-eyeballs-timeout-ms 1000 https://example.com
# fail fast on unreachable hosts
curl --connect-timeout 3 -sS https://example.com || echo "unreachable"
# combine with --retry for resilience
curl --connect-timeout 5 --max-time 20 --retry 3 \
https://example.comMax Time
--max-time (-m) begrenzt die gesamte Operation (DNS + Verbindung + Übertragung). --speed-time/--speed-limit brechen ab, wenn die Übertragung über eine Dauer unter einer Byte-Rate bleibt — perfekt für hängende Downloads. Exit-Code 28 bedeutet Timeout; $? in Skripten prüfen. Immer ein max-time setzen, um endloses Hängen an langsamen oder steckengebliebenen Servern zu verhindern.
# overall timeout for the whole operation
curl --max-time 30 https://example.com
curl -m 30 https://example.com
# max time in milliseconds (decimal)
curl --max-time 2.5 https://example.com
# max time with no data transfer (idle timeout)
curl --speed-time 30 --speed-limit 1000 https://example.com
# abort if speed < 1000 bytes/sec for 30 sec
# max time for a file upload
curl -T big.iso --max-time 600 https://example.com/upload
# max time per redirect hop
curl -L --max-time 60 https://example.com/redirect
# check exit code (28 = timed out)
curl --max-time 5 https://slow.example.com || echo "exit code: $?"Retries
--retry wiederholt bei transienten Fehlern (Timeouts, 5xx, 429) standardmäßig; --retry-all-errors erweitert auf alle Fehler. --retry-delay ergänzt eine feste Wartezeit (verdoppelt sich je Versuch) zwischen Retries. --retry-connrefused wiederholt selbst bei verweigerter Verbindung (z. B. Server startet neu). Mit -C - paaren, um Teildownloads fortzusetzen. Essenziell für resiliente Skripte.
# retry up to 3 times on transient errors
curl --retry 3 https://example.com
# retry on any error (not just transient)
curl --retry 3 --retry-all-errors https://example.com
# retry with exponential backoff
curl --retry 5 --retry-delay 2 https://example.com
# waits 2s, 4s, 6s, 8s, 10s between retries (curl 7.66+)
# retry on connection-refused specifically
curl --retry 3 --retry-connrefused https://example.com
# retry only on HTTP 5xx and 429
curl --retry 3 --retry-all-errors \
-H "Accept: application/json" https://api.example.com
# combine with resume for large downloads
curl --retry 5 --retry-all-errors -C - -O \
https://example.com/bigfile.isoRetry-Delay & Backoff
--retry-delay N wartet N Sekunden vor dem ersten Retry, dann verdoppelt (N, 2N, 4N...). Curl beachtet den Retry-After-Header des Servers bei 429/503. Für eigene Logik (Jitter, maximale Gesamtwartezeit, Bedingung an Statuscode) curl in eine Shell-Schleife wickeln. --retry immer mit --max-time paaren, damit Retries nicht ewig laufen.
# fixed delay between retries
curl --retry 5 --retry-delay 2 https://example.com
# exponential backoff (curl doubles the delay each time)
curl --retry 5 --retry-delay 1 https://example.com
# waits: 1s, 2s, 4s, 8s, 16s
# honor Retry-After header (default with --retry)
curl --retry 3 https://example.com
# cap retry delay with a max-time
curl --retry 10 --retry-delay 1 --max-time 60 https://example.com
# custom backoff in a shell loop
for i in 1 2 3 4 5; do
curl -s --max-time 10 https://example.com && break
echo "attempt $i failed, waiting $((i*2))s..."
sleep $((i*2))
done
# retry on specific HTTP status codes
curl --retry 5 --retry-all-errors \
-w "%{http_code}" -o /dev/null -s https://example.comSpeed-Limits
--speed-time/--speed-limit bricht eine steckengebliebene Übertragung ab (keine Daten für N Sekunden bei einer Rate unter dem Limit) — Exit-Code 28. --limit-rate begrenzt die Übertragungsrate (unterstützt K/M/G-Suffixe), nützlich, um Bandbreite nicht zu sättigen oder langsame Netze zu simulieren. Mit --retry kombinieren, um hängende Downloads automatisch fortzusetzen.
# abort if speed drops below 1000 bytes/sec for 30 sec
curl --speed-limit 1000 --speed-time 30 -O \
https://example.com/bigfile.iso
# shorthand: --speed-time defaults to 30 if only --speed-limit is set
curl --speed-limit 1000 -O https://example.com/bigfile.iso
# limit max download rate (bytes/sec)
curl --limit-rate 100k -O https://example.com/file.zip
# limit rate with units (K, M, G)
curl --limit-rate 1M -O https://example.com/file.zip
# limit upload rate
curl -T big.iso --limit-rate 500k https://example.com/upload
# combine with retry on stall
curl --speed-limit 1000 --speed-time 30 \
--retry 5 --retry-all-errors \
-O https://example.com/bigfile.isoDebugging
Verbose (-v)
-v (verbose) ist das primäre Debugging-Werkzeug. '>'-Zeilen sind die Anfrage, '<'-Zeilen die Antwort, '*'-Zeilen curl-Internas (DNS, TLS, Verbindung) — alles auf stderr, sodass stdout für den Body sauber bleibt. 2>&1 umleiten, um mit grep zu filtern. -o /dev/null verwenden, um Header ohne Speichern des Bodys zu inspizieren.
# verbose: full request + response + curl internals
curl -v https://example.com
# output goes to stderr; body to stdout
curl -v https://example.com > body.txt 2> debug.log
# only show request headers (> lines)
curl -v https://example.com 2>&1 | grep '^>'
# only show response headers (< lines)
curl -v https://example.com 2>&1 | grep '^<'
# only show curl info (* lines)
curl -v https://example.com 2>&1 | grep '^\*'
# verbose without sending the body
curl -v -o /dev/null https://example.comTrace
--trace gibt alles aus (inkl. Body) in Hex + ASCII; --trace-ascii lässt das Hex weg. --trace-time ergänzt Zeitstempel. Anders als -v zeigt trace die Request- und Response-Bodies — die erste Wahl beim Debuggen binärer oder komprimierter Daten. Warnung: --trace loggt Secrets (Passwörter, Tokens) — vor dem Teilen bereinigen.
# trace: dump all sent and received data (hex + ASCII)
curl --trace - https://example.com
# trace ASCII only (no hex dump)
curl --trace-ascii - https://example.com
# trace to a file
curl --trace trace.log https://example.com
# trace including time per packet
curl --trace-ascii - --trace-time https://example.com
# trace with request body (hidden by default in -v)
curl --trace-ascii - -d "secret=data" https://example.com
# compare verbose vs trace
curl -v https://example.com 2>&1 | head
curl --trace-ascii - https://example.com | headNur Header
-I sendet eine HEAD-Anfrage (die meisten Server liefern dieselben Header wie GET ohne Body). -D gibt Header in eine Datei oder '-' (stdout) aus. Um zu sehen, was curl gesendet hat (Request-Header), -v verwenden und grep '^>'. Nur für den Statuscode ist -w '%{http_code}' am saubersten. Hinweis: Manche Server antworten auf HEAD anders als auf GET.
# HEAD request: response headers only
curl -I https://example.com
curl --head https://example.com
# dump response headers to stdout, discard body
curl -D - -o /dev/null https://example.com
# dump response headers to a file
curl -D headers.txt -o body.html https://example.com
# show request headers (what curl sent)
curl -v -o /dev/null https://example.com 2>&1 | grep '^>'
# show both request and response headers
curl -v -o /dev/null https://example.com 2>&1 | grep -E '^[<>]'
# show only the status line
curl -s -o /dev/null -w "%{http_code} %{http_version}\n" \
https://example.com
curl -D - -o /dev/null -s https://example.com | head -1Trennung von Request & Response
Verbose-Ausgabe geht an stderr, der Body an stdout, sodass beide mit Umleitung separat erfasst werden. -D speichert Response-Header; -o den Body; -v (stderr) die volle Konversation. Diese Trennung ist essenziell beim API-Debugging: Header und Body unabhängig inspizieren, Timing loggen und Anfrage gegen Antwort vergleichen.
# capture request and response separately
curl -v https://example.com \
-o body.txt \
1> /dev/null 2> verbose.log
# extract request only
curl -v https://example.com 2>&1 1>/dev/null | grep '^>' > request.txt
# extract response only
curl -v https://example.com 2>&1 1>/dev/null | grep '^<' > response.txt
# split headers and body cleanly
curl -s -D headers.txt -o body.txt https://example.com
# capture everything: body, headers, request, timing
curl -s -D headers.txt -o body.txt \
-w "@curl-format.txt" https://example.com >> timing.log
# show body to terminal, headers to file
curl -D headers.txt https://example.comDebug-Optionen
--dry-run druckt, was curl täte, ohne zu senden — ideal, um URL-Globbing und Konfiguration zu prüfen. --resolve pinnt einen Host auf eine IP und umgeht DNS (essenziell zum Testen eines konkreten Backends). --interface bindet an eine Netzwerkkarte oder IP. --no-keepalive erzwingt eine frische Verbindung pro Anfrage — praktisch, um Verbindungs-Bugs zu reproduzieren.
# show what curl would do without sending
curl --dry-run https://example.com
# dump parsed config files
curl --config /dev/null -v https://example.com 2>&1 | grep -i config
# force a fresh connection (no keep-alive reuse)
curl --no-keepalive https://example.com
# disable DNS cache
curl --doh-url https://dns.example.com/dns-query https://example.com
# use a specific network interface
curl --interface eth0 https://example.com
curl --interface 192.168.1.5 https://example.com
# resolve a hostname to a specific IP (no DNS)
curl --resolve example.com:443:1.2.3.4 https://example.com
# debug globbing (list URLs without fetching)
curl --dry-run -O https://example.com/file[1-3].zipAntwort-Infos
HTTP-Statuscode
-w '%{http_code}' extrahiert nur den Statuscode für Skripte. -f (--fail) lässt curl bei 4xx/5xx mit nicht-null beenden (ohne gibt curl 0 zurück, sogar für 404). --fail-with-body druckt zusätzlich den Response-Body bei Fehlern (nützlicher zum Debuggen). Den Statuscode zum Verzweigen in Skripten nutzen: 2xx Erfolg, 3xx Umleitung, 4xx Client-Fehler, 5xx Server-Fehler.
# get only the status code
curl -s -o /dev/null -w "%{http_code}" https://example.com
echo # 200
# status code with newline
curl -s -o /dev/null -w "%{http_code}\n" https://example.com
# full status line
curl -s -o /dev/null -w "%{http_version} %{http_code}\n" https://example.com
# branch on status code
CODE=$(curl -s -o /dev/null -w "%{http_code}" https://example.com)
if [ "$CODE" = "200" ]; then echo "ok"; else echo "fail: $CODE"; fi
# fail on HTTP errors (4xx, 5xx)
curl -f https://example.com || echo "HTTP error"
curl --fail-with-body https://example.com # 7.76+: still print body
# check redirect chain status codes
curl -L -w "%{num_redirects} redirects, final %{http_code}\n" \
-o /dev/null -s https://short.url/abcWrite-out-Format
-w (--write-out) formatiert Infos zur Übertragung mit %{variable}-Platzhaltern. Timings (time_namelookup, time_connect, time_appconnect, time_total) zerlegen, wo die Zeit hingeht — essenziell für Performance-Analyse. %{json} gibt alle Variablen als JSON aus (curl 7.70+). Ein Format in einer Datei ablegen und mit -w @file wiederverwenden.
# built-in variables with -w / --write-out
curl -s -o /dev/null -w "HTTP %{http_code} in %{time_total}s\n" \
https://example.com
# URL info
curl -s -o /dev/null -w "URL: %{url_effective}\nIP: %{remote_ip}\n" \
https://example.com
# timing breakdown
curl -s -o /dev/null \
-w "dns=%{time_namelookup} connect=%{time_connect} tls=%{time_appconnect} total=%{time_total}\n" \
https://example.com
# size info
curl -s -o /dev/null \
-w "downloaded=%{size_download} uploaded=%{size_upload}\n" \
https://example.com
# write format from a file
cat > fmt.txt <<EOF
http_code: %{http_code}
time_total: %{time_total}s
EOF
curl -s -o /dev/null -w "@fmt.txt" https://example.com
# JSON output (curl 7.70+)
curl -s -o /dev/null -w "%{json}" https://example.comAntwortzeit
Die Timing-Variablen zerlegen die Anfrage: time_namelookup (DNS), time_connect (TCP), time_appconnect (TLS), time_starttransfer (TTFB — erstes Byte empfangen), time_total (ganze Übertragung). TTFB ist die Schlüsselmetrik für API-Latenz. Timings über Endpunkte vergleichen, um Flaschenhälse zu finden (DNS, Netzwerk, TLS oder Serververarbeitung).
# total time
curl -s -o /dev/null -w "%{time_total}\n" https://example.com
# DNS resolution time
curl -s -o /dev/null -w "%{time_namelookup}\n" https://example.com
# TCP connect time
curl -s -o /dev/null -w "%{time_connect}\n" https://example.com
# TLS handshake time (after connect)
curl -s -o /dev/null -w "%{time_appconnect}\n" https://example.com
# time to first byte (TTFB)
curl -s -o /dev/null -w "%{time_starttransfer}\n" https://example.com
# full timing breakdown
curl -s -o /dev/null -w \
"dns=%{time_namelookup} tcp=%{time_connect} tls=%{time_appconnect} ttfb=%{time_starttransfer} total=%{time_total}\n" \
https://example.com
# compare two endpoints
curl -s -o /dev/null -w "%{time_total}\n" https://api1.example.com
curl -s -o /dev/null -w "%{time_total}\n" https://api2.example.comHeader extrahieren
-D - gibt Response-Header auf stdout aus; durch grep pipen, um einen konkreten Header zu extrahieren. -I (HEAD) funktioniert auch, kann aber von GET abweichen. -w liefert %{url_effective} (finale URL nach Umleitungen), %{remote_ip} (Server-IP) und %{num_redirects}. Unbezahlbar zum Debuggen von CDN-Routing, Umleitungen und Server-Identifikation.
# dump all response headers to stdout, discard body
curl -s -D - -o /dev/null https://example.com
# extract one header (Content-Type)
curl -s -D - -o /dev/null https://example.com | \
grep -i "^content-type:"
# extract Content-Length (size)
curl -s -I https://example.com/file.zip | grep -i content-length
# extract Set-Cookie
curl -s -D - -o /dev/null https://example.com | grep -i set-cookie
# extract the final URL after redirects
curl -s -L -o /dev/null -w "%{url_effective}\n" https://short.url/abc
# extract the server's IP address
curl -s -o /dev/null -w "%{remote_ip}\n" https://example.com
# count redirects
curl -s -L -o /dev/null -w "%{num_redirects}\n" https://short.url/abcFormat-Variablen
-w (--write-out) unterstützt Dutzende Variablen (mit 'curl -w "%{json}"' alle als JSON sehen). Die Timing-Variablen sind die Grundlage des Performance-Monitoring; die size-Variablen verfolgen Bandbreite; url_effective und num_redirects debuggen Routing. %{json} (curl 7.70+) ist der einfachste Weg, alles für Logging oder Dashboards zu erfassen.
# complete list of common -w variables
# %{http_code} - response status code
# %{http_version} - HTTP version (1.1, 2, 3)
# %{url_effective} - final URL after redirects
# %{remote_ip} - server IP address
# %{remote_port} - server port
# %{time_namelookup} - DNS resolution time
# %{time_connect} - TCP connect time
# %{time_appconnect} - TLS handshake time
# %{time_pretransfer} - time before transfer starts
# %{time_starttransfer} - TTFB (first byte)
# %{time_total} - total time
# %{size_download} - bytes downloaded
# %{size_upload} - bytes uploaded
# %{size_header} - header bytes
# %{size_request} - request bytes
# %{num_redirects} - number of redirects
# %{ssl_verify_result}- SSL verification result
# %{content_type} - response content type
# %{json} - all variables as JSON (7.70+)
# reference: curl -w "%{json}" https://example.com
curl -s -o /dev/null -w "%{json}" https://example.com | jqFTP & SMTP
FTP-Grundlagen
curl unterstützt FTP für Downloads (GET) und Uploads (PUT via -T). -u liefert Credentials; anonymer FTP nutzt 'anonymous' + eine E-Mail. FTPS (--ftp-ssl) verschlüsselt den Kontrollkanal. Passiv-Modus (Default) funktioniert durch NAT/Firewalls; --ftp-port für Aktiv-Modus, wenn der Server es verlangt.
# anonymous FTP download
curl ftp://ftp.example.com/file.txt
# authenticated FTP
curl -u user:pass ftp://ftp.example.com/file.txt
# list a directory
curl ftp://ftp.example.com/directory/
# download a file
curl -O ftp://ftp.example.com/file.txt
# upload a file (PUT)
curl -T local.txt ftp://ftp.example.com/remote.txt -u user:pass
# use explicit FTPS (FTP over TLS)
curl --ftp-ssl ftp://ftp.example.com/file.txt -u user:pass
# passive mode (default; needed behind NAT/firewalls)
curl --ftp-pasv ftp://ftp.example.com/ -u user:passFTP-Upload
-T lädt eine Datei per FTP-STOR-Befehl hoch. --ftp-create-dirs erzeugt Elternverzeichnisse mit MKD. --append nutzt APPE, um an eine bestehende Datei anzuhängen. -C - nimmt einen unterbrochenen Upload wieder auf. Globbing ({a,b}) lädt mehrere Dateien in einem Aufruf hoch. Für Verzeichnisse vorher tar-en — FTP kann Ordner nicht direkt hochladen.
# upload a single file
curl -T local.txt ftp://ftp.example.com/remote.txt -u user:pass
# upload with explicit filename
curl -T local.txt -o remote.txt ftp://ftp.example.com/ -u user:pass
# upload to a directory
curl -T local.txt ftp://ftp.example.com/uploads/ -u user:pass
# create a directory (MKD command)
curl --ftp-create-dirs -T local.txt \
ftp://ftp.example.com/newdir/file.txt -u user:pass
# append to a remote file
curl -T local.txt --append ftp://ftp.example.com/remote.txt -u user:pass
# upload multiple files with globbing
curl -T "{file1,file2}.txt" ftp://ftp.example.com/ -u user:pass
# resume an interrupted upload
curl -C - -T bigfile.iso ftp://ftp.example.com/bigfile.iso -u user:passFTP-Auflistung
Eine FTP-URL, die auf / endet, listet das Verzeichnis. --list-only liefert nur Dateinamen. -v zeigt die zugrunde liegenden FTP-Befehle (USER, PASS, PASV, LIST, RETR) — unbezahlbar beim Debuggen von Rechte- oder Firewall-Problemen. Curl kann nicht in Unterverzeichnisse rekursieren; für rekursive FTP-Downloads wget --mirror oder ein Skript verwenden.
# list a directory (default format)
curl ftp://ftp.example.com/ -u user:pass
# list with --list-only (names only, no details)
curl --list-only ftp://ftp.example.com/ -u user:pass
# list a specific directory
curl ftp://ftp.example.com/pub/ -u user:pass
# recursive listing (curl doesn't recurse natively)
# use --ftp-method to control PASV/EPSV behavior
curl --ftp-method nocwd ftp://ftp.example.com/ -u user:pass
# download all files in a directory (with globbing)
curl -O ftp://ftp.example.com/pub/*.txt -u user:pass
# show server responses (FTP commands)
curl -v ftp://ftp.example.com/ -u user:pass 2>&1 | grep -E "^\*|^[<>]"SMTP-E-Mail senden
curl kann E-Mails über SMTP senden. Der Body (mit Headern) liegt in einer Datei, die via -T hineingeppipet wird. --mail-from und --mail-rcpt setzen den Envelope (unabhängig von den To/From-Headern im Body). --ssl-reqd erzwingt STARTTLS (Port 587); smtps:// nutzt implizites TLS (Port 465). Auth via -u (LOGIN/PLAIN). Großartig für skriptgesteuerte Alerts von Servern ohne Mail-Client.
# send email via SMTP
curl --url "smtp://smtp.example.com:587" \
--mail-from "[email protected]" \
--mail-rcpt "[email protected]" \
-u "[email protected]:password" \
-T email.txt
# email body from a file
cat > email.txt <<EOF
From: [email protected]
To: [email protected]
Subject: Test from curl
Hello from curl!
EOF
curl --url "smtp://smtp.example.com:587" \
--mail-from "[email protected]" \
--mail-rcpt "[email protected]" \
-u "[email protected]:password" \
--ssl-reqd \
-T email.txt
# multiple recipients
curl --url "smtp://smtp.example.com:587" \
--mail-from "[email protected]" \
--mail-rcpt "[email protected]" \
--mail-rcpt "[email protected]" \
-T email.txt
# STARTTLS (port 587)
curl --ssl-reqd --url "smtp://smtp.example.com:587" \
--mail-from "[email protected]" --mail-rcpt "[email protected]" \
-T email.txt
# SMTPS (implicit TLS, port 465)
curl --url "smtps://smtp.example.com:465" \
--mail-from "[email protected]" --mail-rcpt "[email protected]" \
-T email.txtIMAP & POP3
curl kann Post über IMAP und POP3 lesen. Die URL-Syntax umfasst Ordner-, UID- und Section-Selektoren. IMAP unterstützt Suche (?UNSEEN, ?SUBJECT usw.). imaps:// und pop3s:// nutzen implizites TLS. Hinweis: curl ist für Mail nur lesend — es kann über IMAP/POP3 abrufen, aber nicht senden (für Senden SMTP nutzen). Der Body wird als roher RFC-822-Nachrichtentext zurückgegeben.
# list IMAP mailboxes
curl -u "user:pass" --url "imap://imap.example.com:143"
# list messages in INBOX
curl -u "user:pass" --url "imap://imap.example.com/INBOX"
# fetch a specific message (UID 1)
curl -u "user:pass" --url "imap://imap.example.com/INBOX;UID=1"
# fetch message headers only
curl -u "user:pass" --url "imap://imap.example.com/INBOX;UID=1;SECTION=HEADER"
# search for unread messages
curl -u "user:pass" --url "imap://imap.example.com/INBOX?UNSEEN"
# POP3: list messages
curl -u "user:pass" --url "pop3://pop.example.com/"
# POP3: retrieve message #1
curl -u "user:pass" --url "pop3://pop.example.com/1"
# use IMAPS (implicit TLS, port 993)
curl -u "user:pass" --url "imaps://imap.example.com/INBOX"FTPS & SFTP
FTP hat drei verschlüsselte Varianten: FTPS explicit (--ftp-ssl, Upgrade auf Port 21), FTPS implicit (ftps://, TLS von Anfang an auf Port 990) und SFTP (sftp://, völlig anderes Protokoll über SSH auf Port 22). SFTP unterstützt Schlüssel-Auth via --key (mit --pass für verschlüsselte Schlüssel). SFTP wird heute wegen seiner Einfachheit und Firewall-Freundlichkeit meist FTPS vorgezogen.
# FTPS: explicit TLS (upgrade to TLS on plain FTP port)
curl --ftp-ssl --ssl-reqd ftp://ftp.example.com/ -u user:pass
# FTPS: implicit TLS (TLS from the start, port 990)
curl ftps://ftp.example.com:990/ -u user:pass
# SFTP (SSH File Transfer Protocol, port 22)
curl -u user sftp://sftp.example.com/file.txt
# SFTP with key authentication
curl -u user --key ~/.ssh/id_rsa \
sftp://sftp.example.com/file.txt
# SFTP with a password-protected key
curl -u user --key ~/.ssh/id_rsa --pass passphrase \
sftp://sftp.example.com/file.txt
# SFTP upload
curl -u user -T local.txt sftp://sftp.example.com/remote.txt
# SFTP list directory
curl -u user sftp://sftp.example.com/Parallel & Batch
Parallele Downloads
Curl selbst ist sequenziell — für gleichzeitiges Laden mehrere curls parallel via & und wait ausführen, oder xargs -P N nutzen, um N auf einmal laufen zu lassen. Das beschleunigt viele kleine Dateien drastisch. Rücksicht nehmen: zu viele parallele Verbindungen können den Server überlasten oder Rate-Limits auslösen. 4-8 parallel ist ein vernünftiger Default.
# background multiple curls (shell parallelism)
curl -O https://example.com/a.zip &
curl -O https://example.com/b.zip &
curl -O https://example.com/c.zip &
wait
# parallel with xargs (4 concurrent)
echo -e "https://example.com/a.zip\nhttps://example.com/b.zip" | \
xargs -n1 -P4 curl -O
# parallel with a URL list file
xargs -n1 -P4 curl -O < urls.txt
# zsh-specific parallel with {..}
for url in https://example.com/{a,b,c}.zip; do
curl -O "$url" &
done; wait
# bash-specific using arrays and &
urls=("https://example.com/a.zip" "https://example.com/b.zip")
for url in "${urls[@]}"; do curl -O "$url" & done; waitxargs parallel
xargs -P N führt N Prozesse gleichzeitig aus und füttert jede stdin-Zeile als Argument. -a liest aus einer Datei. -I {} erlaubt, die URL irgendwo in einem Befehl zu platzieren. Der einfachste Weg, curl-Downloads ohne Extra-Tools zu parallelisieren. Für host-bewusstes Throttling oder komplexe Retry-Logik einen eigenen Download-Manager wie aria2c verwenden.
# download each URL from a file, 4 concurrent
xargs -n1 -P4 -a urls.txt curl -O
# download with custom names, parallel
cat urls.txt | xargs -n2 -P4 sh -c 'curl -o "$0" "$1"'
# download and process each response
cat urls.txt | xargs -n1 -P4 -I {} sh -c \
'curl -s {} | jq .field'
# retry failures in parallel
xargs -n1 -P4 -a urls.txt curl --retry 3 -O
# limit total concurrent connections to a host
# (xargs doesn't know about hosts; use a queue or a download manager)
xargs -n1 -P4 -a urls.txt curl -O --limit-rate 1M
# show progress for parallel downloads
xargs -n1 -P4 -a urls.txt curl -O --progress-bar 2>&1URL-Globbing
Globbing expandiert URLs in mehrere Anfragen: [1-10]-Bereiche (mit optionalem :step und Null-Auffüllung über führende Nullen) und {a,b,c}-Listen. -o 'file#1.zip' nutzt #1 als Zähler für eigene Ausgabenamen. -g (--globoff) schaltet die Expansion ab — essenziell für URLs mit wörtlichen [ ] oder { } (JSON, IPv6).
# numeric range: 1, 2, 3
curl -O https://example.com/file[1-3].zip
# range with step: 0, 5, 10, 15, 20
curl -O https://example.com/file[0-20:5].zip
# leading zeros (zero-padded)
curl -O https://example.com/file[01-10].zip # 01, 02, ..., 10
# list expansion: a, b, c
curl -O https://example.com/{a,b,c}.zip
# nested globs
curl -O https://example.com/{v1,v2}/file[1-2].txt
# save each with a custom name pattern
curl -o "file#1.zip" https://example.com/file[1-3].zip
# disable globbing (literal brackets)
curl -g "https://example.com/file[1].zip"Sequentieller Bereich
Für sequenzielle Downloads (wenn Parallelität den Server überlasten oder Rate-Limits verletzen würde) über URLs in bash loopen. sleep für Höflichkeit ergänzen. -sf (silent + fail) lässt curl bei HTTP-Fehlern mit nicht-null beenden, sodass die Schleife früh abbrechen kann. Das sichere Muster für Scraping oder Crawling: rücksichtsvoll sein, Pausen ergänzen, Fehler behandeln.
# fetch URLs one at a time (no parallelism)
for i in 1 2 3 4 5; do
curl -O "https://example.com/page$i.html"
done
# range with brace expansion (bash/zsh)
for i in {1..10}; do
curl -s -O "https://example.com/page$i.html"
done
# with a delay between requests (rate limiting)
for i in {1..10}; do
curl -s -O "https://example.com/page$i.html"
sleep 1
done
# retry each URL individually
for url in $(cat urls.txt); do
curl -s --retry 3 -O "$url"
done
# conditional: stop on first error
for url in $(cat urls.txt); do
curl -sf -O "$url" || { echo "failed: $url"; break; }
doneGNU parallel & curl
GNU parallel ist mächtiger als xargs: es erhält die Ausgabereihenfolge, zeigt Fortschritt (--bar) und behandelt Argumente flexibler. -j N setzt die Nebenläufigkeit. :::: liest aus einer Datei, ::: von der Kommandozeile. parallel ideal für Batch-API-Tests, Scraping und Benchmarks, wo saubere, geordnete Ausgabe von gleichzeitigen Anfragen gebraucht wird.
# GNU parallel: smarter than xargs (preserves order, progress)
parallel -j4 curl -O {} ::: https://example.com/a.zip \
https://example.com/b.zip
# parallel from a file
parallel -j4 curl -O :::: urls.txt
# parallel with progress bar
parallel --bar -j4 curl -O :::: urls.txt
# parallel with output capture
parallel -j4 'curl -s -o {}.out {}' :::: urls.txt
# parallel with retry and timing
parallel -j4 'curl -s -w "{} %{time_total}s\n" -o /dev/null {}' :::: urls.txt
# parallel POST requests
parallel -j4 'curl -s -X POST -d "id={}" https://api.example.com/{}' \
::: 1 2 3 4 5
# combine with --dry-run to preview
parallel --dry-run -j4 curl -O :::: urls.txtKonfigurationsdateien
.curlrc-Grundlagen
~/.curlrc hält Default-Optionen, die bei jedem curl-Aufruf gelten. Lange Optionsnamen ohne führendes -- verwenden. Eine Option pro Zeile; Werte dürfen in Anführungszeichen stehen. So bleiben gängige Einstellungen (Timeouts, Retries, User-Agent) über Skripte und interaktive Nutzung hinweg konsistent. Pro Anfrage überschreiben, indem die Option explizit auf der Kommandozeile übergeben wird.
# ~/.curlrc is read automatically by curl
# one option per line, long option names without the --
# ~/.curlrc example:
# show progress by default
silent
# always follow redirects
location
# default User-Agent
user-agent = "MyApp/1.0"
# default headers
header = "Accept: application/json"
# retry transient errors
retry = 3
# connect timeout
connect-timeout = 10
# max time
max-time = 30
# lines starting with # are comments
# blank lines are ignored
# test: curl https://example.com now uses all the aboveOrt der Konfigurationsdatei
Curl liest standardmäßig ~/.curlrc (oder $CURL_HOME/.curlrc). -K (--config) zeigt auf eine konkrete Datei; -K - liest von stdin. -q (--disable) überspringt die Konfigurationsdatei ganz — nützlich, wenn eine Default-Option eine konkrete Anfrage bricht. CURL_HOME verlagert das Suchverzeichnis für portable Setups.
# default locations (searched in order):
# 1. ~/.curlrc (or $CURL_HOME/.curlrc)
# 2. /etc/curl/curlrc (system-wide, if compiled in)
# set a custom config directory
export CURL_HOME=/etc/curl
# curl then reads $CURL_HOME/.curlrc
# specify a config file explicitly
curl -K /path/to/myconfig https://example.com
curl --config /path/to/myconfig https://example.com
# read config from stdin
echo "silent" | curl -K - https://example.com
# disable config file reading
curl -q https://example.com
curl --disable https://example.com
# check which config curl reads
curl -v https://example.com 2>&1 | grep -i configConfig mit -K
-K lädt Optionen aus einer Datei — perfekt für Umgebungs-Configs (Dev- vs. Prod-Tokens, Timeouts, Header). Secrets in einer Config-Datei (chmod 600) halten sie aus Shell-History und ps heraus. Mehrere -K-Dateien werden der Reihe nach verarbeitet, spätere überschreiben frühere — nützlich für eine Basis-Config plus umgebungsspezifische Overrides.
# use a config file for a specific request
curl -K prod.conf https://api.example.com/data
# prod.conf:
# header = "Authorization: Bearer prod-token"
# header = "X-Environment: production"
# connect-timeout = 5
# max-time = 20
# dev.conf (different settings)
# header = "Authorization: Bearer dev-token"
# header = "X-Environment: development"
# max-time = 60
# switch environments by config file
curl -K dev.conf https://api.example.com/data
curl -K prod.conf https://api.example.com/data
# config file with URL
# echo "url = https://api.example.com/data" > req.conf
curl -K req.conf
# multiple config files (later ones override earlier)
curl -K defaults.conf -K override.conf https://example.comHäufige Defaults
Ein solides ~/.curlrc macht jeden curl-Aufruf sicherer und konsistenter: Timeouts verhindern Hängern, Retries behandeln transiente Fehler, --compressed übernimmt gzip transparent, und ein reduzierter User-Agent verringert Fingerprinting. Die write-out-Zeile loggt Timing und Status für jede Anfrage — unbezahlbar für schnelle Performance-Checks.
# ~/.curlrc with sensible production defaults
# always follow redirects
location
# limit redirects
max-redirs = 5
# timeouts (fail fast, cap total)
connect-timeout = 10
max-time = 60
# retry transient failures
retry = 3
retry-delay = 2
retry-all-errors
# show errors even when silent
show-error
# auto-decompress responses
compressed
# negotiate HTTP/2
http2
# verify SSL by default (explicit for clarity)
cacert = /etc/ssl/certs/ca-certificates.crt
# don't leak the curl version
user-agent = ""
# verbose timing on failure
write-out = "time: %{time_total}s code: %{http_code}\n"Mehrere Configs
Konfiguration in geschichtete Dateien aufteilen (base, auth, api, environment) hält alles modular und sicher. Mit mehreren -K-Flags der Reihe nach verarbeiten — spätere Dateien überschreiben frühere. Secrets in eine 600-permigierte Datei außerhalb der Versionskontrolle. Ein Wrapper-Skript, das den Stapel lädt, erlaubt 'mycurl' mit allen Defaults.
# base.conf — shared defaults
# silent
# show-error
# compressed
# connect-timeout = 10
# max-time = 30
# auth.conf — credentials (chmod 600)
# user = alice:secret
# header = "Authorization: Bearer TOKEN"
# api.conf — API-specific options
# header = "Accept: application/json"
# header = "X-Client: my-app/2.0"
# retry = 5
# combine configs in order (later overrides earlier)
curl -K base.conf -K auth.conf -K api.conf \
https://api.example.com/data
# config file referencing another (nesting not supported)
# but you can source them in a wrapper script:
# #!/bin/bash
# curl -K base.conf -K auth.conf -K api.conf "$@"
# environment-specific overlay
curl -K base.conf -K "${ENV}.conf" https://api.example.comFortgeschrittene Techniken
Wiederverwendung von Verbindungen
Innerhalb eines einzigen curl-Aufrufs wird die TCP-Verbindung über mehrere URLs zum selben Host wiederverwendet (HTTP keep-alive) und spart den TLS-Handshake-Overhead. --no-keepalive schaltet das ab. --max-connects begrenzt gleichzeitige Verbindungen für Multi-URL-Fetches. Über separate curl-Aufrufe hinweg gibt es keine Wiederverwendung — dafür einen persistenten Client wie httpie oder ein Skript in Python/Node nutzen.
# curl reuses connections within a single invocation
# multiple URLs in one command share the TCP connection
curl -o a.txt https://example.com/a \
-o b.txt https://example.com/b
# keep-alive is on by default
# disable it for a single request
curl --no-keepalive https://example.com
# limit max connections (for multi-URL)
curl --max-connects 4 \
-O https://example.com/a -O https://example.com/b
# persistent session across shell calls (not natively supported)
# but you can use a config file to reduce overhead
curl -K session.conf https://example.com/a
curl -K session.conf https://example.com/b
# check if connection was reused
curl -v https://example.com 2>&1 | grep -i "Connection #0"HTTP/2 & HTTP/3
HTTP/2 multiplext Anfragen über eine Verbindung; HTTP/3 nutzt QUIC über UDP und eliminiert Head-of-Line-Blocking. --http2 verhandelt über ALPN via TLS; --http2-prior-knowledge überspringt die Verhandlung (für cleartext h2c). --http3 braucht einen Spezialbuild von curl. %{http_version} prüfen, um zu bestätigen, was tatsächlich genutzt wurde. Die meisten modernen CDNs unterstützen h2 standardmäßig.
# negotiate HTTP/2 (needs TLS + ALPN)
curl --http2 https://example.com
# force HTTP/2 (fail if not available)
curl --http2-only https://example.com
# negotiate HTTP/3 (QUIC, needs curl built with quiche/openssl-quic)
curl --http3 https://example.com
# force HTTP/3 only
curl --http3-only https://example.com
# check what version was negotiated
curl -s -o /dev/null -w "%{http_version}" https://example.com
echo # 2 or 3
# list supported HTTP versions
curl --version | grep -i -E "http2|http3"
# HTTP/2 with prior knowledge (no upgrade negotiation)
curl --http2-prior-knowledge http://example.comBedingte Anfragen
Bedingte Anfragen sparen Bandbreite: der Server gibt 304 Not Modified (kein Body) zurück, wenn sich die Ressource nicht geändert hat. -z (--time-cond) setzt If-Modified-Since aus einem Datum oder der mtime einer lokalen Datei. Für ETag-basiertes Caching If-None-Match manuell setzen. If-Unmodified-Since ermöglicht optimistische Nebenläufigkeit — das PUT scheitert, wenn jemand anderes die Ressource geändert hat.
# fetch only if modified since a date
curl -z "Wed, 21 Oct 2025 07:28:00 GMT" \
-O https://example.com/data.json
curl --timecond "Wed, 21 Oct 2025 07:28:00 GMT" \
-O https://example.com/data.json
# fetch only if changed (use a local file's mtime)
curl -z local_copy.json -O https://example.com/data.json
# ETag-based conditional (If-None-Match)
curl -H 'If-None-Match: "abc123"' \
-o data.json https://example.com/data.json
# server returns 304 Not Modified if ETag matches
# If-Modified-Since header manually
curl -H "If-Modified-Since: Wed, 21 Oct 2025 07:28:00 GMT" \
https://example.com/data.json
# If-Unmodified-Since (for concurrency control)
curl -X PUT -H "If-Unmodified-Since: Wed, 21 Oct 2025 07:28:00 GMT" \
-d '{"x":1}' https://api.example.com/dataInterface & DNS
--interface bindet an eine Netzwerkkarte oder IP — nützlich auf Multi-Homed-Maschinen. --resolve pinnt einen Host auf eine IP, umgeht DNS und ist ideal zum Testen von Backends hinter einem Load Balancer. --doh-url nutzt DNS-over-HTTPS (Privatsphäre). -4/-6 erzwingen eine IP-Familie. Happy Eyeballs (Default) probiert IPv4 und IPv6, um IPv6-Blackhole-Verzögerungen zu vermeiden.
# bind to a specific network interface
curl --interface eth0 https://example.com
curl --interface 192.168.1.5 https://example.com
# pin a hostname to an IP (skip DNS)
curl --resolve example.com:443:1.2.3.4 https://example.com
# pin multiple hosts
curl --resolve example.com:443:1.2.3.4 \
--resolve api.example.com:443:1.2.3.5 \
https://example.com/
# use a custom DNS server (DoH)
curl --doh-url https://dns.google/dns-query https://example.com
curl --doh-url https://cloudflare-dns.com/dns-query https://example.com
# use a specific DNS resolver (plain DNS, curl 7.84+)
curl --dns-servers 8.8.8.8,1.1.1.1 https://example.com
# happy eyeballs: try IPv4 and IPv6 in parallel
curl --happy-eyeballs-timeout-ms 200 https://example.com
# force IPv4 or IPv6
curl -4 https://example.com
curl -6 https://example.comRange-Anfragen & Partial
Range-Anfragen (-r) laden einen Teil einer Datei und liefern 206 Partial Content. Anwendungsfälle: Vorschau großer Dateien, parallele Multi-Connection-Downloads (in Bereiche aufteilen, gleichzeitig laden, zusammenfügen) und Fortsetzen unterbrochener Übertragungen (-C -). Der Server muss Accept-Ranges: bytes anbieten. Die Basis von Download-Beschleunigern wie aria2.
# request a byte range (first 1024 bytes)
curl -r 0-1023 -o part.bin https://example.com/file.zip
# request from byte 1024 to end
curl -r 1024- -o rest.bin https://example.com/file.zip
# request last 500 bytes
curl -r -500 -o tail.bin https://example.com/file.zip
# check if server supports ranges
curl -I https://example.com/file.zip | grep -i accept-ranges
# download in parallel chunks
curl -r 0-49999999 -o part1.bin https://example.com/big.iso &
curl -r 50000000- -o part2.bin https://example.com/big.iso &
wait
cat part1.bin part2.bin > big.iso
# resume a partial download
curl -C - -o file.zip https://example.com/file.zip
# HTTP 206 = Partial Content (range succeeded)
curl -r 0-100 -v https://example.com/file.zip 2>&1 | grep HTTPExit-Codes
Curls Exit-Codes unterscheiden Fehlerarten: 6 (DNS), 7 (Verbindung), 22 (HTTP-Fehler, nur mit -f), 28 (Timeout), 35 (TLS), 60 (Zertifikat). Damit robuste Skripte bauen, die passend wiederholen (z. B. bei 28 wiederholen, bei 6 schnell fehlschlagen). --fail-with-body liefert den Response-Body auch bei 4xx/5xx und macht das Debuggen von API-Fehlern deutlich einfacher als -f.
# common curl exit codes:
# 0 - success
# 1 - unsupported protocol
# 3 - malformed URL
# 6 - couldn't resolve host (DNS failure)
# 7 - failed to connect
# 22 - HTTP error (use with -f)
# 26 - couldn't read a file (e.g., -d @missing.txt)
# 28 - operation timeout
# 35 - SSL connect error
# 47 - too many redirects
# 52 - server didn't reply anything
# 55 - failed sending network data
# 56 - failed receiving network data
# 60 - certificate verification failed
# check exit code
curl -sf https://example.com || echo "failed: $?"
# branch on specific codes
curl --max-time 5 https://example.com
case $? in
0) echo "ok" ;;
6) echo "DNS failure" ;;
7) echo "connection refused" ;;
28) echo "timeout" ;;
*) echo "error: $?" ;;
esac
# treat HTTP errors as failures
curl -f https://api.example.com || echo "HTTP error"
# still print body on HTTP error (7.76+)
curl --fail-with-body https://api.example.comVerwandte curl-Snippets
Copy-paste ready code for common tasks.
HTTP Methods
GET, POST, PUT, and DELETE requests.
Headers
Set and inspect request and response headers.
Authentication
Basic, bearer, and OAuth credentials.
Cookies
Send, save, and reuse cookies.
Upload and Download
Transfer files to and from a server.
Proxies
Route requests through HTTP or SOCKS proxies.
Follow Redirects
Chase 3xx responses automatically.
Debugging
Trace requests, timing, and transfers.
Was this helpful?