Resterm

a terminal-based REST/GraphQL/gRPC/WebSocket/SSE client.

Trace and Timeline

Workflow and WebSocket

Profiler

OAuth browser demo

Resterm is a terminal client for working with HTTP, GraphQL, gRPC, WebSocket and SSE. No cloud sync, no signups, no heavy desktop app. If you live on the keyboard - this is your home.

TL;DR why resterm:

• Resterm is keyboard driven.
• Everything lives in plain files (.http/.rest) - no cloud or account - everything stays local.
• Built-in SSH tunnels for HTTP/gRPC/WebSocket/SSE.
• OAuth 2.0 built-in - client credentials, password grant, authorization code + PKCE with automatic browser flow and token refresh.
• Fast iteration loop with explorer + history + diff/compare + captures/workflows.
• Debuggable - timeline tracing, profiler, streaming transcripts and inline scripts/tests.

Index

Up & Running

• Features
• Installation
  • Quick Install
  • Manual Installation
• Update
• Quick Start
• Quick Configuration Overview

---

Deep dive

• OAuth 2.0
• Workflows & scripting
• Compare runs
• Tracing & timeline
• Streaming (WebSocket & SSE)
• OpenAPI import
• Theming & bindings
• SSH Tunnels
• Documentation

Features

• Workspace navigator that filters .http / .rest files, supports recursion and keeps request lists in sync as you edit.
• Editor with inline syntax highlighting, search (Ctrl+F), clipboard motions, and inline metadata completions (type @ for contextual hints).
• Variable scopes with @global (environment-wide), @var file (document), @var request (per-call), plus compile-time constants (@const), captures, JavaScript hooks, and multi-step workflows with per-step expectations and overrides.
• GraphQL helpers (@graphql, @variables, @query) and gRPC directives (@grpc, @grpc-descriptor, reflection, metadata).
• WebSockets and SSE with scripted @ws steps, automatic transcripts and an interactive console for ad-hoc frames.
• OpenAPI importer converts OpenAPI specs into Resterm-ready .http collections from the CLI.
• Inline requests and curl import for one-off calls (Ctrl+Enter on a URL or curl block).
• Pretty/Raw/Header/Diff/History/Stream views with optional split panes, pinned comparisons, and live event playback.
• OAuth 2.0 with automatic token management - client credentials, password grant, and authorization code + PKCE. Tokens are cached per environment, refreshed automatically, and injected into requests without manual steps.
• Latency with @profile to benchmark endpoints and render histograms right inside the TUI.
• Tracing and Timeline with @trace to enable request tracing.
• Multi-step workflows compose several named requests (@workflow + @step) with per-step overrides and expectations.
• Multi-environment compare via @compare directives or the global --compare flag.
• SSH tunnels route HTTP/gRPC/WebSocket/SSE traffic through bastions with host key verification, keep-alives, retries, and persistent tunnels.
• File Watcher with automatic file change detection: Resterm warns when the current file changes or goes missing on disk and lets you reload from disk (g Shift+R) or keep your buffer, plus a shortcut for quick workspace rescan (files) (g Shift+O).
• Custom theming & bindings if you want to make a resterm more alligned with your taste.

Installation

Quick Install

Linux / macOS:

Homebrew:

brew install resterm

Note

Homebrew installs should be updated with Homebrew (brew upgrade resterm). The built-in resterm --update command is for binaries installed from GitHub releases/install scripts (not via brew).

Shell script:

Important

Pre-built Linux binaries depend on glibc 2.32 or newer. If you run an older distro, build from source on a machine with a newer glibc toolchain or upgrade glibc before using the release archives.

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

or with 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

These scripts will automatically detect your architecture, download the latest release, and install the binary.

Manual Installation

Note

The manual install helper uses curl and jq. Install jq with your package manager (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"

From source

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

Update

resterm --check-update
resterm --update

The first command reports whether a newer release is available; the second downloads and installs it (Windows users receive a staged binary to swap on restart).

Quick Start

If you just want to hit an API right now, you don’t need any files.

1. Start Resterm

   # In a project directory (no files required)
   resterm
   
   # Or explicitly point to a workspace
   resterm --workspace path/to/project

2. Type a minimal request

   • Focus the editor pane (use Tab if needed).

   • Press i or a and type a simple request, for example:

     GET https://httpbin.org/status/204

3. Send it

   • Press Ctrl+Enter to send the request.
   • The response appears in the response pane on the right.

4. Move around

   • Tab / Shift+Tab - cycle focus between sidebar, editor, and response.
   • g+p - jump directly to the response pane.
   • g+i - jump back to the editor.

That’s enough to be productive: open Resterm, type a URL, hit Ctrl+Enter, see the response.

---

Quick Start (but with files)

If you work with .http / .rest files, Resterm will discover and use them.

1. Open a directory with request files

   • Create or open a directory that contains .http / .rest files (see _examples/ in this repo for samples).

   • Run:

     resterm
     # or
     resterm --workspace path/to/project

2. Pick and send a request

   • Use the sidebar to select a request from your .http / .rest files.
   • Press Ctrl+Enter to send it.
   • The response shows up in the right pane.

3. Minimal request file example

   ### Status check
   # @name status
   GET https://httpbin.org/status/204
   User-Agent: resterm
   
   ### Authenticated echo
   # @name bearerEcho
   # @auth bearer {{auth.token}}
   GET https://httpbin.org/bearer
   Accept: application/json

---

Navigation & Layout Cheat Sheet

A few keys that make Resterm feel “native” quickly:

• Pane focus & layout

  • Tab / Shift+Tab - move focus between sidebar, editor, and response.
  • g+r - jump to Requests (sidebar).
  • g+i - jump to Editor.
  • g+p - jump to Response.
  • g+h / g+l - adjust layout:
    • When the left pane (sidebar) is focused: change sidebar width.
    • Otherwise: change editor/response split.
  • g+v / g+s - toggle response pane between inline and stacked layout.
  • g+1, g+2, g+3 + minimize/restore sidebar, editor, response.
  • g+z / g+Z - zoom the focused pane / clear zoom.

• Environments & globals

  • Ctrl+E - switch environments.
  • Ctrl+G - inspect captured globals.

• Working with responses

  • Ctrl+V / Ctrl+U - split the response pane for side-by-side comparison.
  • When response pane is focused:
    • Ctrl+Shift+C or g y - copy the entire Pretty/Raw/Headers tab to the clipboard (no mouse selection needed).

---

Tip

If you only remember three shortcuts…

• Ctrl+Enter - send request
• Tab / Shift+Tab - switch panes
• g+p - jump to response

Inline curl import

Drop a curl command into the editor and press Ctrl+Enter anywhere inside to turn it into a structured request. Resterm understands common flags (-X, -H, --data*, --json, --url, --user, --compressed, -F/--form, etc.), merges repeated data segments, and respects multipart uploads.

curl \
  --compressed \
  --url "https://httpbin.org/post?source=resterm&case=multipart" \
  --request POST \
  -H "Accept: application/json" \
  -H "X-Client: resterm-dev" \
  --user resterm:test123 \
  -F file=@README.md \
  --form-string memo='Testing resterm inline curl
with multiline value' \
  --form-string meta='{"env":"test","attempt":1}'

If you copied the command from a shell, prefixes like sudo or $ are ignored automatically. Resterm loads the file attachment, preserves multiline form fields, and applies compression/auth headers without extra tweaks.

Quick Configuration Overview

• Environments: JSON files (resterm.env.json) are auto-discovered in the request directory, workspace root, or CWD. Dotenv files (.env, .env.*) are opt-in via --env-file and are single-workspace; prefer JSON when you need multiple environments in one file.
• Flags you probebly reach for most: --workspace, --file, --env, --env-file, --timeout, --insecure, --follow, --proxy, --recursive, --from-openapi, --http-out (see docs for the full list).
• Config storage: $HOME/Library/Application Support/resterm, %APPDATA%\resterm, or $HOME/.config/resterm (override with RESTERM_CONFIG_DIR). Themes and keybindings live under this directory when you customize them.

Feature snapshots

• OAuth 2.0: Full OAuth support with three grant types - client credentials for service-to-service calls, password grant for legacy systems, and authorization code + PKCE for user login flows. For auth code flows, Resterm opens your system browser, spins up a local callback server on 127.0.0.1, captures the redirect and exchanges the code automatically. Tokens are cached per environment and refreshed when they expire. Docs: docs/resterm.md#oauth-20-directive and _examples/oauth2.http.
• SSH jumps/tunnels: Route HTTP/gRPC/WebSocket/SSE through bastions with @ssh profiles (persist/keepalive/host-key/retries). Docs: docs/resterm.md#ssh-jumps and _examples/ssh.http.
• Workflows & scripting: Chain requests with @workflow/@step, pass data between steps, and add lightweight JS hooks. Docs + sample: docs/resterm.md#workflows-multi-step-workflows and _examples/workflows.http.
• Compare runs: Run the same request across environments with @compare or --compare, then diff responses side by side (g+c). Docs: docs/resterm.md#compare-runs.
• Tracing & timeline: Add @trace with budgets to capture DNS/connect/TLS/TTFB/transfer timings, visualize overruns, and optionally export spans to OpenTelemetry. Docs: docs/resterm.md#timeline--tracing.
• Streaming (WebSocket & SSE): Use @websocket + @ws steps or @sse to script and record streams. The Stream tab keeps transcripts and an interactive console. Docs: docs/resterm.md#streaming-sse--websocket.
• OpenAPI import: Convert an OpenAPI 3 spec into .http collections from the CLI (--from-openapi). Docs: docs/resterm.md#importing-openapi-specs.
• Theming & bindings: Optional customization via themes/*.toml and bindings.toml/json under the config dir; defaults are ready to use. Docs: docs/resterm.md#theming and docs/resterm.md#custom-bindings.

Documentation

The full reference, including request syntax, metadata, directive tables, scripting APIs, transport settings and advanced workflows, lives in docs/resterm.md.