Resterm

Un client API et un atelier de travail natifs du terminal pour REST, GraphQL, gRPC, WebSocket et SSE.

Resterm est un atelier de travail API-as-code - ou, en des termes plus familiers, un client API - construit autour de fichiers .http et .rest simples que vous pouvez diff, relire et versionner. Il combine l'édition interactive de requêtes avec des workflows déclaratifs, des assertions, des serveurs mock, du tracing, du profilage et de l'automatisation headless. Tout reste sur votre machine. Pas de comptes, pas de synchronisation cloud, pas de télémétrie.

Si vous recherchez un client de type Postman centré sur des collections GUI, Resterm n'est probablement pas fait pour vous, mais essayez-le quand même !

[!NOTE] Resterm est maintenant en v1 ! Consultez les notes de version v1.0.0 pour les nouvelles fonctionnalités et les changements de rupture.

Liens rapides : Captures d'écran, Installation, Démarrage rapide, Documentation.

Tour d'horizon en captures d'écran

Pourquoi Resterm

• HTTP, GraphQL, gRPC, WebSocket et SSE pris en charge d'emblée.
• L'automatisation vit dans les fichiers de requêtes : conditions (@when, @if/@elif/@else, @for-each), workflows multi-étapes (@workflow / @step), captures, variables et assertions (@capture, @var, @assert).
• RestermScript, un petit langage d'expressions conçu pour Resterm, avec des hooks JavaScript lorsque vous le souhaitez.
• Contrôles de style Vim avec des indices contextuels dans la barre inférieure, une aide hors ligne consultable, l'aide K sous le curseur, la recherche / et des commandes comme :w, , et .

Démarrage rapide

1. Installez Resterm (voir Installation pour les scripts, Windows et les installations manuelles).

   root@kitploit:~

   brew install resterm
   

2. Initialisez un espace de travail.

   root@kitploit:~

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

   resterm init vous fournit un petit projet qui fonctionne sans connexion Internet. Le fichier requests.http généré inclut des scénarios mock locaux et quelques requêtes qui s'appuient les unes sur les autres. Ils couvrent les assertions, l'authentification bearer, la correspondance JSON, json-rules et @for-each.

3. Lancez-le et envoyez votre première requête.

   root@kitploit:~

   resterm
   

   Appuyez sur Ctrl+Enter dans l'éditeur pour envoyer la requête en surbrillance.

Pas encore de fichiers ? Lancez simplement resterm, tapez une URL et appuyez sur Ctrl+Enter. Une commande curl collée fonctionne aussi.

CLI

resterm run exécute les fichiers .http / .rest sans ouvrir la TUI, c'est ce que lance l'intégration continue.

resterm run --request CreateUser requests.http

Le projet généré communique avec un serveur mock local. Démarrez-le d'abord dans un autre terminal :

resterm mock requests.http

Dans la TUI, appuyez plutôt sur g Shift+M pour démarrer le même serveur mock depuis l'espace de travail.

La documentation CLI couvre les sélecteurs, les formats de sortie et d'autres exemples.

Serveurs mock

Les mêmes fichiers qui contiennent vos requêtes peuvent servir des mocks HTTP.

• Faites correspondre les requêtes entrantes par query, en-têtes ou corps JSON, puis choisissez une réponse nommée ou par défaut.
• Modélisez les flux de polling et de nouvelles tentatives avec des séquences de réponses, y compris des curseurs indépendants par ressource ou par appelant.
• Retardez les réponses d'une durée fixe, ou attribuez à chaque requête un délai différent avec random, normal ou jitter.
• Construisez des réponses à partir des valeurs de chemin, de query, d'en-têtes et de corps, avec des générateurs pour les données dynamiques.
• Vérifiez les compteurs d'appels avec @expect ou inspectez le trafic reçu depuis RestermScript.
• Rechargez à chaud les fichiers sources et les fixtures, avec TLS optionnel.

Deux scénarios sur une même route :

### 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"}

Servez un seul fichier ou tout un répertoire :

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

Plus d'informations dans la référence des serveurs mock, le guide CLI resterm mock et l'exemple fonctionnel.

Headless

Le package headless est l'API Go publique du même moteur qui alimente la TUI et la CLI. Utilisez-le pour exécuter des requêtes, des workflows, des assertions, des comparaisons d'exécutions et des profils depuis votre propre code Go ou votre CI.

Si vous préférez ne pas construire vous-même un exécuteur, il existe resterm-runner.

Aide-mémoire clavier

• Focus et disposition des panneaux
  • Tab / Shift+Tab : passer entre la barre latérale, l'éditeur et la réponse.
  • g+r, g+i, g+p : accéder aux requêtes, à l'éditeur ou à la réponse.
  • g+h / g+l : redimensionner horizontalement. Modifie la largeur de la barre latérale lorsqu'elle est focalisée, sinon la répartition éditeur/réponse.
  • g+j / g+k : redimensionner la hauteur éditeur/réponse lorsqu'ils sont empilés, replier ou déplier les branches du navigateur.
  • g+v / g+s : basculer le panneau de réponse entre les dispositions en ligne et empilée.
  • g+1, g+2, : réduire ou restaurer la barre latérale, l'éditeur, la réponse.

[!TIP] Si vous ne retenez que trois raccourcis :

• Ctrl+Enter envoie la requête
• Tab / Shift+Tab change de panneau
• g+p accède à la réponse

Installation

Linux / macOS (Homebrew)

brew install resterm

[!NOTE] Les installations Homebrew doivent être mises à jour avec Homebrew (brew upgrade resterm). La commande intégrée resterm --update est destinée aux binaires installés à partir des releases GitHub ou des scripts d'installation.

Linux / macOS (script Shell)

[!IMPORTANT] Les binaires Linux précompilés dépendent de glibc 2.32 ou plus récent. Sur une distribution plus ancienne, compilez à partir des sources avec une chaîne d'outils glibc plus récente ou mettez à niveau glibc avant d'utiliser les archives de release.

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

ou avec 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

Les scripts détectent votre architecture, téléchargent la dernière release et installent le binaire.

Installation manuelle

[!NOTE] L'assistant d'installation manuelle utilise curl et jq. Installez jq avec votre gestionnaire de paquets (brew install jq, sudo apt install jq, etc.).

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"

Depuis les sources

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

Mise à jour

resterm --check-update
resterm --update

La première commande indique si une release plus récente est disponible. La seconde la télécharge, la vérifie et l'installe sur place. Sous Windows, l'ancien binaire reste à côté du nouveau sous le nom resterm.exe.old et est nettoyé lors de la prochaine mise à jour.

Configuration

• Les environnements sont des fichiers JSON (resterm.env.json) découverts dans le répertoire des requêtes, la racine de l'espace de travail ou le répertoire de travail courant (CWD). Un fichier peut définir des environnements nommés ou des groupes indépendants, par exemple api, app et credentials, qui se combinent en un seul environnement. Les fichiers Dotenv (.env, .env.*) sont activés explicitement via --env-file et sont propres à un seul espace de travail. Voir environnements groupés et l'exemple exécutable dans _examples/grouped/.
• La configuration est stockée par système d'exploitation et peut être remplacée avec RESTERM_CONFIG_DIR :
  • macOS : ~/Library/Application Support/resterm
  • Windows : %APPDATA%\resterm
  • Linux/Unix : ~/.config/resterm

Collections

Exportez un espace de travail sous forme de bundle compatible Git et importez-le dans un autre. Les bundles contiennent un manifest.json avec des sommes de contrôle, afin que les importations vérifient d'abord l'intégrité des fichiers. Les valeurs d'environnement sont exportées sous forme d'espaces réservés REPLACE_ME, de sorte que les secrets ne quittent jamais votre machine.

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

Ajoutez --dry-run pour prévisualiser une importation et --force pour écraser les fichiers existants. Documentation : partage de collections.

Import curl

Collez une commande curl dans l'éditeur et appuyez sur Ctrl+Enter pour la transformer en requête structurée. Resterm comprend les options courantes, fusionne les segments de données répétés et préserve les téléversements multipart. Les préfixes shell comme sudo ou $ sont ignorés. La CLI effectue la même conversion avec --from-curl.

Ceci :

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

devient ceci :

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

{"user":"demo"}

Documentation : requêtes inline et exemples d'importation.

RestermScript

RestermScript (RTS) est un petit langage d'expressions conçu pour Resterm. Il cible directement le format de requête, les workflows et les directives, ce qui maintient les scripts courts et prévisibles. Les hooks JavaScript restent disponibles lorsque vous avez besoin de plus.

Exemple rapide (module RTS + requête) :

// 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")) }}

Référence complète : docs/restermscript.md.

Plongée en profondeur

OAuth 2.0

Client credentials, password grant et code d'autorisation avec PKCE. Pour les flux par code d'autorisation, Resterm ouvre votre navigateur, exécute un serveur de rappel local sur 127.0.0.1, capture la redirection et échange le code. Les jetons sont mis en cache par environnement et rafraîchis à leur expiration. Documentation : docs/resterm.md#oauth-20-directive et _examples/oauth2.http.

Workflows et scripts

Enchaînez des requêtes avec @workflow et @step, transmettez des données entre les étapes et ajoutez des hooks JS si nécessaire. Documentation et exemple : docs/resterm.md#workflows et _examples/workflows.http.

Comparer des exécutions

Exécutez la même requête dans différents environnements avec @compare ou --compare, puis faites un diff des réponses côte à côte avec g+c. Documentation : docs/resterm.md#compare-runs.

Tracing et timeline

Ajoutez @trace avec des budgets pour capturer les temps de DNS, de connexion, TLS, TTFB et de transfert. Resterm met en évidence les dépassements de budget et peut exporter des spans vers OpenTelemetry. Documentation : docs/resterm.md#timeline--tracing.

Streaming (WebSocket et SSE)

Utilisez @websocket avec les étapes @ws ou @sse pour scripter et enregistrer des flux. L'onglet Stream conserve les transcriptions et inclut une console interactive. Documentation : docs/resterm.md#streaming-sse--websocket.

gRPC

Appels unaires et streaming avec transcriptions, métadonnées et expansion du corps. Documentation : docs/resterm.md#grpc.

Import OpenAPI

Convertissez des spécifications OpenAPI 3 en collections .http avec --from-openapi, à partir d'un fichier local ou d'une URL http(s). Choisissez les blocs générés avec --openapi-mode requests, mocks ou both. Les récupérations distantes respectent les options globales --insecure et --proxy. Documentation : docs/cli.md#import-examples.

Tunnels SSH

Acheminez le trafic HTTP, gRPC, WebSocket et SSE à travers des bastions avec les profils @ssh. Documentation : docs/resterm.md#ssh-tunnels et _examples/ssh.http.

Redirections de ports Kubernetes

Même principe avec les profils @k8s, ciblant des pods, services, deployments ou statefulsets. Documentation : docs/resterm.md#kubernetes-port-forwards et _examples/k8s.http.

Thèmes et raccourcis (bindings)

Personnalisez les couleurs et les raccourcis clavier avec themes/*.toml et bindings.toml ou bindings.json dans le répertoire de configuration. Documentation : docs/resterm.md#theming et docs/resterm.md#custom-bindings.

Documentation

• docs/resterm.md couvre la syntaxe des requêtes, les directives, les scripts et les transports.
• docs/cli.md couvre resterm run, les importateurs, les collections et l'historique.
• Compatibilité explique les garanties de compatibilité de Resterm pour la v1.

Dans la TUI, appuyez sur ? ou exécutez :help. Utilisez :docs lorsque vous voulez le manuel web complet de la release installée.

Licence

Apache License 2.0.