Skip to content

curl Spickzettel

Kommandozeilen-Tool zum Übertragen von Daten mit URLs.

01

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).

curl
# 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.com

Ausgabe & 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.

curl
# 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.com

Verbose & 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.

curl
# 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.com

Weiterleitungen 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).

curl
# 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.com

URL-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/.

curl
# 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).

curl
# 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 http2
02

HTTP-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.

curl
# 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/secret

POST-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.

curl
# 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/users

PUT & 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.

curl
# 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.txt

DELETE

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.

curl
# 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/1

HEAD & 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.

curl
# 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 allow
03

Header

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.

curl
# 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.com

Hä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.

curl
# 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.com

User-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.

curl
# 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 ~/.curlrc

Referer & 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.

curl
# 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.com

Header 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.

curl
# 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.com
04

POST-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).

curl
# 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-type

URL-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.

curl
# 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.com

Binä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.

curl
# 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/data

Aus 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.

curl
# 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.com

Content-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.

curl
# 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.com
05

JSON-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.

curl
# 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.

curl
# 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/batch

JSON 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.

curl
# 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.com

GraphQL-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.

curl
# 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 | jq

Content 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.

curl
# 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-type
06

Datei-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.

curl
# 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/upload

Mehrere 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.

curl
# 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/upload

Streaming-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).

curl
# 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.iso

Upload 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.

curl
# 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/upload

Upload-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.

curl
# 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/upload
07

Authentifizierung

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.

curl
# 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/secret

Bearer-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.

curl
# 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/data

API-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_...).

curl
# 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/data

Netrc-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.

curl
# ~/.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 guest

Digest & 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.

curl
# 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-authenticate

OAuth & 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.

curl
# 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/user
08

Cookies

Cookies senden (-b)

-b (--cookie) sendet Cookies. Ein String wird unverändert gesendet; ein Dateiname (Netscape-Format) lädt gespeicherte Cookies. Mehrere Cookies sind durch Semikolons getrennt. -b setzt auch den Cookie-Header — äquivalent zu -H 'Cookie: ...'. Curl parst Set-Cookie standardmäßig nicht; -b mit -c paaren, um neue Cookies zu persistieren.

curl
# send a single cookie
curl -b "session=abc123" https://example.com/dashboard

# send multiple cookies
curl -b "session=abc123; theme=dark; lang=en" \
     https://example.com/dashboard

# send cookies from a file (Netscape format)
curl -b cookies.txt https://example.com/dashboard

# send a cookie with attributes (path, domain)
curl -b "session=abc123; Path=/; Domain=.example.com" \
     https://example.com/

# cookie via header (manual)
curl -H "Cookie: session=abc123; theme=dark" \
     https://example.com/dashboard

Cookies speichern (-c)

-c (--cookie-jar) schreibt Set-Cookie-Response-Header in eine Datei im Netscape-Format. -b (lesen) mit -c (schreiben) auf dieselbe Datei paaren, um eine Session über Anfragen zu halten: einmal einloggen, dann den Cookie-Jar für authentifizierte Aufrufe wiederverwenden. -c - gibt zum Inspektieren auf stdout aus.

curl
# save response cookies to a file
curl -c cookies.txt https://example.com/login

# send and save cookies in one request
curl -b cookies.txt -c cookies.txt https://example.com/dashboard

# dump cookies to stdout (Netscape format)
curl -c - https://example.com/

# inspect cookies with --dump-header
curl -D headers.txt https://example.com/
grep -i set-cookie headers.txt

# login then reuse the session cookie
curl -c cookies.txt -d "user=alice&pass=secret" \
     https://example.com/login
curl -b cookies.txt https://example.com/dashboard

Cookie Jar

Ein cookie jar (Netscape-Format) persistiert Cookies zwischen curl-Aufrufen und simuliert eine Browser-Session. Dieselbe Jar-Datei für -b und -c verwenden, damit Cookies bei jeder Anfrage aktualisiert werden. Das Format ist tab-getrennt: domain, include-subdomain-Flag, path, secure-Flag, Ablauf (unix time), name, value. Jar löschen, um sich auszuloggen.

curl
# Netscape cookie file format:
# domain  flag  path  secure  expiration  name  value
# .example.com  TRUE  /  FALSE  1735689600  session  abc123

# full session: login, then call API with the same jar
JAR=/tmp/cookies.txt
curl -s -c "$JAR" -d "user=alice&pass=secret" https://example.com/login
curl -s -b "$JAR" https://example.com/api/profile
curl -s -b "$JAR" https://example.com/api/settings

# update the jar on every request (refresh expiring cookies)
curl -b "$JAR" -c "$JAR" https://example.com/api/data

# expire all cookies by deleting the jar
rm "$JAR"

# view the jar contents
cat "$JAR"
# or human-readable
curl -b "$JAR" -c - -o /dev/null https://example.com/

Cookie aus String

Für Einmal-Anfragen ist -b mit einem String einfacher als ein Jar. Cookies sind durch Semikolons getrennt; Werte mit Sonderzeichen sollten URL-kodiert sein. Der Cookie-Header (via -H) ist äquivalent und erlaubt, den Cookie-String eines Browsers wörtlich einzufügen — nützlich, um eine aufgenommene Session zu wiederholen.

curl
# one-off cookie (no file)
curl -b "session=abc123" https://example.com/

# multiple cookies in one string
curl -b "session=abc123; theme=dark; lang=en" https://example.com/

# build cookie string from variables
SID="abc123"; THEME="dark"
curl -b "session=$SID; theme=$THEME" https://example.com/

# encode a value containing special chars
curl -b "data=$(python3 -c 'import urllib.parse;print(urllib.parse.quote("a&b"))')" \
     https://example.com/

# emulate a browser cookie header exactly
curl -H "Cookie: __cfduid=abc; _ga=GA1.2.xxx; session=xyz" \
     https://example.com/

Session-Management

Web-Logins brauchen oft ein CSRF-Token von der Login-Seite plus Cookie-Persistenz. Das Muster: Formular per GET holen (Cookies speichern), Token extrahieren, Credentials per POST senden (mit Cookies + Token), dann den Jar für authentifizierte Aufrufe wiederverwenden. Jede Anfrage aktualisiert den Jar (-c), sodass erneuerte Session-Cookies weitergereicht werden. Am Ende immer ausloggen und den Jar löschen.

curl
# full login flow with cookie persistence
JAR=/tmp/session.txt

# 1. GET login page (capture CSRF token + cookies)
curl -s -c "$JAR" https://example.com/login > login.html
CSRF=$(grep csrf_token login.html | head -1 | grep -oP 'value="\K[^"]+')

# 2. POST credentials with CSRF and cookies
curl -s -b "$JAR" -c "$JAR" \
     -d "user=alice&pass=secret&csrf=$CSRF" \
     https://example.com/login

# 3. Access protected resources with the session
curl -s -b "$JAR" https://example.com/dashboard
curl -s -b "$JAR" https://example.com/api/data

# 4. Logout (invalidate session)
curl -s -b "$JAR" -c "$JAR" https://example.com/logout
rm "$JAR"
09

Proxy

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.

curl
# 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 proxy

SOCKS-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.

curl
# 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.com

Proxy-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.

curl
# 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.com

No 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.

curl
# 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.

curl
# 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.com
10

SSL/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.

curl
# 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.

curl
# 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.com

TLS-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'.

curl
# 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.

curl
# 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.com

Zertifikats-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.

curl
# 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 cert
11

Downloads

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.

curl
# 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/webhook

Downloads 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.

curl
# 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.iso

Fortschrittsbalken

--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.

curl
# 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.zip

Download-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.

curl
# 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 HTTP

Mehrere 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).

curl
# 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 -O

Mirror & 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
# 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 -O
12

Timeouts & 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.

curl
# 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.com

Max 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.

curl
# 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.

curl
# 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.iso

Retry-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.

curl
# 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.com

Speed-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.

curl
# 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.iso
13

Debugging

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.

curl
# 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.com

Trace

--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.

curl
# 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 | head

Nur 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.

curl
# 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 -1

Trennung 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.

curl
# 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.com

Debug-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.

curl
# 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].zip
14

Antwort-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.

curl
# 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/abc

Write-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.

curl
# 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.com

Antwortzeit

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).

curl
# 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.com

Header 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.

curl
# 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/abc

Format-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.

curl
# 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 | jq
15

FTP & 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.

curl
# 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:pass

FTP-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.

curl
# 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:pass

FTP-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.

curl
# 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.

curl
# 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.txt

IMAP & 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.

curl
# 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.

curl
# 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/
16

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.

curl
# 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; wait

xargs 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.

curl
# 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>&1

URL-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).

curl
# 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.

curl
# 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; }
done

GNU 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.

curl
# 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.txt
17

Konfigurationsdateien

.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.

curl
# ~/.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 above

Ort 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.

curl
# 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 config

Config 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.

curl
# 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.com

Hä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.

curl
# ~/.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.

curl
# 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.com
18

Fortgeschrittene 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
# 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.

curl
# 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.com

Bedingte 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.

curl
# 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/data

Interface & 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.

curl
# 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.com

Range-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.

curl
# 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 HTTP

Exit-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.

curl
# 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.com

Was this helpful?