xh: удобный HTTP-клиент для терминала

Проверять API из терминала приходится часто: посмотреть ответ, отправить JSON, воспроизвести жалобу пользователя. curl умеет всё, но для повседневных запросов его синтаксис получается многословным: кавычки, экранирование, десяток флагов. xh — HTTP-клиент, написанный на Rust, который переносит удобный синтаксис HTTPie в один быстрый исполняемый файл. Он не заменяет curl в сложных сценариях, но экономит время.

Установка и первый запрос

В Debian, Ubuntu, Linux Mint, Fedora и Arch Linux xh есть в штатных репозиториях. Если пакета нет, установите через Cargo — понадобится toolchain Rust.

sudo apt install xh
xh --version
xh https://httpbin.org/json

По умолчанию xh подставляет схему http://, поэтому в примерах схема указана явно. Если создать символическую ссылку с именем xhs, клиент будет по умолчанию использовать HTTPS:

ln -s "$(command -v xh)" ~/.local/bin/xhs
xhs example.com
xh --headers https://example.com

Вывод раскрашен, JSON отформатирован, заголовки отсортированы. Флаг --headers оставляет только заголовки ответа — удобно для проверки редиректов и типов содержимого.

Параметры, JSON и формы

Главное преимущество xh — короткая запись данных. Обычное равенство добавляет поле JSON, а := передаёт литерал: число, булево значение, массив или вложенный объект. Разделитель == добавляет параметр в строку запроса.

xh GET https://httpbin.org/get id==5 lang==ru
xh POST https://httpbin.org/post name=alex age:=37 active:=true
xh PUT https://httpbin.org/put numbers:='[1,2,3]' user:='{"id":7}'

Если тело нужно отправить в формате HTML-формы, используется --form. Файлы передаются через @, а --multipart принудительно включает multipart/form-data даже без файлов. Это пригодится для проверки загрузки аватара или документа.

xh --form POST https://httpbin.org/post login=alex
xh --form POST https://httpbin.org/post file@./report.pdf
cat payload.json | xh POST https://httpbin.org/post

Если данные уже подготовлены, их можно передать из файла или стандартного ввода. Для скриптов важна предсказуемость: --raw отключает обработку тела, а --pretty=none убирает цвета и форматирование, чтобы вывод проще было разбирать.

Заголовки, токены и сессии

Заголовок задаётся конструкцией имя:значение. Значение можно прочитать из файла: это лучше, чем вставлять токен прямо в командную строку, где он попадёт в историю shell и список процессов.

chmod 600 token.txt
xh https://api.example.com/v1/me authorization:@token.txt accept:application/json

Для повторяющихся запросов удобны сессии. --session сохраняет cookies, заголовки и авторизацию между вызовами, а --session-read-only читает сессию, не обновляя её. Файлы лежат в ~/.config/xh/sessions, их стоит беречь как cookie браузера.

xh --session work https://api.example.com/login username=alex password=secret
xh --session work https://api.example.com/orders
xh --session-read-only work https://api.example.com/me

Пароль в примере — учебный. В реальности вводите его по запросу или храните в файле с правами 600. Для Basic и Bearer есть --auth и --auth-type, но заголовок из файла не оставляет секрет в истории.

Редиректы, коды ответа и диагностика

В отличие от HTTPie, xh по умолчанию включает --check-status и завершает работу с ненулевым кодом при ошибке HTTP. Это удобно в автоматизации, но может удивить в интерактивной работе. Редиректы по умолчанию не выполняются: для перехода по цепочке нужен --follow.

xh --follow --max-redirects=5 https://example.com
xh -v https://httpbin.org/status/500
xh --print=hHb https://httpbin.org/status/404

Флаг -v показывает запрос и ответ целиком, включая заголовки. --print позволяет выбрать части вывода: H — заголовки запроса, B — тело запроса, h — заголовки ответа, b — тело, m — метаданные. Для разбора проблем с прокси, кешем или неверным Content-Type этого обычно достаточно.

Коды возврата годятся для условий в скриптах: 2 — таймаут, 3 — необработанный редирект, 4 — ошибка 4xx, 5 — ошибка 5xx, 6 — слишком много редиректов. Проверка в оболочке выглядит просто:

if xh --check-status --timeout=10 https://api.example.com/health >/dev/null; then
  echo "API доступен"
else
  echo "Код: $?"
fi

--timeout ограничивает установку соединения, а не всё время запроса. Если сервер отвечает медленно, нужен внешний timeout. В скриптах добавляйте --ignore-stdin, иначе xh может прочитать тело из перенаправленного ввода.

Скачивание, конфигурация и перенос команд

Для файлов есть --download: клиент сам выберет имя, подставит Accept-Encoding: identity и перейдёт по редиректам. Ключ --continue возобновляет прерванную загрузку, но требует одновременно --download и --output.

xh -d -o archive.tar.gz https://example.com/archive.tar.gz
xh -d -c -o big.iso https://example.com/big.iso
xh --curl POST https://httpbin.org/post name=alex

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

Настройки хранятся в ~/.config/xh/config.json. В конфигурации поддерживается список аргументов по умолчанию — например, таймаут и стиль подсветки. Не стоит записывать туда токены: файл общий для всех сессий и может попасть в резервную копию.

{
  "default_options": ["--timeout=15", "--style=solarized"]
}

Путь к конфигурации переопределяется переменной XH_CONFIG_DIR. Переменные HTTP_PROXY, HTTPS_PROXY и NO_PROXY клиент учитывает. Для проверки DNS есть --resolve домен:адрес: запрос уйдёт на нужный IP с правильным Host и SNI.

Когда xh, а когда curl

• xh — интерактивные запросы к API, быстрый JSON, проверка заголовков, чтение ответов человеком.
• curl — сложные сценарии: загрузка нескольких файлов, тонкая настройка TLS, повторные попытки, работа в минимальных образах и старых системах.
• httpie — если уже есть привычные плагины и сценарии; xh совместим с большей частью его синтаксиса.
• Для скриптов важнее стабильный код возврата и отсутствие лишнего вывода.

Не отправляйте токены в открытом виде и не отключайте проверку сертификатов. Для самоподписанного API укажите свой CA через --verify=/path/to/ca.pem.

Итог

xh занимает нишу между curl и полноценным API-клиентом: он быстрый, ставится одним пакетом и не требует запоминать десятки флагов. Его сильные стороны — короткая запись JSON, понятный вывод, сессии и предсказуемые коды возврата. Освоив --print, --follow, --session и --curl, вы закрываете почти все повседневные задачи проверки HTTP. Для сложных сценариев держите под рукой curl.