Генератор и конструктор curl-команд

Что такое curl-команда?

# Plain GET — curl defaults to GET
curl https://api.example.com/users

# GET with a Bearer token (auth is just a header)
curl https://api.example.com/me \
  -H 'Authorization: Bearer YOUR_TOKEN'

# POST a JSON body — note the Content-Type header
curl -X POST https://api.example.com/users \
  -H 'Content-Type: application/json' \
  -d '{"name":"Ada","role":"admin"}'

# Multipart file upload — '@' reads the file from disk
curl -X POST https://api.example.com/upload \
  -F 'file=@report.pdf' \
  -F 'title=Q3 report'

Ключевые возможности

Альтернативы curl и HTTP-клиенты

Примеры curl-команд

curl https://api.example.com/users

curl https://api.example.com/me \
  -H 'Authorization: Bearer YOUR_TOKEN'

curl -X POST https://api.example.com/users \
  -H 'Content-Type: application/json' \
  -d '{"name":"Ada","role":"admin"}'

curl -X POST https://api.example.com/login \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'username=ada&password=s3cret'

curl -X POST https://api.example.com/upload \
  -F 'file=@report.pdf' \
  -F 'title=Q3 report'

curl -L -o archive.zip \
  https://example.com/files/archive.zip

curl -u ada:s3cret \
  https://api.example.com/private

curl -v -i https://api.example.com/health

Как создать curl-команду

1. 1

   Выберите HTTP-метод

   Выберите GET, POST, PUT, PATCH, DELETE, HEAD или OPTIONS. curl по умолчанию использует GET; выбор POST или другого глагола добавляет -X METHOD к сгенерированной команде. Или нажмите пресет, чтобы задать метод и подходящее тело одним кликом.

2. 2

   Введите URL и параметры запроса

   Введите URL запроса (например, https://api.example.com/users). Добавляйте параметры запроса в виде пар ключ/значение, и инструмент автоматически кодирует их и добавляет ?key=value&… к URL — ручное кодирование не нужно.

3. 3

   Добавьте заголовки и аутентификацию

   Добавляйте заголовки запроса в виде пар ключ/значение, затем выберите схему авторизации: None, Bearer-токен, Basic (логин/пароль) или кастомный заголовок API-ключа. Правильный заголовок Authorization или кастомный заголовок будет сгенерирован в точном формате, который ожидает сервер.

4. 4

   Задайте тело запроса

   Для POST/PUT/PATCH выберите тип тела: вставьте сырой JSON (заголовок Content-Type добавляется за вас), создайте urlencoded-поля формы или соберите multipart-загрузку и переключите любое поле в файл с префиксом @.

5. 5

   Включите нужные параметры

   Активируйте нужные флаги — следовать редиректам (-L), небезопасный TLS (-k), подробный вывод (-v), включить заголовки (-i), сжатие (--compressed), сохранение в файл (-o), таймаут соединения или прокси (-x). Каждое переключение обновляет команду в реальном времени.

6. 6

   Скопируйте, экспортируйте или сбросьте

   Скопируйте готовую команду, выполните Export .sh для скачивания в виде скрипта или Reset для сброса формы. Используйте переключатель Multi-line для выбора между однострочным и многострочным форматом перед копированием.

Частые ошибки curl

# Ожидался PATCH, но -d один подразумевает POST
curl -d '{"role":"admin"}' \
  https://api.example.com/users/7

# Явно задайте глагол
curl -X PATCH -d '{"role":"admin"}' \
  -H 'Content-Type: application/json' \
  https://api.example.com/users/7

# Сервер видит urlencoded, а не JSON — 400/415
curl -X POST https://api.example.com/users \
  -d '{"name":"Ada"}'

# Объявите тип содержимого JSON
curl -X POST https://api.example.com/users \
  -H 'Content-Type: application/json' \
  -d '{"name":"Ada"}'

# $name раскрывается оболочкой в пустую строку
curl -d "{\"user\":\"$name\"}" \
  https://api.example.com/users

# Одинарные кавычки передают тело буквально
curl -d '{"user":"$name"}' \
  https://api.example.com/users

# -d делает это POST, а не GET
curl -d 'page=2&limit=50' \
  https://api.example.com/users

# Строка запроса в URL сохраняет метод GET
curl 'https://api.example.com/users?page=2&limit=50'

:: cmd.exe — обратный слеш не является символом продолжения
curl -X POST https://api.example.com/users \
  -d '{"name":"Ada"}'

:: cmd.exe — одна строка или используйте ^ для продолжения
curl -X POST https://api.example.com/users -d "{\"name\":\"Ada\"}"

# Пробел разбивает аргумент — curl видит два аргумента
curl https://api.example.com/search?q=hello world

# Закодируйте пробел (или возьмите весь URL в кавычки)
curl 'https://api.example.com/search?q=hello%20world'

Типовые сценарии использования

Тестирование REST API

Создавайте и отправляйте запросы к REST-эндпоинту, не выходя из терминала: задайте метод, вставьте Bearer-токен, отправьте JSON-тело и прочитайте ответ. Самый быстрый способ убедиться в корректности API перед написанием клиентского кода.

Воспроизведение запроса из документации

Документация API показывает эндпоинты и параметры, но редко даёт полную готовую команду. Заполните метод, URL, заголовки и авторизацию здесь и получите curl-команду, которая работает «как есть» — без борьбы с кавычками или отсутствующими заголовками Content-Type.

Smoke-тесты в CI/CD

Сгенерируйте curl-команду для health check или post-deploy smoke-теста, затем выполните Export .sh для добавления в пайплайн. Добавьте --connect-timeout и --max-time, чтобы зависший эндпоинт не блокировал сборку, и проверяйте статус-коды с -w.

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

Соберите multipart/form-data-загрузку с -F field=@file или создайте -L -o filename-скачивание с переходом по редиректам к CDN. Предварительно закодируйте сложные имена файлов или значения запроса с помощью нашего URL-энкодера.

Отладка вебхуков

Воспроизведите webhook-payload, отправив тот же JSON, который отправляет провайдер, с правильными заголовками подписи и Content-Type. Воспроизведите точный запрос локально, чтобы отладить, почему ваш обработчик его отклонил.

Воспроизводимые баг-репорты

Вставьте одну самодостаточную curl-команду в баг-репорт или PR, чтобы любой мог воспроизвести точный запрос — метод, заголовки, плейсхолдер авторизации и тело. Намного понятнее, чем описывать запрос прозой.

Изучение флагов curl

Смотрите, как каждый выбор в форме соответствует реальному флагу — выберите Basic auth и наблюдайте появление -u, добавьте JSON-тело и следите за прикреплением заголовка Content-Type. Практический способ изучить синтаксис в паре с нашей шпаргалкой по curl.

Подготовка запроса для конвертации в код

Создайте и проверьте запрос как curl, затем переведите его в HTTP-клиент вашего приложения. Предстоящая вкладка Convert преобразует вставленную curl-команду в fetch, requests, Go, PHP, Ruby и Node.js — начните с curl-команды, которая точно работает.

Флаги и синтаксис curl

Экранирование в оболочке

Инструмент оборачивает значения в одинарные кавычки — самый безопасный способ в POSIX-оболочках, поскольку внутри строки в одинарных кавычках ничего не раскрывается. Буквальная одинарная кавычка внутри значения выводится как последовательность '\'' (закрывающая кавычка, экранированная кавычка, открывающая кавычка). В cmd.exe используйте двойные кавычки; Git Bash и WSL выполняют сгенерированные команды с одинарными кавычками без изменений.

-d против --data-raw и --data-binary

-d/--data удаляет из тела символы новой строки и возврата каретки — подходит для пар key=value, теряет данные при многострочном содержимом. --data-raw идентичен, но не воспринимает ведущий @ как имя файла. --data-binary отправляет байты точно так, как заданы (используйте @file для загрузки сырого содержимого файла). Все три подразумевают POST, если метод не переопределён.

Multipart (-F) против URL-encoded (-d)

-F field=value создаёт multipart/form-data с генерируемым boundary — обязательно для загрузки файлов (-F file=@path) и смешанных форм с файлами и текстом. -d field=value создаёт application/x-www-form-urlencoded — одну строку, объединённую через &. Никогда не задавайте Content-Type вручную для multipart; curl сам вычисляет boundary и устанавливает заголовок.

Кодирование заголовка авторизации

Bearer auth отправляет Authorization: Bearer <token> дословно (RFC 6750). Basic auth через -u user:pass Base64-кодируется в Authorization: Basic <base64> при передаче — это кодирование, а не шифрование, поэтому используйте HTTPS. API-ключ — это любой кастомный заголовок, который требует сервис, например X-API-Key: <value>.

Кодирование строки запроса

Параметры запроса, добавленные в конструкторе, процентно кодируются и добавляются как ?key=value&key2=value2. Зарезервированные символы (пробелы, &, =, #) экранируются, чтобы URL был корректным. Для полей тела, которые нужно закодировать, встроенная функция curl --data-urlencode выполняет кодирование в момент запроса.

Поведение при редиректах (-L)

Без -L curl выводит ответ 301/302 и останавливается. С -L он следует заголовку Location до конечного URL. Обратите внимание, что curl удаляет заголовок Authorization при редиректе на другой хост (защита по умолчанию); используйте --location-trusted только тогда, когда понимаете последствия.

Сжатые ответы

--compressed добавляет заголовок Accept-Encoding, рекламирующий поддержку gzip/deflate/brotli, и прозрачно разжимает ответ, экономя трафик. Декодированное тело идентично ответу без сжатия — это чисто транспортная оптимизация, безопасная для большинства вызовов API.

Вывод: -o против -O

-o filename записывает тело ответа в указанный вами файл; -O сохраняет его под именем удалённого файла из пути URL. Оба подавляют стандартный вывод в stdout. Сочетайте с -L, чтобы редиректы разрешились до реального ресурса перед записью файла.

Лучшие практики curl-запросов

Никогда не хардкодьте секреты в общих командах

curl-команда, которую вы вставляете в PR, тикет или чат, будет прочитана другими и проиндексирована инструментами. Замените токены и пароли плейсхолдером (YOUR_TOKEN) или ссылайтесь на переменную окружения (-H "Authorization: Bearer $API_TOKEN"). Для длинных учётных данных curl может читать заголовок из файла с помощью -H @headerfile, чтобы секрет никогда не появлялся в истории оболочки.

Предпочитайте --data-binary @file для бинарных payload

Когда тело — это файл, байты которого важны (изображение, подписанный payload, JSON, где значимы пробелы), используйте --data-binary @file, а не -d @file. Обычный -d удаляет символы новой строки и возврата каретки, молча повреждая бинарное и многострочное содержимое. --data-binary отправляет файл точно так, как он есть на диске.

Заключайте значения заголовков в кавычки

Всегда оборачивайте значения -H в кавычки: -H 'Content-Type: application/json'. Без кавычек пробел после двоеточия разбивает аргумент, и curl получает некорректный заголовок. Одинарные кавычки также предотвращают раскрытие оболочкой $, * и других спецсимволов внутри значения — именно это генерирует инструмент по умолчанию.

Используйте --compressed для экономии трафика

Добавляйте --compressed к вызовам API и загрузкам, чтобы запросить gzip/brotli-кодирование и дать curl прозрачно разжать ответ. Для API с большим объёмом JSON это может сократить объём передачи на 70–90% без изменения получаемого ответа — бесплатное улучшение в скриптах, которые регулярно опрашивают эндпоинты.

Фиксируйте таймауты в скриптах

В любом автоматизированном контексте добавляйте --connect-timeout и --max-time, чтобы медленный или зависший эндпоинт не блокировал пайплайн бесконечно. Health check с --max-time 10 быстро завершится с ошибкой и позволит CI продолжить работу. Сочетайте с --retry N для поглощения кратковременных сетевых сбоев без немедленного отказа.

Проверяйте с -v перед автоматизацией

Прежде чем встраивать curl-команду в скрипт или cron-задание, запустите её один раз с -v, чтобы увидеть точную строку запроса, заголовки и TLS-рукопожатие. Это самый быстрый способ обнаружить неверный метод, отсутствующий Content-Type или незакреплённый заголовок авторизации — отлаживайте интерактивно, затем удалите -v для production.

Часто задаваемые вопросы