Resterm

Ein terminalnativer API-Client und eine Arbeitsumgebung für REST, GraphQL, gRPC, WebSocket und SSE.

Resterm ist eine API-as-code-Arbeitsumgebung – oder, in vertrauteren Begriffen, ein API-Client –, die um einfache .http- und .rest-Dateien herum aufgebaut ist, die du diffen, reviewen und versionieren kannst. Sie kombiniert interaktive Request-Bearbeitung mit deklarativen Workflows, Assertions, Mock-Servern, Tracing, Profiling und Headless-Automatisierung. Alles bleibt auf deinem Rechner. Keine Konten, keine Cloud-Synchronisierung, keine Telemetrie.

Wenn du nach einem Client im Postman-Stil suchst, der sich auf GUI-Sammlungen konzentriert, ist Resterm wahrscheinlich nicht das Richtige für dich – aber probier es trotzdem aus!

[!NOTE] Resterm ist jetzt v1! Siehe die v1.0.0-Releasehinweise für neue Funktionen und Breaking Changes.

Schnellzugriff: Screenshots, Installation, Schnellstart, Dokumentation.

Screenshot-Tour

Warum Resterm

• HTTP, GraphQL, gRPC, WebSocket und SSE von Haus aus.
• Die Automatisierung lebt in den Request-Dateien: Bedingungen (@when, @if/@elif/@else, @for-each), mehrstufige Workflows (@workflow / @step), Captures, Variablen und Assertions (@capture, @var, @assert).
• RestermScript, eine kleine, für Resterm entwickelte Ausdruckssprache, mit JavaScript-Hooks, wenn du sie brauchst.
• Vim-ähnliche Bedienung mit kontextuellen Hinweisen in der unteren Leiste, durchsuchbarer Offline-Hilfe, K-Hilfe unter dem Cursor, /-Suche und Befehlen wie :w, , und .

Schnellstart

1. Installiere Resterm (siehe Installation für Skripte, Windows und manuelle Installationen).

   root@kitploit:~

   brew install resterm
   

2. Lege einen Workspace an.

   root@kitploit:~

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

   resterm init erstellt dir ein kleines Projekt, das ohne Internetverbindung funktioniert. Die generierte requests.http enthält lokale Mock-Szenarien und einige Requests, die aufeinander aufbauen. Sie decken Assertions, Bearer-Auth, JSON-Matching, json-rules und @for-each ab.

3. Starte Resterm und sende deinen ersten Request.

   root@kitploit:~

   resterm
   

   Drücke im Editor Ctrl+Enter, um den markierten Request zu senden.

Noch keine Dateien? Starte einfach resterm, gib eine URL ein und drücke Ctrl+Enter. Auch ein eingefügter curl-Befehl funktioniert.

CLI

resterm run führt .http- / .rest-Dateien aus, ohne die TUI zu öffnen – genau das, was CI ausführt.

resterm run --request CreateUser requests.http

Das generierte Projekt spricht mit einem lokalen Mock-Server. Starte ihn zuerst in einem anderen Terminal:

resterm mock requests.http

Drücke in der TUI stattdessen g Shift+M, um denselben Mock-Server aus dem Workspace zu starten.

Die CLI-Dokumentation behandelt Selektoren, Ausgabeformate und weitere Beispiele.

Mock-Server

Dieselben Dateien, die deine Requests enthalten, können HTTP-Mocks ausliefern.

• Erkenne eingehende Requests anhand von Query, Headern oder JSON-Body und wähle dann eine benannte oder Standard-Antwort.
• Bilde Polling- und Retry-Abläufe mit Antwortsequenzen ab, einschließlich unabhängiger Cursor pro Ressource oder Aufrufer.
• Verzögere Antworten um einen festen Betrag oder gib jedem Request mit random, normal oder jitter eine andere Verzögerung.
• Erzeuge Antworten aus Pfad-, Query-, Header- und Body-Werten, mit Generatoren für dynamische Daten.
• Verifiziere Aufrufanzahlen mit @expect oder untersuche empfangenen Datenverkehr aus RestermScript.
• Hot Reload für Quelldateien und Fixtures, mit optionalem TLS.

Zwei Szenarien auf einer 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"}

Eine Datei oder ein ganzes Verzeichnis ausliefern:

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

Mehr in der Mock-Server-Referenz, im resterm mock-CLI-Leitfaden und im funktionierenden Beispiel.

Headless

Das headless-Paket ist die öffentliche Go-API für dieselbe Engine, die TUI und CLI antreibt. Nutze sie, um Requests, Workflows, Assertions, Vergleichsläufe und Profile aus deinem eigenen Go-Code oder aus CI auszuführen.

Wenn du lieber keinen eigenen Runner bauen möchtest, gibt es resterm-runner.

Tastatur-Spickzettel

• Pane-Fokus und Layout
  • Tab / Shift+Tab: Zwischen Sidebar, Editor und Antwort wechseln.
  • g+r, g+i, g+p: Zu Requests, Editor oder Antwort springen.
  • g+h / g+l: Horizontale Größenänderung. Ändert die Sidebar-Breite, wenn die Sidebar fokussiert ist, andernfalls die Editor/Antwort-Aufteilung.
  • g+j / g+k: Höhe von Editor/Antwort bei gestapelter Ansicht ändern, Zweige im Navigator einklappen oder aufklappen.
  • g+v / g+s: Den Antwortbereich zwischen Inline- und gestapeltem Layout umschalten.
  • g+1, g+2, g+3: Sidebar, Editor oder Antwort minimieren oder wiederherstellen.

[!TIP] Wenn du dir nur drei Tastenkürzel merkst:

• Ctrl+Enter sendet den Request
• Tab / Shift+Tab wechselt die Panes
• g+p springt zur Antwort

Installation

Linux / macOS (Homebrew)

brew install resterm

[!NOTE] Homebrew-Installationen sollten mit Homebrew aktualisiert werden (brew upgrade resterm). Der integrierte Befehl resterm --update ist für Binärdateien gedacht, die aus GitHub-Releases oder über Installationsskripte installiert wurden.

Linux / macOS (Shell-Skript)

[!IMPORTANT] Vorgefertigte Linux-Binärdateien sind auf glibc 2.32 oder neuer angewiesen. Verwende bei einer älteren Distribution eine neuere glibc-Toolchain, um aus dem Quellcode zu bauen, oder aktualisiere glibc, bevor du die Release-Archive verwendest.

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

oder mit 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

Die Skripte erkennen deine Architektur, laden das neueste Release herunter und installieren die Binärdatei.

Manuelle Installation

[!NOTE] Der Helfer für die manuelle Installation verwendet curl und jq. Installiere jq mit deinem Paketmanager (brew install jq, sudo apt install jq usw.).

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"

Aus dem Quellcode

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

Update

resterm --check-update
resterm --update

Der erste Befehl meldet, ob ein neueres Release verfügbar ist. Der zweite lädt es herunter, verifiziert es und installiert es an Ort und Stelle. Unter Windows bleibt die alte Binärdatei neben der neuen als resterm.exe.old erhalten und wird beim nächsten Update bereinigt.

Konfiguration

• Umgebungen sind JSON-Dateien (resterm.env.json), die im Request-Verzeichnis, im Workspace-Root oder im aktuellen Arbeitsverzeichnis gefunden werden. Eine Datei kann benannte Umgebungen oder unabhängige Gruppen definieren, zum Beispiel api, app und credentials, die sich zu einer Umgebung kombinieren. Dotenv-Dateien (.env, .env.*) werden optional über --env-file aktiviert und gelten für einen einzelnen Workspace. Siehe gruppierte Umgebungen und das ausführbare Beispiel in _examples/grouped/.
• Die Konfiguration wird pro Betriebssystem gespeichert und kann mit RESTERM_CONFIG_DIR überschrieben werden:
  • macOS: ~/Library/Application Support/resterm
  • Windows: %APPDATA%\resterm
  • Linux/Unix: ~/.config/resterm

Collections

Exportiere einen Workspace als Git-freundliches Bundle und importiere es in ein anderes. Bundles enthalten eine manifest.json mit Prüfsummen, sodass Importe zuerst die Dateiintegrität prüfen. Umgebungswerte werden als REPLACE_ME-Platzhalter exportiert, sodass Geheimnisse deinen Rechner nie verlassen.

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

Füge --dry-run hinzu, um einen Import in der Vorschau anzusehen, und --force, um vorhandene Dateien zu überschreiben. Doku: Collection-Sharing.

Curl-Import

Füge einen curl-Befehl in den Editor ein und drücke Ctrl+Enter, um ihn in einen strukturierten Request umzuwandeln. Resterm versteht die gängigen Flags, führt wiederholte Datensegmente zusammen und erhält Multipart-Uploads intakt. Shell-Präfixe wie sudo oder $ werden ignoriert. Die CLI führt dieselbe Konvertierung mit --from-curl durch.

Das hier:

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

wird zu:

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

{"user":"demo"}

Doku: Inline-Requests und Importbeispiele.

RestermScript

RestermScript (RTS) ist eine kleine, für Resterm entwickelte Ausdruckssprache. Sie zielt direkt auf das Request-Format, Workflows und Direktiven ab, was Skripte kurz und vorhersehbar hält. JavaScript-Hooks bleiben verfügbar, wenn du mehr brauchst.

Kurzes Beispiel (RTS-Modul + Request):

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

Vollständige Referenz: docs/restermscript.md.

Vertiefung

OAuth 2.0

Client-Credentials, Password-Grant und Autorisierungscode mit PKCE. Bei Auth-Code-Abläufen öffnet Resterm deinen Browser, startet einen lokalen Callback-Server auf 127.0.0.1, erfasst die Weiterleitung und tauscht den Code um. Tokens werden pro Umgebung zwischengespeichert und bei Ablauf erneuert. Doku: docs/resterm.md#oauth-20-directive und _examples/oauth2.http.

Workflows und Skripting

Verkette Requests mit @workflow und @step, gib Daten zwischen Schritten weiter und füge bei Bedarf JS-Hooks hinzu. Doku und Beispiel: docs/resterm.md#workflows und _examples/workflows.http.

Vergleichsläufe

Führe denselben Request mit @compare oder --compare über Umgebungen hinweg aus und vergleiche die Antworten dann mit g+c nebeneinander. Doku: docs/resterm.md#compare-runs.

Tracing und Timeline

Füge @trace mit Budgets hinzu, um DNS-, Connect-, TLS-, TTFB- und Transfer-Zeiten zu erfassen. Resterm hebt Überschreitungen hervor und kann Spans nach OpenTelemetry exportieren. Doku: docs/resterm.md#timeline--tracing.

Streaming (WebSocket und SSE)

Verwende @websocket mit @ws-Schritten oder @sse, um Streams zu skripten und aufzuzeichnen. Der Stream-Tab speichert Transkripte und enthält eine interaktive Konsole. Doku: docs/resterm.md#streaming-sse--websocket.

gRPC

Unäre und Streaming-Aufrufe mit Transkripten, Metadaten und Body-Expansion. Doku: docs/resterm.md#grpc.

OpenAPI-Import

Konvertiere OpenAPI-3-Spezifikationen mit --from-openapi in .http-Collections, aus einer lokalen Datei oder einer http(s)-URL. Wähle die erzeugten Blöcke mit --openapi-mode requests, mocks oder both. Remote-Abrufe respektieren die globalen Flags --insecure und --proxy. Doku: docs/cli.md#import-examples.

SSH-Tunnel

Leite HTTP-, gRPC-, WebSocket- und SSE-Datenverkehr mit @ssh-Profilen durch Bastion-Hosts. Doku: docs/resterm.md#ssh-tunnels und _examples/ssh.http.

Kubernetes-Port-Forwards

Dasselbe Konzept mit @k8s-Profilen, die auf Pods, Services, Deployments oder StatefulSets abzielen. Doku: docs/resterm.md#kubernetes-port-forwards und _examples/k8s.http.

Theming und Bindings

Passe Farben und Tastenkombinationen mit themes/*.toml und bindings.toml oder bindings.json im Konfigurationsverzeichnis an. Doku: docs/resterm.md#theming und docs/resterm.md#custom-bindings.

Dokumentation

• docs/resterm.md behandelt Request-Syntax, Direktiven, Skripting und Transports.
• docs/cli.md behandelt resterm run, Importeure, Collections und Verlauf.
• Kompatibilität erklärt Resterm-Kompatibilitätszusagen für v1.

Drücke in der TUI ? oder führe :help aus. Verwende :docs, wenn du das vollständige Web-Handbuch für die installierte Version möchtest.

Lizenz

Apache License 2.0.