curl для начинающих: ваш первый шаг в мир HTTP-запросов

curl — утилита командной строки для передачи данных по URL. Она отправляет запрос серверу и показывает ответ: HTML-страницу, JSON от API, заголовки или файл. Название расшифровывается как Client URL. Кроме HTTP и HTTPS, curl работает с FTP, SFTP, SMTP, IMAP и другими протоколами.

curl есть почти в любой системе Linux и macOS, а в Windows 10 и 11 входит в поставку. Его используют, чтобы:

• проверять API и веб-сервисы без браузера;
• скачивать файлы в скриптах;
• проверять доступность сайта, редиректы и сертификат;
• выяснять, где теряется время при загрузке страницы;
• отправлять тестовые письма через SMTP.

Первый запрос

Без параметров curl выполняет GET-запрос и выводит тело ответа в терминал:

curl https://example.com

Основные флаги

Описания — по официальному руководству curl.

Флаг -k отключает проверку TLS-сертификата, и соединение перестаёт быть защищённым от подмены. Он допустим только для диагностики на своём стенде, в скриптах и рабочих настройках ему не место.

Сочетание -sS удобно в скриптах: прогресс не засоряет вывод, а ошибки видны. Для скачивания в скрипте обычно пишут curl -fsSL: без прогресса, с сообщением об ошибке, с переходом по редиректам и с ненулевым кодом выхода, если сервер ответил ошибкой.

Заголовки и редиректы

Посмотреть только заголовки ответа:

curl -I https://example.com

Проверить, куда ведёт цепочка редиректов, и увидеть заголовки каждого ответа:

curl -sIL http://example.com

Подробный вывод с деталями TLS-соединения — первое, что стоит сделать, если запрос ведёт себя странно:

curl -v https://example.com -o /dev/null

Запросы к API

GET-запрос с заголовком авторизации:

curl -s -H "Authorization: Bearer $TOKEN" https://api.example.com/v1/items

POST с данными формы:

curl -d "name=mike&age=30" https://api.example.com/register

Если указан -d, метод POST выбирается автоматически, -X POST добавлять не нужно.

POST с JSON:

curl --json '{"name": "mike", "age": 30}' https://api.example.com/users

В старых версиях curl, где --json ещё нет, то же самое записывается так:

curl -H "Content-Type: application/json" -d '{"name": "mike", "age": 30}' https://api.example.com/users

PUT и DELETE:

curl -X PUT --json '{"age": 31}' https://api.example.com/users/42
curl -X DELETE https://api.example.com/users/42

Базовая аутентификация:

curl -u admin:пароль https://example.com/admin/

Если указать только логин (-u admin), curl запросит пароль интерактивно, и он не останется в истории команд.

Скачивание и загрузка файлов

# сохранить с именем из URL
curl -O https://example.com/file.zip

# сохранить под своим именем
curl -o backup.zip https://example.com/file.zip

# отправить файл через форму (multipart/form-data)
curl -F "file=@report.pdf" https://example.com/upload

# загрузить файл методом PUT
curl -T report.pdf https://example.com/files/report.pdf

Сколько времени занимает запрос

Флаг -w выводит служебные переменные после выполнения запроса. Так можно понять, на каком этапе теряется время:

curl -o /dev/null -s -w "DNS: %{time_namelookup}\nTCP: %{time_connect}\nTLS: %{time_appconnect}\nПервый байт: %{time_starttransfer}\nВсего: %{time_total}\nКод: %{http_code}\n" https://example.com

Все значения — в секундах от начала запроса. Если велико время DNS, проблема в резолвере; если велико время до первого байта при быстром соединении, долго отвечает само приложение. Подробнее о поиске сетевых проблем — в статье «Сетевой траблшутинг: утилиты диагностики».

Код ответа отдельно, например для мониторинга в скрипте:

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

Таймауты, повторы и прокси

# не ждать соединения дольше 5 секунд, а всего запроса — дольше 20
curl --connect-timeout 5 -m 20 https://example.com

# повторить до трёх раз при временных ошибках
curl --retry 3 https://example.com

# запрос через HTTP-прокси или SOCKS5
curl -x http://proxy.example.com:3128 https://example.com
curl -x socks5h://127.0.0.1:1080 https://example.com

Схема socks5h:// означает, что имя сервера разрешает сам прокси, а не ваш компьютер.

Почтовые протоколы

Отправка письма через SMTP

curl --url "smtp://smtp.example.com:587" \
  --ssl-reqd \
  --mail-from "sender@example.com" \
  --mail-rcpt "recipient@example.com" \
  --upload-file email.txt \
  --user "username:password"

• --ssl-reqd — требовать шифрование (STARTTLS);
• --mail-from и --mail-rcpt — отправитель и получатель;
• --upload-file — файл с письмом: заголовки From, To, Subject, пустая строка и текст.

Просмотр папок через IMAP

curl --url "imaps://imap.example.com" \
  --user "username:password" \
  -X 'LIST "" "*"'

Типичные ошибки

• Забытый -L. Сервер отвечает редиректом, а curl показывает пустой ответ или страницу «Moved».
• -k в рабочих скриптах. Скрипт перестаёт замечать подмену сертификата. Правильнее исправить цепочку сертификатов на сервере или указать свой корневой сертификат через --cacert.
• Пароли и токены в командной строке. Они остаются в истории оболочки и видны в списке процессов. Токены лучше передавать через переменные окружения или файл (-H @headers.txt).
• Отсутствие -f в скриптах. Без него ответ 404 или 500 считается успешным запросом, и скрипт продолжит работу с «файлом», в котором на самом деле страница ошибки.

curl удобно дополняет браузерные инструменты разработчика: его команду легко сохранить, повторить и вставить в скрипт или задачу CI.

Как с помощью curl искать причину проблемы — отправить запрос на конкретный сервер в обход DNS, проследить цепочку редиректов, разобрать, на каком этапе теряется время, — описано в статье «Отладка HTTP с curl». Проверка сертификатов и TLS — в «Отладке TLS: curl и openssl s_client».