Resterm

Un client API e workbench nativo per terminale per REST, GraphQL, gRPC, WebSocket e SSE.

Resterm è un workbench API-as-code - o, in termini più familiari, un client API - costruito attorno a semplici file .http e .rest che puoi confrontare, rivedere e versionare. Combina la modifica interattiva delle richieste con workflow dichiarativi, asserzioni, mock server, tracing, profiling e automazione headless. Tutto resta sulla tua macchina. Nessun account, nessuna sincronizzazione cloud, nessuna telemetria.

Se cerchi un client in stile Postman incentrato su raccolte con GUI, Resterm probabilmente non fa per te, ma provalo comunque!

[!NOTE] Resterm è ora alla v1! Consulta le note di rilascio della v1.0.0 per le nuove funzionalità e le modifiche incompatibili.

Link rapidi: Screenshot, Installazione, Avvio rapido, Documentazione.

Tour di screenshot

Perché Resterm

• HTTP, GraphQL, gRPC, WebSocket e SSE inclusi di serie.
• L'automazione vive nei file di richiesta: condizioni (@when, @if/@elif/@else, @for-each), workflow multi-step (@workflow / @step), catture, variabili e asserzioni (@capture, @var, @assert).
• RestermScript, un piccolo linguaggio di espressioni creato per Resterm, con hook JavaScript quando ti servono.
• Controlli in stile Vim con suggerimenti contestuali nella barra inferiore, help offline ricercabile, help K sotto il cursore, ricerca con / e comandi come :w, , e .

Avvio rapido

1. Installa Resterm (vedi Installazione per script, Windows e installazioni manuali).

   root@kitploit:~

   brew install resterm
   

2. Prepara un workspace.

   root@kitploit:~

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

   resterm init ti fornisce un piccolo progetto che funziona senza connessione internet. Il requests.http generato include scenari mock locali e alcune richieste che si basano l'una sull'altra. Coprono asserzioni, autenticazione bearer, matching JSON, json-rules e @for-each.

3. Avvialo e invia la tua prima richiesta.

   root@kitploit:~

   resterm
   

   Premi Ctrl+Enter nell'editor per inviare la richiesta evidenziata.

Non hai ancora file? Basta eseguire resterm, digitare un URL e premere Ctrl+Enter. Funziona anche un comando curl incollato.

CLI

resterm run esegue i file .http / .rest senza aprire la TUI, ovvero ciò che viene eseguito in CI.

resterm run --request CreateUser requests.http

Il progetto generato comunica con un mock server locale. Avvialo prima in un altro terminale:

resterm mock requests.http

Nella TUI, premi g Shift+M per avviare invece lo stesso mock server dal workspace.

La documentazione CLI copre i selettori, i formati di output e altri esempi.

Mock Server

Gli stessi file che contengono le tue richieste possono servire mock HTTP.

• Abbina le richieste in arrivo in base a query, header o corpo JSON, poi scegli una risposta nominata o predefinita.
• Modella flussi di polling e retry con sequenze di risposte, inclusi cursori indipendenti per risorsa o chiamante.
• Ritarda le risposte di una quantità fissa, oppure assegna a ogni richiesta un ritardo diverso con random, normal o jitter.
• Costruisci risposte a partire da valori di path, query, header e body, con generatori per dati dinamici.
• Verifica il numero di chiamate con @expect o ispeziona il traffico ricevuto da RestermScript.
• Ricarica a caldo file sorgente e fixture, con TLS opzionale.

Due scenari su una stessa 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"}

Servi un singolo file o un'intera directory:

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

Maggiori dettagli nel riferimento dei Mock Server, nella guida CLI resterm mock e nell'esempio funzionante.

Headless

Il pacchetto headless è l'API Go pubblica dello stesso motore che alimenta la TUI e la CLI. Usalo per eseguire richieste, workflow, asserzioni, confronti di esecuzioni e profili dal tuo codice Go o dalla CI.

Se preferisci non costruire un runner da solo, esiste resterm-runner.

Cheat sheet della tastiera

• Focus e layout dei pannelli
  • Tab / Shift+Tab: spostati tra sidebar, editor e risposta.
  • g+r, g+i, g+p: vai a richieste, editor o risposta.
  • g+h / g+l: ridimensiona in orizzontale. Cambia la larghezza della sidebar quando la sidebar è focalizzata, altrimenti la divisione editor/risposta.
  • g+j / g+k: ridimensiona l'altezza di editor/risposta quando sono impilati, comprime o espande i rami nel navigatore.
  • g+v / g+s: alterna il pannello della risposta tra layout inline e impilato.
  • g+1, g+2, g+3: minimizza o ripristina sidebar, editor, risposta.

[!TIP] Se devi ricordare solo tre scorciatoie:

• Ctrl+Enter invia la richiesta
• Tab / Shift+Tab cambia pannello
• g+p passa alla risposta

Installazione

Linux / macOS (Homebrew)

brew install resterm

[!NOTE] Le installazioni Homebrew vanno aggiornate con Homebrew (brew upgrade resterm). Il comando integrato resterm --update è destinato ai binari installati dalle release GitHub o dagli script di installazione.

Linux / macOS (Shell script)

[!IMPORTANT] I binari Linux precompilati dipendono da glibc 2.32 o successiva. Su una distro più vecchia, compila dal sorgente con una toolchain glibc più recente o aggiorna glibc prima di usare gli archivi di release.

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

oppure con 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

Gli script rilevano la tua architettura, scaricano l'ultima release e installano il binario.

Installazione manuale

[!NOTE] Lo script di installazione manuale usa curl e jq. Installa jq con il tuo gestore di pacchetti (brew install jq, sudo apt install jq, ecc.).

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"

Dal sorgente

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

Aggiornamento

resterm --check-update
resterm --update

Il primo comando segnala se è disponibile una release più recente. Il secondo la scarica, la verifica e la installa al suo posto. Su Windows, il vecchio binario resta accanto al nuovo come resterm.exe.old e viene rimosso all'aggiornamento successivo.

Configurazione

• Gli ambienti sono file JSON (resterm.env.json) individuati nella directory delle richieste, nella radice del workspace o nella CWD. Un file può definire ambienti nominati o gruppi indipendenti, ad esempio api, app e credentials, che si combinano in un unico ambiente. I file dotenv (.env, .env.*) sono facoltativi tramite --env-file e valgono per un singolo workspace. Vedi ambienti raggruppati e l'esempio eseguibile in _examples/grouped/.
• La configurazione è archiviata per sistema operativo e può essere sovrascritta con RESTERM_CONFIG_DIR:
  • macOS: ~/Library/Application Support/resterm
  • Windows: %APPDATA%\resterm
  • Linux/Unix: ~/.config/resterm

Raccolte

Esporta un workspace come bundle Git-friendly e importalo in un altro. I bundle includono un manifest.json con checksum, quindi le importazioni verificano prima l'integrità dei file. I valori degli ambienti vengono esportati come segnaposto REPLACE_ME, così i segreti non lasciano mai la tua macchina.

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

Aggiungi --dry-run per vedere in anteprima un'importazione e --force per sovrascrivere i file esistenti. Documentazione: condivisione delle raccolte.

Importazione da curl

Incolla un comando curl nell'editor e premi Ctrl+Enter per trasformarlo in una richiesta strutturata. Resterm comprende i flag comuni, unisce i segmenti di dati ripetuti e mantiene intatti gli upload multipart. I prefissi di shell come sudo o $ vengono ignorati. La CLI esegue la stessa conversione con --from-curl.

Questo:

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

diventa questo:

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

{"user":"demo"}

Documentazione: richieste inline ed esempi di importazione.

RestermScript

RestermScript (RTS) è un piccolo linguaggio di espressioni creato per Resterm. Punta direttamente al formato delle richieste, ai workflow e alle direttive, il che mantiene gli script brevi e prevedibili. Gli hook JavaScript restano disponibili quando ti serve di più.

Esempio rapido (modulo RTS + richiesta):

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

Riferimento completo: docs/restermscript.md.

Approfondimento

OAuth 2.0

Client credentials, password grant e authorization code con PKCE. Per i flussi con authorization code, Resterm apre il browser, avvia un server di callback locale su 127.0.0.1, cattura il redirect e scambia il codice. I token vengono memorizzati nella cache per ambiente e aggiornati quando scadono. Documentazione: docs/resterm.md#oauth-20-directive ed _examples/oauth2.http.

Workflow e scripting

Collega le richieste con @workflow e @step, passa dati tra i passaggi e aggiungi hook JS dove servono. Documentazione ed esempio: docs/resterm.md#workflows ed _examples/workflows.http.

Confronto delle esecuzioni

Esegui la stessa richiesta in più ambienti con @compare o --compare, poi confronta le risposte fianco a fianco con g+c. Documentazione: docs/resterm.md#compare-runs.

Tracing e timeline

Aggiungi @trace con budget per catturare i tempi di DNS, connessione, TLS, TTFB e trasferimento. Resterm evidenzia gli sforamenti e può esportare gli span verso OpenTelemetry. Documentazione: docs/resterm.md#timeline--tracing.

Streaming (WebSocket e SSE)

Usa @websocket con passaggi @ws o @sse per scriptare e registrare gli stream. La scheda Stream conserva le trascrizioni e include una console interattiva. Documentazione: docs/resterm.md#streaming-sse--websocket.

gRPC

Chiamate unary e streaming con trascrizioni, metadati ed espansione del body. Documentazione: docs/resterm.md#grpc.

Importazione OpenAPI

Converti le specifiche OpenAPI 3 in raccolte .http con --from-openapi, da un file locale o da un URL http(s). Scegli i blocchi generati con --openapi-mode requests, mocks o both. I fetch remoti rispettano i flag globali --insecure e --proxy. Documentazione: docs/cli.md#import-examples.

Tunnel SSH

Instrada il traffico HTTP, gRPC, WebSocket e SSE attraverso i bastion con i profili @ssh. Documentazione: docs/resterm.md#ssh-tunnels ed _examples/ssh.http.

Port-forward Kubernetes

Stessa idea con i profili @k8s, che puntano a pod, service, deployment o statefulset. Documentazione: docs/resterm.md#kubernetes-port-forwards ed _examples/k8s.http.

Temi e scorciatoie

Personalizza colori e scorciatoie da tastiera con themes/*.toml e bindings.toml o bindings.json nella directory di configurazione. Documentazione: docs/resterm.md#theming e docs/resterm.md#custom-bindings.

Documentazione

• docs/resterm.md copre la sintassi delle richieste, le direttive, lo scripting e i transport.
• docs/cli.md copre resterm run, gli importatori, le raccolte e la cronologia.
• Compatibilità spiega le garanzie di compatibilità di Resterm per la v1.

Nella TUI, premi ? o esegui :help. Usa :docs quando vuoi il manuale web completo per la release installata.

Licenza

Apache License 2.0.