Resterm

Нативный терминальный API-клиент и рабочая среда для REST, GraphQL, gRPC, WebSocket и SSE.

Resterm — это рабочая среда в духе API-as-code — или, говоря привычнее, API-клиент, — построенная вокруг обычных .http и .rest файлов, которые можно сравнивать, ревьюить и версионировать. Он сочетает интерактивное редактирование запросов с декларативными рабочими процессами, проверками (assertions), mock-серверами, трассировкой, профилированием и автоматизацией без графического интерфейса. Всё остаётся на вашей машине. Никаких аккаунтов, облачной синхронизации и телеметрии.

Если вы ищете клиент в стиле Postman, ориентированный на GUI-коллекции, Resterm, скорее всего, не для вас, но всё равно попробуйте!

[!NOTE] Resterm теперь на v1! Смотрите заметки о релизе v1.0.0 о новых функциях и ломающих изменениях.

Быстрые ссылки: Скриншоты, Установка, Быстрый старт, Документация.

Обзор скриншотов

Почему Resterm

• HTTP, GraphQL, gRPC, WebSocket и SSE из коробки.
• Автоматизация живёт в файлах запросов: условия (@when, @if/@elif/@else, @for-each), многошаговые рабочие процессы (@workflow / @step), захваты, переменные и проверки (@capture, @var, @assert).
• RestermScript — небольшой язык выражений, созданный для Resterm, с JavaScript-хуками, когда они нужны.
• Управление в стиле Vim с контекстными подсказками в нижней панели, доступной офлайн справкой с поиском, справкой K под курсором, поиском / и командами вроде :w, , и .

Быстрый старт

1. Установите Resterm (см. Установка — скрипты, Windows и ручная установка).

   root@kitploit:~

   brew install resterm
   

2. Создайте рабочую область.

   root@kitploit:~

   mkdir my-api && cd my-api
   resterm init
   

   resterm init создаёт небольшой проект, который работает без подключения к интернету. Сгенерированный requests.http включает локальные mock-сценарии и несколько запросов, которые строятся друг на друге. Они покрывают проверки, bearer-аутентификацию, сопоставление JSON, json-rules и @for-each.

3. Запустите его и отправьте первый запрос.

   root@kitploit:~

   resterm
   

   Нажмите Ctrl+Enter в редакторе, чтобы отправить выделенный запрос.

Ещё нет файлов? Просто запустите resterm, введите URL и нажмите Ctrl+Enter. Вставленная curl-команда тоже работает.

CLI

resterm run выполняет .http / .rest файлы без открытия TUI — именно это запускается в CI.

resterm run --request CreateUser requests.http

Сгенерированный проект обращается к локальному mock-серверу. Сначала запустите его в другом терминале:

resterm mock requests.http

В TUI нажмите g Shift+M, чтобы запустить тот же mock-сервер из рабочей области.

Документация по CLI описывает селекторы, форматы вывода и другие примеры.

Mock-серверы

Те же файлы, в которых живут ваши запросы, могут служить HTTP-моками.

• Сопоставляйте входящие запросы по query-параметрам, заголовкам или JSON-телу, а затем выбирайте именованный ответ или ответ по умолчанию.
• Моделируйте сценарии опроса и повторов с помощью последовательностей ответов, включая независимые курсоры для каждого ресурса или вызывающего.
• Задерживайте ответы на фиксированное время или задавайте каждому запросу разную задержку с помощью random, normal или jitter.
• Стройте ответы из значений пути, query-параметров, заголовков и тела, с генераторами для динамических данных.
• Проверяйте количество вызовов с помощью @expect или просматривайте полученный трафик из RestermScript.
• Горячая перезагрузка исходных файлов и фикстур, с опциональным TLS.

Два сценария на одном маршруте:

### Payment accepted
# @mock method=POST path=/payments name=accepted default=true latency=150ms
HTTP/1.1 202 Accepted
Content-Type: application/json

{"id":"pay_123","status":"pending"}

### Payment declined
# @mock method=POST path=/payments name=declined
# @match query={"mode":"decline"} headers={"X-Tenant":"demo"} json={"amount":0}
HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json

{"error":"amount must be positive"}

Обслуживайте один файл или целую директорию:

resterm mock ./requests.http
resterm mock --recursive --addr 127.0.0.1:9090 ./requests

Подробнее в справочнике по Mock-серверам, руководстве по CLI resterm mock и рабочем примере.

Headless

Пакет headless — это публичный Go API для того же движка, который работает под капотом TUI и CLI. Используйте его для запуска запросов, рабочих процессов, проверок, сравнения запусков и профилей из собственного Go-кода или CI.

Если вы предпочитаете не собирать раннер самостоятельно, есть resterm-runner.

Шпаргалка по клавиатуре

• Фокус панелей и раскладка
  • Tab / Shift+Tab: перемещение между сайдбаром, редактором и ответом.
  • g+r, g+i, g+p: переход к запросам, редактору или ответу.
  • g+h / g+l: изменение размера по горизонтали. Меняет ширину сайдбара, когда сфокусирован сайдбар, и разделение редактора/ответа в остальных случаях.
  • g+j / g+k: изменение высоты редактора/ответа при вертикальном расположении, свёртывание или разворачивание веток в навигаторе.
  • g+v / g+s: переключение панели ответа между встроенной и вертикальной раскладкой.
  • g+1, g+2, g+3: сворачивание или восстановление сайдбара, редактора, ответа.

[!TIP] Если запомнить только три сочетания:

• Ctrl+Enter — отправить запрос
• Tab / Shift+Tab — переключение панелей
• g+p — переход к ответу

Установка

Linux / macOS (Homebrew)

brew install resterm

[!NOTE] Установки через Homebrew следует обновлять через Homebrew (brew upgrade resterm). Встроенная команда resterm --update предназначена для бинарников, установленных из GitHub-релизов или установочных скриптов.

Linux / macOS (скрипт для оболочки)

[!IMPORTANT] Готовые Linux-бинарники зависят от glibc 2.32 или новее. На старых дистрибутивах собирайте из исходников с более новым тулчейном glibc или обновите glibc перед использованием архивов релизов.

curl -fsSL https://raw.githubusercontent.com/unkn0wn-root/resterm/main/install.sh | bash

или с помощью wget:

wget -qO- https://raw.githubusercontent.com/unkn0wn-root/resterm/main/install.sh | bash

Windows (PowerShell)

iwr -useb https://raw.githubusercontent.com/unkn0wn-root/resterm/main/install.ps1 | iex

Скрипты определяют вашу архитектуру, скачивают последний релиз и устанавливают бинарник.

Ручная установка

[!NOTE] Помощник ручной установки использует curl и jq. Установите jq через ваш пакетный менеджер (brew install jq, sudo apt install jq и т.д.).

Linux / macOS

# Detect latest tag
LATEST_TAG=$(curl -fsSL https://api.github.com/repos/unkn0wn-root/resterm/releases/latest | jq -r .tag_name)

# Download the matching binary (Darwin/Linux + amd64/arm64)
curl -fL -o resterm "https://github.com/unkn0wn-root/resterm/releases/download/${LATEST_TAG}/resterm_$(uname -s)_$(uname -m)"

# Make it executable and move it onto your PATH
chmod +x resterm
sudo install -m 0755 resterm /usr/local/bin/resterm

Windows (PowerShell)

$latest = Invoke-RestMethod https://api.github.com/repos/unkn0wn-root/resterm/releases/latest
$asset  = $latest.assets | Where-Object { $_.name -like 'resterm_Windows_*' } | Select-Object -First 1
Invoke-WebRequest -Uri $asset.browser_download_url -OutFile resterm.exe
# Optionally relocate to a directory on PATH, e.g.:
Move-Item resterm.exe "$env:USERPROFILE\bin\resterm.exe"

Из исходников

go install github.com/unkn0wn-root/resterm/cmd/resterm@latest

Обновление

resterm --check-update
resterm --update

Первая команда сообщает, доступна ли более новая версия. Вторая скачивает, проверяет и устанавливает её на место. В Windows старый бинарник остаётся рядом с новым как resterm.exe.old и удаляется при следующем обновлении.

Конфигурация

• Окружения — это JSON-файлы (resterm.env.json), обнаруживаемые в директории запросов, корне рабочей области или текущей рабочей директории. Файл может определять именованные окружения или независимые группы, например api, app и credentials, которые объединяются в одно окружение. Dotenv-файлы (.env, .env.*) подключаются опционально через --env-file и применяются к одной рабочей области. См. групповые окружения и запускаемый пример в _examples/grouped/.
• Конфигурация хранится в зависимости от ОС и может быть переопределена через RESTERM_CONFIG_DIR:
  • macOS: ~/Library/Application Support/resterm
  • Windows: %APPDATA%\resterm
  • Linux/Unix: ~/.config/resterm

Коллекции

Экспортируйте рабочую область как Git-дружелюбный бандл и импортируйте его в другую. Бандлы содержат manifest.json с контрольными суммами, поэтому при импорте сначала проверяется целостность файлов. Значения окружений экспортируются как плейсхолдеры REPLACE_ME, поэтому секреты никогда не покидают вашу машину.

resterm collection export --workspace ./my-api --out ./shared/my-api-bundle
resterm collection import --in ./shared/my-api-bundle --workspace ./my-local-api

Добавьте --dry-run, чтобы предпросмотреть импорт, и --force, чтобы перезаписать существующие файлы. Документация: обмен коллекциями.

Импорт из curl

Вставьте curl-команду в редактор и нажмите Ctrl+Enter, чтобы превратить её в структурированный запрос. Resterm понимает распространённые флаги, объединяет повторяющиеся сегменты данных и сохраняет multipart-загрузки нетронутыми. Префиксы оболочки, такие как sudo или $, игнорируются. CLI выполняет то же преобразование с помощью --from-curl.

Исходная команда:

curl -X POST https://api.example.com/login \
  -H "Content-Type: application/json" \
  --user demo:secret \
  -d '{"user":"demo"}'

превращается в это:

### POST https://api.example.com/login
# @auth basic demo secret
POST https://api.example.com/login
Content-Type: application/json

{"user":"demo"}

Документация: inline-запросы и примеры импорта.

RestermScript

RestermScript (RTS) — это небольшой язык выражений, созданный для Resterm. Он нацелен непосредственно на формат запросов, рабочие процессы и директивы, что делает скрипты короткими и предсказуемыми. JavaScript-хуки остаются доступны, когда нужно больше.

Краткий пример (RTS-модуль + запрос):

// rts/helpers.rts
module helpers
export fn authHeader(token) {
  return token ? "Bearer " + token : ""
}

# @use ./rts/helpers.rts
# @when env.has("feature")
# @assert response.statusCode == 200
GET https://api.example.com/users/{{= vars.get("user") }}
Authorization: {{= helpers.authHeader(vars.get("auth.token")) }}

Полный справочник: docs/restermscript.md.

Глубокое погружение

OAuth 2.0

Client credentials, password grant и authorization code с PKCE. Для потоков с authorization code Resterm открывает ваш браузер, запускает локальный callback-сервер на 127.0.0.1, перехватывает редирект и обменивает код. Токены кэшируются для каждого окружения и обновляются по истечении срока действия. Документация: docs/resterm.md#oauth-20-directive и _examples/oauth2.http.

Рабочие процессы и скриптинг

Соединяйте запросы в цепочки с помощью @workflow и @step, передавайте данные между шагами и добавляйте JS-хуки там, где нужно. Документация и пример: docs/resterm.md#workflows и _examples/workflows.http.

Сравнение запусков

Запускайте один и тот же запрос в разных окружениях с помощью @compare или --compare, затем сравнивайте ответы бок о бок с помощью g+c. Документация: docs/resterm.md#compare-runs.

Трассировка и таймлайн

Добавьте @trace с бюджетами, чтобы фиксировать тайминги DNS, connect, TLS, TTFB и передачи данных. Resterm подсвечивает превышения и умеет экспортировать спаны в OpenTelemetry. Документация: docs/resterm.md#timeline--tracing.

Стриминг (WebSocket и SSE)

Используйте @websocket с шагами @ws или @sse, чтобы скриптовать и записывать потоки. Вкладка Stream хранит транскрипты и включает интерактивную консоль. Документация: docs/resterm.md#streaming-sse--websocket.

gRPC

Unary и стриминговые вызовы с транскриптами, метаданными и разворачиванием тела. Документация: docs/resterm.md#grpc.

Импорт из OpenAPI

Преобразуйте спецификации OpenAPI 3 в .http-коллекции с помощью --from-openapi, из локального файла или http(s) URL-адреса. Выбирайте генерируемые блоки через --openapi-mode requests, mocks или both. Удалённые загрузки учитывают глобальные флаги --insecure и --proxy. Документация: docs/cli.md#import-examples.

SSH-туннели

Направляйте HTTP-, gRPC-, WebSocket- и SSE-трафик через бастионы с помощью профилей @ssh. Документация: docs/resterm.md#ssh-tunnels и _examples/ssh.http.

Kubernetes port-forwards

Та же идея с профилями @k8s, нацеленными на поды, сервисы, deployment-ы или statefulset-ы. Документация: docs/resterm.md#kubernetes-port-forwards и _examples/k8s.http.

Темы и привязки клавиш

Настраивайте цвета и клавиатурные сочетания с помощью themes/*.toml и bindings.toml или bindings.json в директории конфигурации. Документация: docs/resterm.md#theming и docs/resterm.md#custom-bindings.

Документация

• docs/resterm.md описывает синтаксис запросов, директивы, скриптинг и транспорты.
• docs/cli.md описывает resterm run, импортёры, коллекции и историю.
• Совместимость объясняет гарантии совместимости Resterm для v1.

Внутри TUI нажмите ? или выполните :help. Используйте :docs, когда нужна полная веб-документация для установленного релиза.

Лицензия

Apache License 2.0.