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

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

Параметры запроса, добавленные в конструкторе, процентно кодируются и добавляются как `?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.

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