resterm

Resterm

An API-as-code workbench for the terminal.

Resterm is a terminal API client that stores your requests in plain-text `.http` and `.rest` files you can diff, review and track in version control. Edit and send requests in the terminal, or run them from scripts and CI. Request files support workflows, assertions, mock servers, tracing and profiling. No accounts, cloud sync or telemetry. Quick links: [Screenshots](#screenshot-tour), [Quick Start](#quick-start), [Request files](#request-files), [Installation](#installation), [Documentation](#documentation). ## Screenshot tour See the UI in action (click to expand)

Workflows

Trace and Timeline

Profiler

Explain

RestermScript

Light Theme

OAuth browser demo (old UI design)

## Why Resterm - **HTTP, GraphQL, gRPC, WebSocket and SSE** support. - **Automation in request files:** conditions (`@when`, `@if`/`@elif`/`@else`, `@for-each`), multi-step workflows (`@workflow` / `@step`), captures, variables and assertions (`@capture`, `@var`, `@assert`). - **Record HTTP traffic** and export it to Resterm `.http` files as requests or mock responses. - **RestermScript**, a small expression language built for Resterm, with JavaScript hooks when you want them. - **Vim-style controls** with shortcut hints, searchable offline help, `Shift+k` help under the cursor, `/` search and commands like `:w`, `:q`, `:help` and `:docs`. - **Auth and tunneling:** OAuth 2.0 (client credentials, password, authorization code with PKCE), auth through existing CLIs, SSH tunnels and Kubernetes port-forwards. - **CLI runner:** `resterm run` for scripted runs and CI, with JSON and JUnit output. - **Mock servers** declared next to the requests they mimic, with matching rules, sequences, call verification and hot reload. - **Timeline tracing, profiling and compare runs** across environments. - **Streaming transcripts** and an interactive console for WebSocket and SSE. - **No AI integration**, ever. ## Quick Start 1. Install Resterm (see [Installation](#installation) for scripts, Windows and manual installs). ```bash brew install resterm ``` 2. Create a workspace. ```bash mkdir my-api && cd my-api resterm init ``` `resterm init` gives you a small project that works without an internet connection. The generated `requests.http` includes local mock scenarios and a few requests that build on each other. They cover assertions, bearer auth, JSON matching, `json-rules`, and `@for-each`. 3. Open Resterm and send your first request. ```bash resterm ``` Press `Ctrl+Enter` in the editor to send the highlighted request. No files yet? Just run `resterm`, type a URL and press `Ctrl+Enter`. A pasted curl command works too. ## Request files Resterm request files use standard HTTP syntax plus `# @` directives for configuration and automation: ```http # @setting base-url https://api.example.com/v1/ ### Create users // Send this request once for each name in the list. # @for-each ["david", "tom"] as name # @when env.mode == "development" # @assert response.statusCode == 201 POST users Content-Type: application/json {"name":"{{= name }}"} ``` Settings before the first request apply to the whole file. `###` separates requests, and directives can repeat, limit or validate a request. More examples: [`_examples/`](_examples/). ## CLI Use `resterm run` to execute `.http` / `.rest` files from scripts or CI without opening the TUI. ```bash resterm run --request CreateUser requests.http ``` The generated project talks to a local mock server. Start it in another terminal first: ```bash resterm mock requests.http ``` In the TUI, press `g Shift+m` in normal mode to start the workspace mock server. Repeat to stop it. The [CLI documentation](docs/cli.md) covers selectors, output formats and more examples. ## Keyboard cheat sheet These are the default bindings. `+` means hold keys together (`Alt+v`). A space means press them in sequence (`g v`: press `g`, release it, then press `v`). Letters are lowercase, and `Shift` is written explicitly when required (`g Shift+z`). Symbols such as `?` and `:` mean type that character using your keyboard layout. In the editor, `i` enters insert mode and `Esc` returns to normal mode. If completion is open, the first `Esc` dismisses it. Use normal mode for `g` sequences, `Alt+v` / `Alt+h`, `?`, `Shift+k`, `:` and pane switching. Insert mode preserves character input, including text produced with Alt, and uses `Tab` for completion or indentation. `Ctrl+Enter` still sends requests in insert mode. - Pane focus and layout - `Tab` / `Shift+Tab`: move between sidebar, editor and response. - `g r`, `g i`, `g p`: jump to requests, editor normal mode or response. - `g h` / `g l`: shrink or grow the sidebar when it is focused. Otherwise, move the editor/response divider left or right in the side-by-side layout. - `g j` / `g k`: move the editor/response divider down or up when stacked, or collapse and expand branches when the navigator is focused. - `g v` / `g s`: place the response beside or below the editor. - `g 1`, `g 2`, `g 3`: minimize or restore sidebar, editor or response. - `g z`: toggle zoom for the focused editor or response pane. `g Shift+z`: clear zoom. - Environments and globals - `Ctrl+e`: switch environments. - `Ctrl+g`: inspect captured globals. - Help and commands - `?`: open the searchable offline help index. - `Shift+k` (editor normal mode): open help for the directive, template or keyword under the cursor. - `:help ` / `:man `: open an embedded topic; `:docs ` opens the version-matched full manual. - `Ctrl+o`: open the file/workspace popup. Type to filter, scroll with `Up` / `Down`, and use `Tab` to descend into directories. - `:`: open the command line. Use `Up` / `Down` to select suggestions, `Tab` to complete one, or `Enter` to accept and run a selection. Path arguments such as `:mock start --source` and `:edit` browse the filesystem in the same popup. - `g e`: open the current file, or the file selected in the navigator, in your external editor. - Requests and responses - `Ctrl+Enter`: send the active request, including from editor insert mode. - `Alt+v` / `Alt+h`: split responses side by side or stack them for comparison. Repeat the same shortcut to close the split. - `Ctrl+Shift+c` or `g y` (response focused): copy the whole Pretty, Raw or Headers tab. - `g x`: show the Explain preview for the active request without sending it. > [!TIP] > If you only remember three shortcuts: > > - `Ctrl+Enter` sends the request > - `Tab` / `Shift+Tab` switches panes > - `g p` jumps to the response ## Installation **Linux / macOS (Homebrew)** ```bash 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 or install scripts. **Linux / macOS (Shell script)** > [!IMPORTANT] > Pre-built Linux binaries depend on glibc 2.32 or newer. On an older distro, build from source with a newer glibc toolchain or upgrade glibc before using the release archives. ```bash curl -fsSL https://raw.githubusercontent.com/unkn0wn-root/resterm/main/install.sh | bash ``` or with `wget`: ```bash wget -qO- https://raw.githubusercontent.com/unkn0wn-root/resterm/main/install.sh | bash ``` **Windows (PowerShell)** ```powershell iwr -useb https://raw.githubusercontent.com/unkn0wn-root/resterm/main/install.ps1 | iex ``` The scripts 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** ```bash # Find the latest release 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)" # Install on PATH chmod +x resterm sudo install -m 0755 resterm /usr/local/bin/resterm ``` **Windows (PowerShell)** ```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 move to a directory on PATH: Move-Item resterm.exe "$env:USERPROFILE\bin\resterm.exe" ``` ### From source ```bash go install github.com/unkn0wn-root/resterm/cmd/resterm@latest ``` ## Update ```bash resterm --check-update resterm --update ``` The first command reports whether a newer release is available. The second downloads, verifies and installs it in place. On Windows the old binary stays next to the new one as `resterm.exe.old` and is cleaned up on the next update. ## Configuration - Resterm looks for environment files (`resterm.env.json`) in the request directory, workspace root or current working directory. A file can define named environments or groups, such as api, app and credentials, that combine into one environment. Use `--env-file` to load dotenv files (`.env`, `.env.*`) for the current workspace. See [grouped environments](./docs/resterm.md#grouped-environments) and the example in `_examples/grouped/`. - Configuration is stored in the directory below. Set `RESTERM_CONFIG_DIR` to use another location: - macOS: `~/Library/Application Support/resterm` - Windows: `%APPDATA%\resterm` - Linux/Unix: `~/.config/resterm` ## Mock Servers You can define mock responses in the same `.http` files as your requests. - Match incoming requests by query, headers or JSON body, then pick a named or default response. - Return a sequence of responses for polling and retry tests. Use a path, query, header, or cookie value to track each sequence separately. - Delay responses by a fixed amount, or give every request a different delay with `random`, `normal`, or `jitter`. - Build responses from path, query, header and body values, with generators for dynamic data. - Verify call counts with `@expect` or inspect received traffic from RestermScript. - Reload source files and fixtures when they change. TLS is optional. Two scenarios on one route: ```http ### 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"} ``` Serve one file or a whole directory: ```bash resterm mock ./requests.http resterm mock --recursive --addr 127.0.0.1:9090 ./requests ``` More in the [Mock Servers reference](docs/resterm.md#mock-servers), the [`resterm mock` CLI guide](docs/cli.md#resterm-mock) and the [working example](_examples/mocks.http). ## Recording Traffic You can record your API traffic or other HTTP traffic and save it as requests or mock responses in a Resterm `.http` file. ```bash res