Что такое curl и как с ним работать

Терминал с командой curl и ответом сервера на экране ноутбука Программное обеспечение

Утилита командной строки curl отправляет запрос по адресу URL и печатает ответ сервера. Утилита поддерживает больше двадцати протоколов, среди них HTTP и HTTPS, FTP, SMTP и IMAP. Разработчику она нужна для работы с API и тестирования без браузера и Postman: отправить GET или POST, добавить заголовки, передать JSON, посмотреть код ответа.

Все команды ниже мы прогнали против маленького локального API на Python 3.14 на Windows 10: команды bash в Git Bash с curl 8.23.0, команды PowerShell в Windows PowerShell 5.1 со встроенным curl.exe 8.13.0. Вывод скопирован из этого прогона. Таблицу прогресса, которую curl рисует при сохранении в файл, мы не приводим. Опции -C, -F и -x мы не прогоняли: наш сервер не отдаёт файл кусками и не принимает загрузку формой, а прокси в опыте не было.

Что такое curl простыми словами

По сути curl работает клиентом для URL: вы даёте ему адрес и опции, он открывает соединение, отправляет запрос, получает ответ и выводит тело в терминал. Название обыгрывает «Client for URLs», а ещё читается как «see URL». Всю передачу данных выполняет библиотека libcurl, команда curl служит к ней интерфейсом командной строки.

Проект начинался в 1996 году как HttpGet бразильского разработчика Рафаэля Сагулы. Даниэль Стенберг вскоре стал его сопровождающим, после переименований в urlget и curl версия curl 4 вышла 20 марта 1998 года. Сейчас curl и libcurl пишет сообщество, а не один человек.

Где curl пригодится разработчику:

  • проверить свой API, не открывая браузер и не настраивая графический клиент;
  • повторить запрос из браузера: в DevTools Chrome на вкладке Network правый клик по запросу, затем Copy и Copy as cURL (так пункты подписаны в английском интерфейсе);
  • скачать файл с помощью скрипта, например в cron или CI;
  • увидеть сырые заголовки и код ответа, когда фронтенд показывает непонятную ошибку.

Установка curl и проверка версии

В Windows 10 curl встроен начиная со сборки 17063, на нашей машине файл лежит в C:\Windows\System32\curl.exe. В macOS он тоже есть из коробки, свежую версию можно поставить через Homebrew командой brew install curl. В Ubuntu пакет так и называется: sudo apt install curl.

Версию и набор протоколов показывает curl --version (коротко -V). Так выглядит ответ встроенного curl.exe на нашей Windows 10 в PowerShell:

curl.exe -V
curl 8.13.0 (Windows) libcurl/8.13.0 Schannel zlib/1.3.1 WinIDN
Release-Date: 2025-04-02
Protocols: dict file ftp ftps http https imap imaps ipfs ipns mqtt pop3 pop3s smb smbs smtp smtps telnet tftp ws wss
Features: alt-svc AsynchDNS HSTS HTTPS-proxy IDN IPv6 Kerberos Largefile libz NTLM SPNEGO SSL SSPI threadsafe Unicode UnixSockets

В строке Protocols этой сборки нет sftp и scp, а curl 8.23.0 из Git for Windows на той же машине их поддерживает. Версия тоже важна: опция --json появилась в curl 7.82.0, а в Ubuntu 22.04 пакет curl версии 7.81.0. Прежде чем писать скрипт для сервера, посмотрите curl --version на нём.

Учебный API для опытов

Чтобы команды можно было повторить без интернета, поднимем сервер на стандартной библиотеке Python. Адрес /users отдаёт список в формате JSON и принимает новый объект методом POST, /echo возвращает то, что получил от curl (метод, тип содержимого, тело, куки, заголовок авторизации), /login ставит куку, /old делает редирект. Сохраните код в файл server.py:

# server.py: учебный API для опытов с curl, проверен на Python 3.14
import json
from http.server import BaseHTTPRequestHandler, HTTPServer


class Handler(BaseHTTPRequestHandler):
    def send_response(self, code, message=None):
        # без строк Server и Date, чтобы вывод не менялся от запуска к запуску
        self.send_response_only(code, message)

    def answer(self, status, data, extra=None):
        body = json.dumps(data).encode()
        self.send_response(status)
        self.send_header("Content-Type", "application/json")
        self.send_header("Content-Length", str(len(body)))
        for name, value in (extra or {}).items():
            self.send_header(name, value)
        self.end_headers()
        if self.command != "HEAD":
            self.wfile.write(body)

    def do_GET(self):
        size = int(self.headers.get("Content-Length", 0))
        text = self.rfile.read(size).decode()
        if self.path == "/users" and self.command == "POST":
            try:
                self.answer(201, json.loads(text))
            except ValueError:
                self.answer(400, {"error": "bad json", "body": text})
        elif self.path == "/users":
            self.answer(200, {"users": ["Anna", "Boris"]})
        elif self.path == "/echo":
            info = {"method": self.command,
                    "type": self.headers["Content-Type"],
                    "body": text,
                    "cookie": self.headers["Cookie"],
                    "auth": self.headers["Authorization"]}
            self.answer(200, {k: v for k, v in info.items() if v})
        elif self.path == "/login":
            self.answer(200, {"login": "ok"}, {"Set-Cookie": "session=abc123"})
        elif self.path == "/old":
            self.answer(301, {"moved": "/echo"}, {"Location": "/echo"})
        else:
            self.answer(404, {"error": "not found"})

    do_POST = do_HEAD = do_GET


if __name__ == "__main__":
    print("API: http://127.0.0.1:8000", flush=True)
    HTTPServer(("127.0.0.1", 8000), Handler).serve_forever()

Запустите его в первом окне терминала и не закрывайте:

python server.py
API: http://127.0.0.1:8000

Сервер возвращает присланный объект и никуда его не записывает. Команды curl дальше выполняйте во втором окне, в той же папке.

Читайте также:  Vim команды: режимы, перемещение, правка и выход

Два окна терминала: в одном работает локальный сервер, в другом идут запросы

Синтаксис команды curl

Базовый синтаксис: curl [опции] URL. Опции и адреса можно перемешивать в любом порядке. Без опций команда выполняет GET-запрос и печатает тело ответа. Основные опции, которые встретятся дальше:

Опция Что делает
-X METHOD меняет метод запроса, например на PUT или DELETE
-d данные отправляет данные методом POST как форму
--json данные отправляет JSON методом POST и ставит заголовки
-H 'Имя: значение' добавляет заголовок к запросу
-i / -I заголовки ответа с телом / только заголовки (запрос HEAD)
-v подробный вывод: что ушло на сервер и что пришло
-o файл / -O сохранить ответ в файл / в файл с оригинальным именем
-L следовать редиректам
-b, -c отправить куки / сохранить куки в файл
-u user:password Basic-аутентификация
-F поле=@файл загрузить файл формой multipart/form-data
-f, -s, -S ошибка при коде 400 и выше, тихий режим, текст ошибки в тихом режиме
-w формат вывести после ответа код, заголовок, время

Полный список опций печатает команда curl --help all, руководство целиком curl --manual.

GET-запрос и заголовки ответа

Простой GET-запрос:

curl http://127.0.0.1:8000/users
{"users": ["Anna", "Boris"]}

Чтобы увидеть код ответа и заголовки вместе с телом, добавьте -i. Её полное имя --show-headers, до версии 8.10.0 она называлась --include, старое имя работает.

curl -i http://127.0.0.1:8000/users
HTTP/1.0 200 OK
Content-Type: application/json
Content-Length: 28

{"users": ["Anna", "Boris"]}

-I отправляет запрос HEAD и показывает только заголовки. Флаг -v печатает и сам запрос: строки с > curl отправил, строки с < получил. Служебные строки со звёздочкой отрежем grep:

curl -s -v http://127.0.0.1:8000/users 2>&1 | grep '^[<>]'
> GET /users HTTP/1.1
> Host: 127.0.0.1:8000
> User-Agent: curl/8.23.0
> Accept: */*
> 
< HTTP/1.0 200 OK
< Content-Type: application/json
< Content-Length: 28
< 

Без опций curl сам ставит заголовки Host, User-Agent со своей версией и Accept: */*. Какие ещё бывают заголовки и зачем они, мы разбирали в статье про HTTP-заголовки.

Отправка POST-запроса: форма и JSON

-d отправляет данные методом POST. Метод указывать не нужно, а тип содержимого curl по умолчанию ставит как у HTML-формы:

curl -d 'name=Vera&role=dev' http://127.0.0.1:8000/echo
{"method": "POST", "type": "application/x-www-form-urlencoded", "body": "name=Vera&role=dev"}

Для REST API нужен JSON. Классический вариант: заголовок Content-Type через -H и тело через -d. С версии 7.82.0 то же делает одна опция --json, она ещё добавляет Accept: application/json:

curl -H 'Content-Type: application/json' -d '{"name": "Vera"}' http://127.0.0.1:8000/users
curl --json '{"name": "Vera"}' http://127.0.0.1:8000/users
{"name": "Vera"}{"name": "Vera"}

Ответы склеились в одну строку, потому что сервер не ставит перевод строки в конце тела. Длинный JSON удобнее держать в файле и передавать как --json @user.json. Проверять, что внутри действительно JSON, curl не будет: битое тело уйдёт на сервер как есть.

Читайте также:  Git Bash: что это, как установить и основные команды

Мы не советуем писать curl -X POST -d ...: -d уже делает POST. Хуже того, метод из -X вместе с -L уходит во все запросы цепочки редиректов. -X используйте для PUT, DELETE и PATCH. Как эти методы работают в API, разобрано в статье REST API.

Ноутбук с ответом API в формате JSON на экране

Заголовки запроса и аутентификация

Заголовков -H можно передать несколько, ограничения нет. Если имя совпадает с заголовком, который curl ставит сам, побеждает ваш. Токен передают заголовком Authorization, а User-Agent меняет -A:

curl -H 'Authorization: Bearer token123' http://127.0.0.1:8000/echo
{"method": "GET", "auth": "Bearer token123"}

Что ушло в заголовке User-Agent после -A, видно в подробном выводе:

curl -s -v -A 'my-script/1.0' http://127.0.0.1:8000/echo 2>&1 | grep User-Agent
> User-Agent: my-script/1.0

Для Basic-аутентификации есть -u user:password:

curl -u admin:qwerty http://127.0.0.1:8000/echo
{"method": "GET", "auth": "Basic YWRtaW46cXdlcnR5"}

Сервер получил пару admin:qwerty в кодировке Base64. Это не шифрование: Base64 раскодируется обратно без всякого ключа. Без HTTPS такой пароль мы бы не отправляли. Пароль прямо в команде лучше не писать: там, где система это позволяет, curl прячет его из списка процессов, но на короткое время он там виден другим пользователям той же системы. Укажите только имя, -u admin, и curl спросит пароль сам.

Куки: сохранить и отправить

-c файл записывает куки, которые прислал сервер, -b файл читает их и отправляет:

curl -c cookies.txt http://127.0.0.1:8000/login
{"login": "ok"}

Сервер прислал куку, curl записал её в файл. Отправляем её со следующим запросом:

curl -b cookies.txt http://127.0.0.1:8000/echo
{"method": "GET", "cookie": "session=abc123"}

Строка с кукой в самом файле:

grep session cookies.txt
127.0.0.1   FALSE   /   FALSE   0   session abc123

Файл в формате Netscape, поля разделены табуляцией. Одну куку можно передать и без файла: -b 'session=abc123'.

Разработчик сверяет запрос и ответ сервера на двух мониторах

Редиректы: -L и что происходит с POST

По умолчанию curl редиректам не следует и показывает ответ 3xx как есть. С -L он идёт по адресу из заголовка Location, по умолчанию не больше 50 переходов (--max-redirs):

curl http://127.0.0.1:8000/old
curl -L http://127.0.0.1:8000/old
{"moved": "/echo"}{"method": "GET"}

Теперь отправим POST на тот же адрес:

curl -L -d 'x=1' http://127.0.0.1:8000/old
curl -L --post301 -d 'x=1' http://127.0.0.1:8000/old
{"method": "GET"}{"method": "POST", "type": "application/x-www-form-urlencoded", "body": "x=1"}

После ответов 301, 302 и 303 curl повторяет POST как GET. В прогоне выше после 301 данные формы до нового адреса не дошли. Если API ждёт POST и после редиректа, нужны --post301, --post302 или --post303. Пароль из -u при переходе на другой хост curl не передаёт.

Код ответа и ошибки в скриптах

Для curl ответ 404 или 500 не ошибка: запрос выполнен, тело получено, код выхода 0. В скрипте сломанный API пройдёт незамеченным, если не проверить код. Первый способ: -w '%{http_code}' печатает код ответа, а -o /dev/null выбрасывает тело.

code=$(curl -s -o /dev/null -w '%{http_code}' http://127.0.0.1:8000/users)
if [ "$code" = 200 ]; then echo "API отвечает"; else echo "ошибка: $code"; fi
curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:8000/nope
API отвечает
404

Второй способ: -f завершает curl с кодом 22, если сервер ответил 400 и выше. Вместе с -sS таблица прогресса скрыта, а текст ошибки остаётся. --fail-with-body (с версии 7.76.0) тоже возвращает 22, но печатает тело ответа:

curl -s http://127.0.0.1:8000/nope; echo " код выхода: $?"
curl -sS -f http://127.0.0.1:8000/nope 2>&1; echo "код выхода: $?"
curl -s --fail-with-body http://127.0.0.1:8000/nope; echo " код выхода: $?"
{"error": "not found"} код выхода: 0
curl: (22) The requested URL returned error: 404
код выхода: 22
{"error": "not found"} код выхода: 22

Защита не абсолютная: при аутентификации ответы 401 и 407 могут проскочить мимо -f. Если сервер не запущен, curl выйдет с кодом 7 (Failed to connect to host). В -w можно вывести и заголовок ответа (%header{} появился в curl 7.84.0, --json в 7.82.0):

curl -s --json '{"name": "Vera"}' -w '\n%{http_code} %header{content-type}\n' http://127.0.0.1:8000/users
{"name": "Vera"}
201 application/json

Скрипт проверки API запускается в терминале на сервере

Скачать файл и загрузить файл на сервер

-o имя сохраняет ответ в файл с заданным именем, -O берёт имя файла из последней части URL. Существующий файл с тем же именем curl перезапишет без вопросов.

curl -O http://127.0.0.1:8000/users
cat users
{"users": ["Anna", "Boris"]}

При сохранении в файл curl рисует в терминале таблицу прогресса, её скрывает -s. Прерванное скачивание большого файла продолжает -C -: curl сам посмотрит, сколько байт уже лежит в файле.

Читайте также:  SSH ключи: как создать, где хранятся и как добавить на сервер

Загрузку файла на сервер формой делает -F 'file=@report.csv': знак @ говорит curl взять содержимое из файла, а тип содержимого будет multipart/form-data.

curl в Windows: PowerShell, cmd и кавычки

В Windows PowerShell 5.1 слово curl занято: это псевдоним Invoke-WebRequest, у которого другие параметры. Проверить легко:

(Get-Command curl).Definition
Invoke-WebRequest

Настоящую утилиту вызывайте как curl.exe. В PowerShell 7 такого псевдонима нет, в cmd и Git Bash команда curl сразу запускает утилиту. Про сам PowerShell и запуск файлов .ps1 есть отдельная статья: PowerShell скрипты.

Команду, скопированную из Linux, PowerShell 5.1 запускает, но сервер получает тело JSON без кавычек. Windows PowerShell 5.1 не сохраняет кавычки внутри строки, когда передаёт аргументы внешней программе; с версии 7.3 PowerShell их сохраняет:

curl.exe -s -H 'Content-Type: application/json' -d '{"name": "Vera"}' http://127.0.0.1:8000/users
{"error": "bad json", "body": "{name: Vera}"}

Рабочий обход: положить JSON в файл и передать его через @. Сам '@user.json' берите в кавычки, иначе PowerShell примет @ за свой оператор и не запустит команду. В русской Windows PowerShell 5.1 сообщение такое: «Оператор с символом «@» невозможно использовать для ссылки на переменные в выражении. «@user» может использоваться только как аргумент для команды. Для ссылки на переменные в выражении используйте «$user».», код ошибки SplattingNotPermitted. С кавычками команда работает:

Set-Content -Path user.json -Value '{"name": "Vera"}'
curl.exe -s --json '@user.json' http://127.0.0.1:8000/users
{"name": "Vera"}

Если не хочется думать о кавычках PowerShell, запускайте примеры из этой статьи в Git Bash: там они работают как в Linux.

Окна PowerShell и Git Bash рядом на одном экране

HTTPS, сертификаты и прокси

С адресами https:// curl по умолчанию проверяет сертификат сервера: имя в сертификате должно совпасть с хостом из URL, а подпись принадлежать известному центру сертификации. Код выхода 60 значит, что сертификат подтвердить не удалось. Опция -k отключает проверку целиком, и соединение по HTTPS перестаёт быть защищённым. Мы не советуем ставить её даже «временно»: такую опцию легко забыть в скрипте. Для внутреннего центра сертификации передайте его сертификат опцией --cacert файл.pem. В сборках на Schannel, как у curl.exe в Windows, опция тоже работает, но для них рекомендуют добавить сертификат в хранилище корневых сертификатов Windows. Как устроены сертификаты и TLS, мы разбирали в статье как работает HTTPS.

Через прокси запрос отправляет опция -x [протокол://]хост[:порт], без протокола curl считает прокси HTTP-прокси.

Ноутбук разработчика рядом с сетевым оборудованием в серверной

Частые вопросы о curl

Что такое curl-запрос?

Это команда curl с адресом и опциями, которая описывает один HTTP-запрос: метод, заголовки, тело. Её можно скопировать в терминал и повторить, поэтому curl-запрос удобно прикладывать к описанию бага в API.

Чем curl в Linux отличается от curl.exe в Windows?

Это один проект с теми же опциями. Различаются версия, набор протоколов и TLS-библиотека конкретной сборки, всё это показывает curl -V. У curl.exe в Windows библиотека Schannel, и опции сертификатов работают с ней иначе: например, переменную окружения CURL_CA_BUNDLE такая сборка не учитывает. В PowerShell 5.1 добавляются псевдоним curl и обработка кавычек.

Кто создал curl?

Начал проект бразильский разработчик Рафаэль Сагула в 1996 году под именем HttpGet. Даниэль Стенберг вскоре стал сопровождающим, curl 4 вышел 20 марта 1998 года. Сейчас утилиту развивает сообщество.

Как посмотреть только код ответа?

curl -s -o /dev/null -w '%{http_code}\n' адрес. В PowerShell вызывайте curl.exe и вместо /dev/null пишите NUL: curl.exe -s -o NUL -w '%{http_code}\n' адрес.

Как отправить файл JSON?

curl --json @data.json адрес (в PowerShell '@data.json' в кавычках) или, для curl 7.81.0 и раньше, curl -H 'Content-Type: application/json' --data-binary @data.json адрес. Обычный -d @файл выкидывает из файла переводы строк, а --data-binary и --json отправляют его как есть.

Оцените статью
bestprogrammer.ru
Добавить комментарий