Skip to content

curl Шпаргалка

Инструмент командной строки для передачи данных по URL.

01

Начало работы

Базовые запросы

curl выполняет HTTP-запросы из командной строки. По умолчанию используется GET. -v показывает подробный вывод, -o сохраняет в указанный файл, -O сохраняет удалённое имя файла, -L следует перенаправлениям, -I запрашивает только заголовки (HEAD-запрос).

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

Вывод и сохранение

-o записывает тело в указанный файл; -O использует удалённое имя файла. --output-dir задаёт каталог назначения. -s (silent) скрывает индикатор прогресса и ошибки — добавьте -S, чтобы ошибки всё же показывались. Используйте -D для дампа заголовков в файл, отбрасывая тело через -o /dev/null.

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

Подробный режим и заголовки

-v (verbose) печатает весь диалог: '>' — запрос, '<' — ответ, '*' — служебная информация curl; всё идёт в stderr, поэтому stdout остаётся чистым для тела. -I отправляет HEAD-запрос и печатает заголовки. -D дампит заголовки в файл или '-' в stdout; в сочетании с -o /dev/null можно изучать заголовки, не сохраняя тело.

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

Следование перенаправлениям

-L следует HTTP-перенаправлениям 3xx; по умолчанию curl проходит до 50 переходов (ограничьте через --max-redirs). RFC 301/302 обычно превращает POST в GET — используйте --post301/--post302, чтобы сохранить метод. По умолчанию учётные данные не отправляются перенаправленным хостам; --location-trusted отправляет их везде (риск безопасности).

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 и globbing

curl раскрывает шаблоны «globbing» в URL: диапазоны [1-10], списки {a,b,c}, с необязательным :step. Каждое раскрытие — отдельный запрос. Используйте -g (--globoff), чтобы трактовать скобки буквально — важно для URL с JSON-массивами или IPv6-адресами вроде 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"

Справка и версия

--version показывает версию curl, поддерживаемые протоколы (HTTP, HTTPS, FTP и др.) и скомпилированные возможности (HTTP2, SSL, brotli). --help all перечисляет все опции — удобно, когда помните лишь часть имени флага. Возможности зависят от сборки curl (например, HTTP/3 нужна специальная сборка).

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-методы

GET-запросы

GET — метод по умолчанию. Всегда берите URL с & или ? в кавычки, чтобы оболочка не отправила его в фон и не раскрыла. -X явно задаёт метод, но для GET обычно не нужен. Для API задайте Accept для согласования формата ответа.

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-запросы

Отправка -d автоматически переключает метод на POST, поэтому -X POST избыточен (но безвреден и проясняет намерение). Чтобы отправить POST-ом файл, используйте -d @filename (@ читает файл). Content-Type по умолчанию для -d — application/x-www-form-urlencoded; переопределите через -H для JSON.

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 заменяет ресурс целиком; PATCH применяет частичное обновление. Оба требуют -X, потому что у curl нет для них -d-сокращения. -T (upload-file) передаёт файл как тело запроса и идеален для PUT-загрузок. Используйте --data-binary вместо -d, чтобы не терять переводы строк при отправке сырых файлов.

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 удаляет ресурс. Большинство API требуют аутентификации, поэтому добавьте -u или заголовок Authorization. Некоторые API принимают тело (причина, флаги каскада) — добавьте -d и заголовок Content-Type. Используйте -w '%{http_code}' для проверки результата: 204 (No Content) и 200 — типичные успешные ответы.

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 отправляет HEAD-запрос (только заголовки, без тела) — полезно проверить размер (Content-Length), тип (Content-Type) и дату изменения, ничего не скачивая. OPTIONS раскрывает разрешённые методы (заголовок Allow) и используется браузерами для CORS-preflight. Добавьте заголовки Origin и Access-Control-Request-Method, чтобы сымитировать настоящий preflight.

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

Заголовки

Установка заголовков (-H)

-H (--header) добавляет заголовок запроса. Повторяйте -H для нескольких заголовков. Завершающая точка с запятой (X-Empty;) отправляет пустое значение. @headers.txt читает заголовки из файла (по строке «Name: value») — удобно держать токены Authorization вне истории команд.

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

Частые заголовки

Самые частые заголовки: Accept сообщает серверу нужный формат; Content-Type описывает тело запроса; Authorization несёт учётные данные. --compressed просит curl запросить сжатые ответы (gzip, br) и автоматически их распаковать, поэтому кодировку не нужно обрабатывать вручную.

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

Некоторые серверы блокируют User-Agent по умолчанию. -A (--user-agent) задаёт его; пустой -A убирает полностью. Длинная форма — -H 'User-Agent: ...'. Многие сайты со защитой от скрейпинга проверяют подписи реальных браузеров, поэтому часто нужен реалистичный UA браузера.

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) задаёт заголовок Referer. Переопределение Host необходимо при тестировании виртуальных хостов по IP: сервер выбирает сайт по Host. CORS-эндпоинты часто требуют Origin; X-Forwarded-For/Proto имитируют запросы за прокси или балансировщиком.

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

Удаление заголовков

-H 'Header-Name:' (с двоеточием, но без значения) говорит curl не отправлять значение этого заголовка — фактически удаляя заголовок по умолчанию, например User-Agent или Accept-Encoding. Повторное указание того же имени заменяет заголовок, а не дублирует его. Полезно для отправки минимального запроса.

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-данные и формы

Данные формы (-d)

-d (--data) отправляет URL-кодированные данные формы и переключает метод на POST. Несколько -d объединяются через &. -d обрезает пробелы и переводы строк по краям; --data-binary сохраняет их; --data-raw полностью отключает функцию @file (литеральное значение, начинающееся с @, отправляется как есть).

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-кодирование

--data-urlencode выполняет percent-кодирование значения (или всего name=value), поэтому не нужно вручную кодировать пробелы, &, = и не-ASCII. С name@file содержимое файла URL-кодируется как значение. Всегда применяйте это для пользовательских данных, чтобы не ломать структуру формы.

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

Бинарные данные

--data-binary отправляет файл байт в байт (сохраняя переводы строк и нулевые байты), в отличие от -d, который их обрезает. -T передаёт файл потоком, поэтому память не растёт даже при больших загрузках. Чтобы отправить заранее сжатые данные, передайте по пайпу с -H 'Content-Encoding: gzip' — сервер должен это поддерживать; иначе используйте 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

Чтение из файла (@file)

-d @file читает тело запроса из файла (@ включает чтение файла). --data-binary @file сохраняет байты как есть. -d @- читает из stdin — идеально для пайпов с jq, curl или другими преобразованиями. Если литеральное значение начинается с @ и раскрытие файла не нужно, используйте --data-raw.

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 и формы

Всегда согласуйте Content-Type с форматом тела: application/x-www-form-urlencoded (по умолчанию для -d), application/json (с -H), multipart/form-data (автоматически для -F), text/xml для SOAP. Добавление charset=utf-8 — хорошая практика для не-ASCII данных. Несовпадение заставляет серверы отклонять или неверно разбирать тело.

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-запросы

Базовый JSON POST

JSON-запросам нужен -H 'Content-Type: application/json' плюс -d со JSON-строкой. Возьмите JSON в одинарные кавычки, чтобы оболочка не трогала двойные внутри. Пропустите ответ через jq '.' для читаемого вывода или jq '.field' для извлечения конкретного значения.

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 из файла

Для сложного JSON сохраните его в .json-файл и используйте -d @file (или --data-binary @file, чтобы сохранить байты точно, включая переводы строк в конце). Пайп с jq -n позволяет строить JSON программно без возни с экранированием. Сначала всегда проверяйте через jq . — синтаксическая ошибка тратит запрос впустую.

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 с переменными

Подстановка переменных в JSON-строки ломается на кавычках и спецсимволах. Безопасный паттерн — jq --arg/--argjson: он строит валидный JSON и корректно экранирует значения. --arg для строк, --argjson для чисел/булевых. Для секретов предпочтительнее файл заголовков (-H @file) вместо аргументов командной строки, чтобы не утечь через ps.

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-запросы

GraphQL использует один POST-эндпоинт с JSON-телом, содержащим строку 'query' и необязательные 'variables'. Встроенный запрос требует экранирования внутренних двойных кавычек, поэтому храните сложные запросы в .json-файле и используйте -d @file. Интроспекция (запрос __schema) перечисляет типы API и отлично подходит для исследования.

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

Согласование контента

Accept согласовывает формат ответа; многие REST API по умолчанию возвращают JSON, но поддерживают альтернативы XML или CSV. --compressed запрашивает gzip/brotli и распаковывает автоматически. API часто версионируются через Accept (например, GitHub: application/vnd.github+json). Проверяйте фактический Content-Type ответа сервера, чтобы убедиться, что согласование сработало.

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

Загрузка файлов

Multipart-загрузка (-F)

-F (--form) строит multipart/form-data-запрос — стандарт для загрузки файлов. -F file=@path читает файл. Добавьте ;filename=, чтобы переопределить имя, которое видит сервер, и ;type= для Content-Type части. Несколько файлов в одном имени поля (с [] во многих фреймворках) требуют нескольких -F.

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

Несколько файлов и полей

Multipart-формы могут смешивать файлы и текстовые поля. Используйте [] в именах полей для загрузок в виде массива (фреймворки вроде Rails/PHP разбирают их в массивы). Поле может нести JSON, если задать ;type=application/json — сервер прочитает его как структурированные данные, а не файл. curl не умеет загружать каталоги нативно — сначала упакуйте в tar.

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

Потоковая загрузка (-T)

-T (--upload-file) использует PUT и передаёт файл потоком, поэтому память остаётся плоской даже при огромных загрузках — намного лучше -d @file для больших данных. -T - читает из stdin. -C - возобновляет прерванную передачу. Со слэшем в конце URL curl добавляет локальное имя файла (подобно HTTP PUT-зеркалированию).

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

Загрузка с прогрессом

По умолчанию curl показывает индикатор прогресса в stderr. --progress-bar переключает на более простой бар. -s (silent) прячет его; добавьте S (-sS), чтобы ошибки показывались. Информация о прогрессе идёт в stderr, поэтому stdout (тело) остаётся чистым — удобно при пайпах. Используйте -w с %{size_upload} и %{time_total} для однострочной сводки.

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

Поля и типы загрузки

curl угадывает MIME-тип по расширению файла. Переопределите через ;type=. Опция ;filename= меняет то, что видит сервер, — полезно для обезличенных имён. Префикс < читает содержимое файла в текстовое поле (вместо отправки файлом) — помогает, когда API ожидает строку, а данные у вас в файле.

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

Аутентификация

Basic-аутентификация (-u)

-u (--user) отправляет HTTP Basic (base64-кодированные user:pass). Опустите пароль, чтобы его запросили интерактивно (безопаснее — не попадает в историю команд). --netrc читает учётные данные из ~/.netrc, чтобы они никогда не появлялись в командной строке. Basic небезопасен по обычному HTTP; всегда используйте HTTPS. Любой с доступом к shell видит аргументы -u через ps.

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-токен

Bearer-токены (OAuth2, JWT) идут в заголовке Authorization. Не кладите токены в командную строку — ps открывает их другим пользователям. Читайте из файла (-H @file) или переменной окружения, а для чувствительных значений используйте файл заголовков. Сниппет refresh-token показывает стандартный поток client credentials OAuth2.

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-ключ в заголовке

API-ключи передаются в кастомных заголовках (X-API-Key, X-Client-Id) или как query-параметры. Query-строки утекают в логи сервера и историю браузера, поэтому предпочитайте заголовки. Для AWS --aws-sigv4 подписывает запрос вашими access/secret-ключами. GitHub использует Bearer с персональным токеном доступа (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

--netrc читает учётные данные из ~/.netrc, сопоставляя хосты с парами логин/пароль. Файл должен иметь chmod 600, иначе curl откажется его использовать. --netrc-file указывает на произвольное расположение. Запись 'default' применяется к любому хосту без конкретной machine-записи. Это самый чистый способ держать секреты вне командной строки.

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 передаёт учётные данные открытым текстом (по HTTPS это нормально). Digest отправляет хеш, никогда не пароль. NTLM и Negotiate обслуживают SSO Windows/Kerberos. --anyauth позволяет curl выбрать схему по заголовку WWW-Authenticate сервера. Сервер должен поддерживать метод; -v показывает, какие испытания он выдаёт.

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 и токены

У OAuth2 несколько типов выдачи: client_credentials (сервер-сервер), authorization_code (после входа в браузере), password (устаревший). Токен-эндпоинт возвращает access_token (и часто refresh_token); используйте access_token как Bearer-заголовок для последующих запросов. Пароли приложений (GitLab, GitHub) работают с -u и обходят ограничения 2FA.

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

Куки

Отправка куки (-b)

-b (--cookie) отправляет куки. Строка отправляется как есть; имя файла (формат Netscape) загружает сохранённые куки. Несколько куки разделяются точкой с запятой. -b также задаёт заголовок Cookie — эквивалент -H 'Cookie: ...'. curl по умолчанию не разбирает Set-Cookie; объединяйте -b с -c, чтобы сохранять новые куки.

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

Сохранение куки (-c)

-c (--cookie-jar) записывает заголовки ответа Set-Cookie в файл в формате Netscape. Объедините -b (чтение) с -c (запись) на одном файле, чтобы поддерживать сессию между запросами: войдите один раз, затем переиспользуйте cookie-jar для авторизованных вызовов. -c - дампит в stdout для осмотра.

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

Cookie jar (формат Netscape) сохраняет куки между вызовами curl, имитируя сессию браузера. Используйте один jar-файл для -b и -c, чтобы куки обновлялись в каждом запросе. Формат с табуляцией: домен, флаг включения поддоменов, путь, флаг secure, срок действия (unix-время), имя, значение. Удалите jar, чтобы выйти.

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/

Куки из строки

Для разовых запросов -b со строкой проще jar-файла. Куки разделяются точкой с запятой; значения со спецсимволами нужно URL-кодировать. Заголовок Cookie (через -H) эквивалентен и позволяет вставить куку-строку браузера дословно — удобно для воспроизведения захваченной сессии.

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/

Управление сессией

Веб-вход часто требует CSRF-токен со страницы входа плюс сохранение куки. Паттерн: GET формы (сохраняя куки), извлечь токен, POST учётных данных (с куками и токеном), затем переиспользовать jar для авторизованных вызовов. Каждый запрос обновляет jar (-c), поэтому обновлённые куки сессии распространяются. По завершении всегда выходите и удаляйте jar.

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

Прокси

HTTP/HTTPS-прокси

-x (--proxy) направляет запрос через прокси. Переменные окружения http_proxy/https_proxy/no_proxy учитываются автоматически. Для HTTPS-целей через HTTP-прокси curl использует CONNECT для туннелирования. Задайте no_proxy, чтобы обходить прокси для внутренних хостов — через запятую, ведущая точка означает поддомены.

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-прокси

SOCKS5 не зависит от протокола, поэтому туннелирует HTTP, HTTPS и другое. --socks5-hostname поручает прокси разрешать DNS (полезно для хостов, которые ваша машина не резолвит). Частый трюк: ssh -D 1080 создаёт локальный SOCKS-прокси, туннелирующий трафик через удалённый SSH-сервер — отлично для безопасного сёрфинга в недоверенных сетях.

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

Аутентификация прокси

Прокси часто требуют аутентификацию. -U (--proxy-user) передаёт учётные данные; --proxy-ntlm/--proxy-digest/--proxy-anyauth выбирают схему. Встраивание user:pass в URL -x эквивалентно. Для NTLM (корпоративные прокси Windows) --proxy-ntlm обрабатывает многошаговое рукопожатие. -U user (без пароля) запрашивает интерактивно.

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 и обход

--noproxy (или переменная no_proxy) перечисляет хосты, обходящие прокси. Ведущая точка означает «этот домен и все поддомены». '*' обходит прокси для всего. Диапазоны CIDR работают в свежих curl. Это существенно, когда внешний прокси не может достучаться до внутренних корпоративных хостов.

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 добавляет заголовки, предназначенные самому прокси (например, Proxy-Authorization), а не пересылаемые цели. -p (--proxytunnel) заставляет curl использовать CONNECT даже для обычного HTTP (обычно CONNECT применяется только для HTTPS). Полезно, когда прокси перехватывает обычный HTTP, а нужен сквозной туннель.

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

Пропуск проверки (--insecure)

-k (--insecure) пропускает проверку сертификата — только для self-signed сертификатов разработки, никогда в продакшене, так как допускает MITM-атаки. По умолчанию проверяются и цепочка сертификатов, и имя хоста. --resolve позволяет закрепить IP при сохранении корректных Host/SNI — полезно для тестирования конкретного бэкенда за балансировщиком.

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"

Клиентские сертификаты

Взаимный TLS (mTLS) требует и клиентский сертификат (--cert), и его приватный ключ (--key). PEM по умолчанию; --cert-type P12 обслуживает связки PKCS#12. --pass передаёт пароль ключа. --cacert переопределяет список доверенных CA (по умолчанию системное хранилище) — полезно для внутренних CA. mTLS обычен в zero-trust и service mesh.

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

--tlsv1.X задаёт минимальную версию; --tls-max ограничивает сверху. Принуждение 1.2+ отключает устаревшие протоколы (SSLv3, TLS 1.0/1.1) с известными слабостями. По умолчанию согласовывается наивысшая взаимно поддерживаемая версия. -v раскрывает согласованную версию и шифр в строке «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"

Шифры и CA-набор

--ciphers ограничивает набор шифров (синтаксис OpenSSL). --cacert указывает на кастомный CA-набор для проверки серверов с внутренними/приватными CA — по умолчанию используется системный (/etc/ssl/certs или связка macOS). Если CA-набор устарел, серверы с валидными сертификатами могут отклоняться; обновление curl (или пакета ca-certificates) это исправляет.

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

Осмотр сертификата

Используйте -v для осмотра сертификата сервера (subject, issuer, сроки действия). --pinnedpubkey принуждает закрепление сертификата — запрос падает, если публичный ключ сервера не совпадает, нейтрализуя подставные CA. Для глубокой отладки TLS --trace-ascii дампит всё рукопожатие. openssl s_client — более мощная альтернатива для осмотра сертификатов.

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

Скачивание

Сохранение в файл (-o/-O)

-o записывает в выбранное имя файла; -O использует удалённое имя (базовое имя из URL). --output-dir задаёт папку назначения для -O. Несколько -O скачивают несколько файлов за один вызов. -o /dev/null отбрасывает тело — полезно для триггеринга вебхуков или замера времени без сохранения данных.

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

Продолжение загрузки (-C)

-C - (--continue-at -) продолжает загрузку с места обрыва, используя размер существующего файла как байтовое смещение. Сервер должен поддерживать Range-запросы (проверьте Accept-Ranges: bytes). Сочетайте с --retry для обработки нестабильных соединений — curl повторяет и возобновляет, избегая потерь трафика.

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

Индикатор прогресса

--progress-bar показывает более простой бар ### вместо метра по умолчанию. -s гасит весь прогресс; -sS сохраняет ошибки. Прогресс идёт в stderr, поэтому не загрязняет тело в stdout — можно захватывать оба по отдельности. -w с %{size_download} и %{time_total} даёт чистую однострочную сводку для скриптов.

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

Диапазон загрузки

-r (--range) запрашивает байтовый диапазон, возвращая 206 Partial Content. Полезно для превью больших файлов, возобновления или параллельных многопоточных загрузок. Сервер должен объявить Accept-Ranges: bytes. В сочетании с фоновыми задачами shell (&) скачивайте диапазоны параллельно, затем склейте — основа ускорителей загрузки вроде 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

Несколько файлов и globbing

Globbing URL ([1-3], {a,b,c}) выдаёт один запрос на каждое раскрытие. --output-dir задаёт, куда -O их сохранит. Для настоящего параллелизма (curl сам последователен) передавайте URL в xargs -P N, чтобы запустить N curl одновременно. Это резко ускоряет скачивание множества мелких файлов с одного хоста (уважайте лимиты сервера).

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

Зеркалирование и обход

curl спроектирован для одного URL — он не обходит дерево. Для зеркалирования сайта используйте wget --mirror или извлекайте ссылки скриптом с grep. Для пакетных загрузок перечислите URL в файле и скормите xargs -P N для параллелизма. Пример с sitemap загружает и скачивает каждую страницу индекса сайта — удобно для офлайн-снимков.

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

Таймауты и повторные попытки

Таймаут соединения

--connect-timeout ограничивает время установления TCP/TLS-соединения (но не передачи). Без него curl может висеть минуты на недостижимых хостах (умолчание ОС ~2 минуты). Всегда задавайте в скриптах и --connect-timeout (быстрый провал на мёртвых хостах), и --max-time (потолок всей операции), чтобы избежать зависаний.

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 (-m) ограничивает всю операцию (DNS + соединение + передача). --speed-time/--speed-limit прерывают передачу, если скорость падает ниже лимита на время — идеально для застрявших загрузок. Код выхода 28 означает таймаут; проверяйте $? в скриптах. Всегда задавайте max-time, чтобы предотвратить бесконечные зависания на медленных или залипших серверах.

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: $?"

Повторные попытки

--retry повторяет при переходных ошибках (таймауты, 5xx, 429) по умолчанию; --retry-all-errors распространяет на все отказы. --retry-delay добавляет фиксированное ожидание (удваивается на каждой попытке) между повторами. --retry-connrefused повторяет даже при отказе соединения (например, сервер перезапускается). Сочетайте с -C - для возобновления частичных загрузок. Это необходимо устойчивым скриптам.

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

Задержка и backoff

--retry-delay N ждёт N секунд перед первым повтором, затем удваивает (N, 2N, 4N...). curl уважает заголовок Retry-After сервера для ответов 429/503. Для собственной логики (jitter, предельный итог, условие по статусу) оберните curl в цикл shell. Всегда сочетайте --retry с --max-time, чтобы повторы не длились вечно.

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-time/--speed-limit прерывают застрявшую передачу (нет данных N секунд при скорости ниже лимита) — код выхода 28. --limit-rate ограничивает скорость (суффиксы K/M/G), полезно, чтобы не забивать канал или эмулировать медленную сеть. Сочетайте с --retry для автоматического возобновления прерванных загрузок.

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

Отладка

Подробный режим (-v)

-v (verbose) — главный инструмент отладки. Строки '>' — запрос, '<' — ответ, '*' — внутренности curl (DNS, TLS, соединение) — всё в stderr, поэтому stdout остаётся чистым для тела. Перенаправьте 2>&1 и фильтруйте через grep. Используйте -o /dev/null, чтобы осмотреть заголовки, не сохраняя тело.

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 дампит всё (включая тело) в hex + ASCII; --trace-ascii пропускает hex. --trace-time добавляет метки времени. В отличие от -v, trace показывает тела запроса и ответа, поэтому это выбор для отладки бинарных или сжатых данных. Предупреждение: --trace логирует секреты (пароли, токены) — чистите перед обменом.

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

Только заголовки

-I отправляет HEAD-запрос (большинство серверов возвращает те же заголовки, что и GET, без тела). -D дампит заголовки в файл или '-' (stdout). Чтобы увидеть, что curl отправил (заголовки запроса), используйте -v и grep '^>'. Только для статус-кода чище всего -w '%{http_code}'. Учтите: некоторые серверы отвечают на HEAD иначе, чем на 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

Разделение запроса и ответа

Подробный вывод идёт в stderr, тело — в stdout, поэтому их можно захватывать раздельно перенаправлением. -D сохраняет заголовки ответа; -o — тело; -v (stderr) захватывает весь диалог. Это разделение существенно при отладке API: осматривайте заголовки и тело независимо, логируйте тайминги, сравнивайте запрос с ответом.

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

Опции отладки

--dry-run печатает, что curl собирался сделать, не отправляя — отлично для проверки globbing URL и конфигурации. --resolve закрепляет хост за IP, обходя DNS (необходимо для тестирования конкретного бэкенда). --interface привязывается к сетевой карте или IP. --no-keepalive принуждает свежее соединение на каждый запрос — полезно воспроизводить баги уровня соединения.

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

Информация об ответе

HTTP-статус

-w '%{http_code}' извлекает только статус-код для скриптов. -f (--fail) заставляет curl выходить с ненулевым кодом при 4xx/5xx (без него curl возвращает 0 даже для 404). --fail-with-body дополнительно печатает тело ответа при ошибке (полезнее для отладки). Используйте статус-код для ветвления в скриптах: 2xx успех, 3xx перенаправление, 4xx ошибка клиента, 5xx ошибка сервера.

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

-w (--write-out) форматирует информацию о передаче через плейсхолдеры %{variable}. Тайминги (time_namelookup, time_connect, time_appconnect, time_total) раскладывают, куда уходит время — необходимо для анализа производительности. %{json} выводит все переменные как JSON (curl 7.70+). Сохраните формат в файл и используйте -w @file для повторного применения.

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

Время ответа

Переменные тайминга раскладывают запрос: time_namelookup (DNS), time_connect (TCP), time_appconnect (TLS), time_starttransfer (TTFB — первый полученный байт), time_total (вся передача). TTFB — ключевая метрика задержки API. Сравнивайте тайминги между эндпоинтами, чтобы выявить узкие места (DNS, сеть, TLS или обработка на сервере).

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

Извлечение заголовков

-D - дампит заголовки ответа в stdout; пропустите через grep, чтобы извлечь конкретный заголовок. -I (HEAD) тоже работает, но может отличаться от GET. -w даёт %{url_effective} (итоговый URL после перенаправлений), %{remote_ip} (IP сервера) и %{num_redirects}. Неоценимо для отладки маршрутизации CDN, перенаправлений и идентификации сервера.

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

Переменные формата

-w (--write-out) поддерживает десятки переменных (запустите 'curl -w "%{json}"', чтобы увидеть все как JSON). Переменные тайминга — фундамент мониторинга производительности; переменные размера отслеживают трафик; url_effective и num_redirects отлаживают маршрутизацию. %{json} (curl 7.70+) — самый простой способ захватить всё для логов или дашбордов.

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

curl поддерживает FTP и для скачивания (GET), и для загрузки (PUT через -T). -u передаёт учётные данные; анонимный FTP использует 'anonymous' + email. FTPS (--ftp-ssl) шифрует управляющий канал. Пассивный режим (по умолчанию) работает через NAT/файрволы; используйте --ftp-port для активного режима, если сервер требует.

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

-T загружает файл командой FTP STOR. --ftp-create-dirs создаёт родительские каталоги через MKD. --append использует APPE, чтобы дописывать в существующий файл. -C - возобновляет прерванную загрузку. Globbing ({a,b}) загружает несколько файлов за один вызов. Для каталогов сначала tar — FTP не может загружать папки напрямую.

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

URL FTP, оканчивающийся на /, показывает содержимое каталога. --list-only возвращает только имена файлов. -v показывает underlying FTP-команды (USER, PASS, PASV, LIST, RETR) — неоценимо для отладки проблем прав или файрвола. curl не обходит подкаталоги рекурсивно; используйте wget --mirror или скрипт для рекурсивного скачивания по FTP.

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

curl может отправлять почту по SMTP. Тело (с заголовками) — в файле, переданном через -T. --mail-from и --mail-rcpt задают конверт (отдельно от заголовков To/From в теле). --ssl-reqd принуждает STARTTLS (порт 587); smtps:// использует неявный TLS (порт 465). Аутентификация через -u (LOGIN/PLAIN). Отлично для скриптовых оповещений с серверов без почтового клиента.

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 может читать почту по IMAP и POP3. Синтаксис URL включает папку, UID и селекторы секций. IMAP поддерживает поиск (?UNSEEN, ?SUBJECT и др.). imaps:// и pop3s:// используют неявный TLS. Учтите: curl в отношении почты только читает — получить может, но отправить через IMAP/POP3 нет (для отправки — SMTP). Тело возвращается как сырой текст сообщения RFC 822.

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 три шифрованных варианта: FTPS явный (--ftp-ssl, апгрейд на порту 21), FTPS неявный (ftps://, TLS с самого начала на порту 990) и SFTP (sftp://, совершенно другой протокол поверх SSH на порту 22). SFTP поддерживает ключ-аутентификацию через --key (с --pass для шифрованных ключей). Сегодня SFTP обычно предпочитают FTPS за простоту и дружелюбие к файрволам.

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

Параллельность и пакеты

Параллельные загрузки

curl сам по себе последователен — для параллельного скачивания запускайте несколько curl параллельно через & и wait, или используйте xargs -P N, чтобы запустить N одновременно. Это резко ускоряет множество мелких файлов. Будьте вежливы: слишком много параллельных соединений могут перегрузить сервер или привести к rate-limit. 4-8 параллельных — разумное значение по умолчанию.

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

xargs -P N запускает N процессов параллельно, подавая каждую строку stdin как аргумент. -a читает из файла. -I {} позволяет вставить URL в любое место команды. Это простейший способ распараллелить загрузки curl без дополнительных инструментов. Для учёта хоста при троттлинге или сложной логики повторов используйте выделенный менеджер загрузок вроде aria2c.

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

Globbing URL

Globbing раскрывает URL в несколько запросов: диапазоны [1-10] (с необязательным :step и ведущими нулями для паддинга) и списки {a,b,c}. -o 'file#1.zip' использует #1 как счётчик для кастомных имён вывода. -g (--globoff) отключает раскрытие — необходимо для URL с литеральными [ ] или { } (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"

Последовательный диапазон

Для последовательных загрузок (когда параллелизм перегрузил бы сервер или нарушил лимиты) циклите по URL в bash. Добавьте sleep для вежливости. -sf (silent + fail) заставляет curl выходить с ненулевым кодом при HTTP-ошибках, чтобы цикл мог прерваться раньше. Это безопасный паттерн для скрейпинга или краулинга: будьте деликатны, добавляйте задержки и обрабатывайте ошибки.

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 мощнее xargs: сохраняет порядок вывода, показывает прогресс (--bar) и гибче обрабатывает аргументы. -j N задаёт параллелизм. :::: читает из файла, ::: — из командной строки. parallel идеален для пакетного тестирования API, скрейпинга и бенчмарков, где нужен чистый упорядоченный вывод параллельных запросов.

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

Файлы конфигурации

Основы .curlrc

~/.curlrc хранит опции по умолчанию, применяемые к каждому вызову curl. Используйте длинные имена опций без ведущего --. Одна опция на строку; значения можно брать в кавычки. Это держит частые настройки (таймауты, повторы, User-Agent) единообразными для скриптов и интерактивного использования. Переопределяйте на конкретный запрос, передавая опцию явно в командной строке.

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

Расположение файла конфигурации

curl читает ~/.curlrc (или $CURL_HOME/.curlrc) по умолчанию. -K (--config) указывает на конкретный файл; -K - читает из stdin. -q (--disable) полностью пропускает файл конфигурации — полезно, когда опция по умолчанию ломает конкретный запрос. CURL_HOME перемещает каталог поиска для переносимых настроек.

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

Конфигурация с -K

-K загружает опции из файла — идеально для конфигураций по средам (токены dev и prod, таймауты, заголовки). Хранение секретов в файле конфигурации (chmod 600) держит их вне истории команд и ps. Несколько файлов -K обрабатываются по порядку, поэтому поздние переопределяют ранние — удобно для базовой конфигурации плюс переопределений по среде.

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

Частые значения по умолчанию

Продуманный ~/.curlrc делает каждый вызов curl безопаснее и единообразнее: таймауты предотвращают зависания, повторы обрабатывают переходные сбои, --compressed прозрачно обслуживает gzip, а урезанный User-Agent снижает фингерпринтинг. Строка write-out логирует тайминги и статус каждого запроса — неоценимо для быстрых проверок производительности.

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"

Несколько конфигураций

Разделение конфигурации на слои файлов (base, auth, api, окружение) держит всё модульным и безопасным. Обрабатывайте их несколькими флагами -K по порядку — поздние файлы переопределяют ранние. Секреты храните в файле с правами 600 вне системы контроля версий. Скрипт-обёртка, загружающая стек, позволит вызывать «mycurl» со всеми умолчаниями.

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

Продвинутые техники

Переиспользование соединений

В пределах одного вызова curl TCP-соединение переиспользуется для нескольких URL одного хоста (HTTP keep-alive), экономя накладные расходы TLS-рукопожатия. --no-keepalive отключает это. --max-connects ограничивает параллельные соединения для мульти-URL выборок. Между отдельными вызовами curl переиспользования нет — для этого нужен постоянный клиент вроде httpie или скрипт на Python/Node.

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 мультиплексирует запросы в одном соединении; HTTP/3 использует QUIC поверх UDP, устраняя блокировку начала очереди. --http2 согласовывается через ALPN поверх TLS; --http2-prior-knowledge пропускает согласование (для cleartext h2c). --http3 требует специальной сборки curl. Проверяйте %{http_version}, чтобы подтвердить фактически использованную версию. Большинство современных CDN поддерживают h2 по умолчанию.

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

Условные запросы

Условные запросы экономят трафик: сервер возвращает 304 Not Modified (без тела), если ресурс не изменился. -z (--time-cond) задаёт If-Modified-Since по дате или mtime локального файла. Для кеширования на ETag задайте If-None-Match вручную. If-Unmodified-Since включает оптимистическую конкуренцию — PUT падает, если ресурс изменил кто-то другой.

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

Интерфейс и DNS

--interface привязывается к сетевой карте или IP — полезно на машинах с несколькими интерфейсами. --resolve закрепляет хост за IP, обходя DNS, и отлично подходит для тестирования бэкендов за балансировщиком. --doh-url использует DNS-over-HTTPS (приватность). -4/-6 принуждают семейство IP. Happy Eyeballs (по умолчанию) пробует и IPv4, и IPv6, избегая задержек IPv6-чёрной дыры.

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-запросы и частичные

Range-запросы (-r) получают часть файла, возвращая 206 Partial Content. Сценарии: превью больших файлов, параллельные многопоточные загрузки (разбить на диапазоны, загрузить параллельно, склеить) и возобновление прерванных передач (-C -). Сервер должен объявить Accept-Ranges: bytes. Это основа ускорителей загрузки вроде 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

Коды выхода

Коды выхода curl различают режимы отказа: 6 (DNS), 7 (соединение), 22 (HTTP-ошибка, только с -f), 28 (таймаут), 35 (TLS), 60 (сертификат). Стройте на них устойчивые скрипты с правильными повторами (например, повтор при 28, но быстрый провал при 6). --fail-with-body возвращает тело ответа даже при 4xx/5xx, сильно упрощая отладку ошибок API по сравнению с -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?