Resterm

Un cliente de API y banco de trabajo nativo de terminal para REST, GraphQL, gRPC, WebSocket y SSE.

Resterm es un banco de trabajo API-como-código — o, en términos más familiares, un cliente de API — construido alrededor de archivos .http y .rest simples que puedes comparar (diff), revisar y versionar. Combina la edición interactiva de solicitudes con flujos de trabajo declarativos, aserciones, servidores mock, trazado, perfilado y automatización headless. Todo permanece en tu máquina. Sin cuentas, sin sincronización en la nube, sin telemetría.

Si buscas un cliente estilo Postman centrado en colecciones GUI, Resterm probablemente no sea para ti, ¡pero pruébalo de todos modos!

[!NOTE] Resterm ahora es v1. Consulta las notas de la versión v1.0.0 para conocer las nuevas funciones y los cambios importantes.

Enlaces rápidos: Capturas de pantalla, Instalación, Inicio rápido, Documentación.

Tour de capturas de pantalla

Por qué Resterm

• HTTP, GraphQL, gRPC, WebSocket y SSE incluidos de serie.
• La automatización vive en los archivos de solicitud: condiciones (@when, @if/@elif/@else, @for-each), flujos de trabajo de varios pasos (@workflow / @step), capturas, variables y aserciones (@capture, @var, @assert).
• RestermScript, un pequeño lenguaje de expresiones creado para Resterm, con hooks de JavaScript cuando los necesites.
• Controles estilo Vim con sugerencias contextuales en la barra inferior, ayuda offline buscable, ayuda K bajo el cursor, búsqueda / y comandos como :w, , y .

Inicio rápido

1. Instala Resterm (consulta Instalación para scripts, Windows e instalaciones manuales).

   root@kitploit:~

   brew install resterm
   

2. Inicializa un espacio de trabajo.

   root@kitploit:~

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

   resterm init te proporciona un pequeño proyecto que funciona sin conexión a internet. El requests.http generado incluye escenarios mock locales y algunas solicitudes que se apoyan entre sí. Cubren aserciones, autenticación bearer, coincidencia JSON, json-rules y @for-each.

3. Inícialo y envía tu primera solicitud.

   root@kitploit:~

   resterm
   

   Pulsa Ctrl+Enter en el editor para enviar la solicitud resaltada.

¿Aún no tienes archivos? Simplemente ejecuta resterm, escribe una URL y pulsa Ctrl+Enter. Un comando curl pegado también funciona.

CLI

resterm run ejecuta archivos .http / .rest sin abrir la TUI, que es lo que ejecuta el CI.

resterm run --request CreateUser requests.http

El proyecto generado se comunica con un servidor mock local. Inícialo primero en otra terminal:

resterm mock requests.http

En la TUI, pulsa g Shift+M para iniciar el mismo servidor mock desde el espacio de trabajo.

La documentación de CLI cubre selectores, formatos de salida y más ejemplos.

Servidores mock

Los mismos archivos que contienen tus solicitudes pueden servir mocks HTTP.

• Haz coincidir solicitudes entrantes por query, cabeceras o cuerpo JSON, y luego elige una respuesta nombrada o por defecto.
• Modela flujos de polling y reintentos con secuencias de respuestas, incluidos cursores independientes por recurso o llamador.
• Retrasa las respuestas una cantidad fija, o da a cada solicitud un retraso diferente con random, normal o jitter.
• Construye respuestas a partir de valores de path, query, cabeceras y cuerpo, con generadores para datos dinámicos.
• Verifica contadores de llamadas con @expect o inspecciona el tráfico recibido desde RestermScript.
• Recarga en caliente archivos fuente y fixtures, con TLS opcional.

Dos escenarios en una misma ruta:

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

Sirve un archivo o un directorio completo:

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

Más en la referencia de servidores mock, la guía CLI de resterm mock y el ejemplo funcional.

Headless

El paquete headless es la API pública de Go para el mismo motor que impulsa la TUI y la CLI. Úsalo para ejecutar solicitudes, flujos de trabajo, aserciones, comparar ejecuciones y perfiles desde tu propio código Go o CI.

Si prefieres no construir tu propio ejecutor, está resterm-runner.

Chuleta de teclado

• Enfoque y diseño de paneles
  • Tab / Shift+Tab: muévete entre la barra lateral, el editor y la respuesta.
  • g+r, g+i, g+p: salta a solicitudes, editor o respuesta.
  • g+h / g+l: redimensiona horizontalmente. Cambia el ancho de la barra lateral cuando está enfocada, o la división editor/respuesta en caso contrario.
  • g+j / g+k: redimensiona la altura del editor/respuesta cuando están apilados, colapsa o expande ramas en el navegador.
  • g+v / g+s: alterna el panel de respuesta entre diseño en línea y apilado.
  • g+1, g+2, g+3: minimiza o restaura la barra lateral, el editor y la respuesta.

[!TIP] Si solo recuerdas tres atajos:

• Ctrl+Enter envía la solicitud
• Tab / Shift+Tab cambia de panel
• g+p salta a la respuesta

Instalación

Linux / macOS (Homebrew)

brew install resterm

[!NOTE] Las instalaciones de Homebrew deben actualizarse con Homebrew (brew upgrade resterm). El comando integrado resterm --update es para binarios instalados desde releases de GitHub o scripts de instalación.

Linux / macOS (Script de shell)

[!IMPORTANT] Los binarios de Linux precompilados dependen de glibc 2.32 o superior. En una distro más antigua, compila desde el código fuente con una toolchain de glibc más nueva o actualiza glibc antes de usar los archivos de release.

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

o 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

Los scripts detectan tu arquitectura, descargan la última release e instalan el binario.

Instalación manual

[!NOTE] El asistente de instalación manual usa curl y jq. Instala jq con tu gestor de paquetes (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"

Desde el código fuente

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

Actualización

resterm --check-update
resterm --update

El primer comando informa si hay una release más reciente disponible. El segundo la descarga, verifica e instala en su lugar. En Windows, el binario antiguo permanece junto al nuevo como resterm.exe.old y se limpia en la siguiente actualización.

Configuración

• Los entornos son archivos JSON (resterm.env.json) detectados en el directorio de solicitudes, la raíz del espacio de trabajo o el directorio de trabajo actual (CWD). Un archivo puede definir entornos con nombre o grupos independientes, por ejemplo api, app y credentials, que se combinan en un único entorno. Los archivos Dotenv (.env, .env.*) son opcionales mediante --env-file y son de un solo espacio de trabajo. Consulta entornos agrupados y el ejemplo ejecutable en _examples/grouped/.
• La configuración se almacena por sistema operativo y se puede sobrescribir con RESTERM_CONFIG_DIR:
  • macOS: ~/Library/Application Support/resterm
  • Windows: %APPDATA%\resterm
  • Linux/Unix: ~/.config/resterm

Colecciones

Exporta un espacio de trabajo como un bundle compatible con Git e impórtalo en otro. Los bundles incluyen un manifest.json con checksums, por lo que las importaciones verifican primero la integridad de los archivos. Los valores de entorno se exportan como placeholders REPLACE_ME, para que los secretos nunca salgan de tu máquina.

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

Añade --dry-run para previsualizar una importación y --force para sobrescribir archivos existentes. Documentación: compartición de colecciones.

Importación de curl

Pega un comando curl en el editor y pulsa Ctrl+Enter para convertirlo en una solicitud estructurada. Resterm entiende las flags comunes, fusiona segmentos de datos repetidos y mantiene intactas las subidas multipart. Los prefijos de shell como sudo o $ se ignoran. La CLI hace la misma conversión con --from-curl.

Esto:

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

se convierte en esto:

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

{"user":"demo"}

Documentación: solicitudes en línea y ejemplos de importación.

RestermScript

RestermScript (RTS) es un pequeño lenguaje de expresiones creado para Resterm. Apunta directamente al formato de solicitud, los flujos de trabajo y las directivas, lo que mantiene los scripts cortos y predecibles. Los hooks de JavaScript siguen disponibles cuando necesitas más.

Ejemplo rápido (módulo RTS + solicitud):

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

Referencia completa: docs/restermscript.md.

Inmersión profunda

OAuth 2.0

Credenciales de cliente, concesión de contraseña y código de autorización con PKCE. Para los flujos de código de autorización, Resterm abre tu navegador, ejecuta un servidor de callback local en 127.0.0.1, captura la redirección e intercambia el código. Los tokens se almacenan en caché por entorno y se refrescan cuando expiran. Documentación: docs/resterm.md#oauth-20-directive y _examples/oauth2.http.

Flujos de trabajo y scripting

Encadena solicitudes con @workflow y @step, pasa datos entre pasos y añade hooks JS donde sea necesario. Documentación y ejemplo: docs/resterm.md#workflows y _examples/workflows.http.

Comparar ejecuciones

Ejecuta la misma solicitud en distintos entornos con @compare o --compare, y luego compara las respuestas lado a lado con g+c. Documentación: docs/resterm.md#compare-runs.

Trazado y línea de tiempo

Añade @trace con presupuestos para capturar tiempos de DNS, conexión, TLS, TTFB y transferencia. Resterm resalta las sobreejecuciones y puede exportar spans a OpenTelemetry. Documentación: docs/resterm.md#timeline--tracing.

Streaming (WebSocket y SSE)

Usa @websocket con pasos @ws o @sse para scriptear y grabar streams. La pestaña Stream conserva transcripciones e incluye una consola interactiva. Documentación: docs/resterm.md#streaming-sse--websocket.

gRPC

Llamadas unarias y de streaming con transcripciones, metadatos y expansión de cuerpo. Documentación: docs/resterm.md#grpc.

Importación OpenAPI

Convierte especificaciones OpenAPI 3 en colecciones .http con --from-openapi, desde un archivo local o una URL http(s). Elige los bloques generados con --openapi-mode requests, mocks o both. Las descargas remotas respetan las flags globales --insecure y --proxy. Documentación: docs/cli.md#import-examples.

Túneles SSH

Enruta tráfico HTTP, gRPC, WebSocket y SSE a través de bastiones con perfiles @ssh. Documentación: docs/resterm.md#ssh-tunnels y _examples/ssh.http.

Kubernetes port-forwards

La misma idea con perfiles @k8s, dirigidos a pods, services, deployments o statefulsets. Documentación: docs/resterm.md#kubernetes-port-forwards y _examples/k8s.http.

Temas y bindings

Personaliza colores y atajos de teclado con themes/*.toml y bindings.toml o bindings.json en el directorio de configuración. Documentación: docs/resterm.md#theming y docs/resterm.md#custom-bindings.

Documentación

• docs/resterm.md cubre la sintaxis de solicitudes, directivas, scripting y transportes.
• docs/cli.md cubre resterm run, importadores, colecciones e historial.
• Compatibilidad explica las garantías de compatibilidad de Resterm para v1.

Dentro de la TUI, pulsa ? o ejecuta :help. Usa :docs cuando quieras el manual web completo de la release instalada.

Licencia

Apache License 2.0.