### Install Resterm via Package Managers and Scripts

Source: https://context7.com/unkn0wn-root/resterm/llms.txt

Provides commands to install Resterm on Linux, macOS, and Windows using Homebrew, custom install scripts, or PowerShell. It also includes instructions for installing from source using Go.

```bash
# Linux/macOS (Homebrew)
brew install resterm

# Linux/macOS (install script)
curl -fsSL 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

# From source (requires Go 1.24+)
go install github.com/unkn0wn-root/resterm/cmd/resterm@latest
```

--------------------------------

### Install Resterm from Source (Go)

Source: https://github.com/unkn0wn-root/resterm/blob/main/README.md

Installs Resterm by building it directly from the source code using Go. This method requires Go to be installed on the system and is useful for developers who want the latest changes or need to customize the build.

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

--------------------------------

### Install Resterm using PowerShell (Windows)

Source: https://github.com/unkn0wn-root/resterm/blob/main/README.md

Installs Resterm on Windows systems using a PowerShell script. This command downloads and executes the installation script, automating the setup process.

```powershell
iwr -useb https://raw.githubusercontent.com/unkn0wn-root/resterm/main/install.ps1 | iex
```

--------------------------------

### Resterm SSH Tunnel Syntax Examples (Text)

Source: https://github.com/unkn0wn-root/resterm/blob/main/docs/resterm.md

Provides examples of Resterm's @ssh directive syntax for defining and using SSH tunnel profiles. Demonstrates global, file, and request-scoped definitions, as well as referencing existing profiles.

```text
# @ssh global bastion host=jump.example.com user=ops key=~/.ssh/id_ed25519 persist
# @ssh use=bastion
# @ssh host=10.0.0.5 user=svc password=env:SSH_PW

```

```text
# @ssh global edge host=10.0.0.5 user=ops

```

```text
# @ssh request host=192.168.1.50 user=svc password=env:SSH_PW timeout=12s

```

```text
# @ssh use=bastion

```

--------------------------------

### Test Script Example

Source: https://context7.com/unkn0wn-root/resterm/llms.txt

Demonstrates a test script that validates the existence and format of a globally stored token.

```APIDOC
## GET https://httpbin.org/anything/reports

### Description
This endpoint retrieves reports and includes a test script to verify that a globally stored token is available and valid. It also captures a trace ID from the response headers.

### Method
GET

### Endpoint
https://httpbin.org/anything/reports

### Parameters
#### Query Parameters
- **reporting.token** (string) - Required - The bearer token for authentication.

#### Headers
- **Accept** (string) - Optional - Specifies the desired response format, defaults to `application/json`.

### Request Example
```http
# @script test
> client.test("script-created token is available", function () {
>   var token = vars.get("reporting.token");
>   tests.assert(typeof token === "string" && token.length > 0, "global token should exist");
> });
GET https://httpbin.org/anything/reports
Accept: application/json
```

### Response
#### Success Response (200)
- **data** (object) - The echoed request details.

#### Response Example
```json
{
  "data": {
    "args": {},
    "data": "",
    "files": {},
    "form": {},
    "headers": {
      "Accept": "application/json",
      "Authorization": "Bearer your_reporting_token",
      "Host": "httpbin.org",
      "Trace-Id": "your_trace_id",
      "User-Agent": "curl/7.64.1",
      "X-Amzn-Trace-Id": "Root=1-6411d7e0-7f1d1e1e1e1e1e1e1e1e1e1"
    },
    "json": null,
    "origin": "192.168.1.1",
    "url": "https://httpbin.org/anything/reports"
  }
}
```
```

--------------------------------

### Manual Resterm Installation (Windows)

Source: https://github.com/unkn0wn-root/resterm/blob/main/README.md

Manually installs Resterm on Windows by downloading the latest release executable. This script uses PowerShell to find the correct asset from the latest release and downloads it. It also includes an optional step to move the executable to a directory on the system's PATH.

```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"
```

--------------------------------

### Resterm Init Command Examples

Source: https://github.com/unkn0wn-root/resterm/blob/main/docs/resterm.md

Demonstrates various ways to use the `resterm init` command, including specifying a target directory, using a specific template, previewing actions with dry-run, and overwriting existing files.

```bash
# Create files in a subdirectory
resterm init ./api-tests

# Use the minimal template
resterm init --template minimal

# Preview what would be created
resterm init --dry-run

# Overwrite existing files
resterm init --force
```

--------------------------------

### Manual Resterm Installation (Linux/macOS)

Source: https://github.com/unkn0wn-root/resterm/blob/main/README.md

Manually installs Resterm on Linux and macOS by fetching the latest release binary. This method requires `curl` and `jq` to be installed. It downloads the appropriate binary based on the system architecture and makes it executable.

```bash
# 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
```

--------------------------------

### Install Resterm via Script (Linux)

Source: https://github.com/unkn0wn-root/resterm/blob/main/README.md

Installs Resterm on Linux systems by downloading and executing an installation script from a GitHub repository. This method is suitable for systems where Homebrew is not installed or preferred.

```bash
# Linux (install script)
curl -fsSL https://raw.githubusercontent.com/unkn0wn-root/resterm/main/install.sh | bash
```

--------------------------------

### Example HTTP Request File

Source: https://github.com/unkn0wn-root/resterm/blob/main/docs/resterm.md

A minimal example of an .http file used by Resterm. It demonstrates defining requests with HTTP methods, URLs, headers, and JSON bodies, including variable usage like {{$uuid}}.

```http
### Fetch Status
# @name health
GET https://httpbin.org/status/204
User-Agent: resterm
Accept: application/json

### Create Resource
# @name create
POST https://httpbin.org/anything
Content-Type: application/json

{
  "id": "{{$uuid}}",
  "note": "created from Resterm"
}
```

--------------------------------

### Assertions Example

Source: https://context7.com/unkn0wn-root/resterm/llms.txt

Illustrates how to perform inline response assertions using `@assert` directives with RestermScript expressions.

```APIDOC
## GET https://httpbin.org/get?mode=debug

### Description
This endpoint makes a GET request and includes several inline assertions to validate the response. It checks the status code, a specific JSON field, the format of a URL, the presence of a substring in the text, and the number of headers.

### Method
GET

### Endpoint
https://httpbin.org/get?mode=debug

### Parameters
#### Query Parameters
- **mode** (string) - Set to `debug` for this example.

#### Headers
- **Accept** (string) - Optional - Specifies the desired response format, defaults to `application/json`.

### Request Example
```http
# @assert response.statusCode == 200
# @assert response.json("args.mode") == "debug"
# @assert match("^https?://", response.json("url"))
# @assert contains(response.text(), "\"url\"")
# @assert len(response.json("headers")) > 0
GET https://httpbin.org/get?mode=debug
Accept: application/json
```

### Response
#### Success Response (200)
- **data** (object) - The echoed request details.

#### Response Example
```json
{
  "data": {
    "args": {
      "mode": "debug"
    },
    "headers": {
      "Accept": "application/json",
      "Host": "httpbin.org",
      "User-Agent": "curl/7.64.1",
      "X-Amzn-Trace-Id": "Root=1-6411d7e0-7f1d1e1e1e1e1e1e1e1e1e1"
    },
    "origin": "192.168.1.1",
    "url": "https://httpbin.org/get?mode=debug"
  }
}
```
```

--------------------------------

### Install Resterm using Shell Script (Linux/macOS)

Source: https://github.com/unkn0wn-root/resterm/blob/main/README.md

Installs Resterm on Linux and macOS by downloading and executing an installation script. This method is suitable for systems without Homebrew or when a direct script installation is preferred. Note that Linux binaries require glibc 2.32 or newer.

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

```bash
wget -qO- https://raw.githubusercontent.com/unkn0wn-root/resterm/main/install.sh | bash
```

--------------------------------

### Install Resterm via PowerShell (Windows)

Source: https://github.com/unkn0wn-root/resterm/blob/main/README.md

Installs Resterm on Windows systems using PowerShell. This command downloads and executes an installation script, making it convenient for Windows users.

```powershell
# Windows (PowerShell)
iwr -useb https://raw.githubusercontent.com/unkn0wn-root/resterm/main/install.ps1 | iex
```

--------------------------------

### Send Basic HTTP Requests with Metadata

Source: https://context7.com/unkn0wn-root/resterm/llms.txt

Illustrates creating and sending HTTP requests using `.http` files. It shows how to use metadata directives for naming (`# @name`), tagging, and configuring requests, including GET, POST, and dynamic helpers for timestamps and UUIDs.

```http
### Fetch Status
# @name health
GET https://httpbin.org/status/204
User-Agent: resterm/0.1
Accept: application/json

### Create Resource
# @name createPost
POST https://httpbin.org/anything/posts
Content-Type: application/json
Accept: application/json

{
  "title": "foo",
  "body": "bar",
  "userId": 1
}

### Using Dynamic Helpers
# @name timestampHelpers
POST https://httpbin.org/anything/time
Content-Type: application/json

{
  "now_unix": "{{$timestamp}}",
  "now_unix_plus_6d": "{{$timestamp + 6d}}",
  "now_iso_minus_90m": "{{$timestampISO8601 - 90m}}",
  "now_unix_ms": "{{$timestampMs}}",
  "request_id": "{{$uuid}}"
}
```

--------------------------------

### Install Resterm using Homebrew (Linux/macOS)

Source: https://github.com/unkn0wn-root/resterm/blob/main/README.md

Installs the Resterm tool on Linux and macOS systems using the Homebrew package manager. This is a straightforward method for users who have Homebrew set up.

```bash
brew install resterm
```

--------------------------------

### TOML Theme File Example for Resterm

Source: https://github.com/unkn0wn-root/resterm/blob/main/docs/resterm.md

This TOML file demonstrates the structure for creating custom themes in Resterm. It includes metadata, style definitions for various UI elements, color definitions, and segment configurations. Unspecified fields will inherit default values.

```toml
[metadata]
name = "Oceanic"
author = "You"
description = "Cool dusk palette"

[styles.header_title]
foreground = "#5fd1ff"
bold = true

[colors]
pane_border_focus_file = "#1f6feb"
pane_active_foreground = "#f8faff"

[editor_metadata]
comment_marker = "#4c566a"

[[header_segments]]
background = "#5e81ac"
foreground = "#eceff4"

[[command_segments]]
background = "#3b4252"
key = "#88c0d0"
text = "#eceff4"

```

--------------------------------

### OAuth 2.0 Token Caching Example (HTTP)

Source: https://github.com/unkn0wn-root/resterm/blob/main/docs/resterm.md

Demonstrates how to seed the OAuth 2.0 token cache with initial parameters and subsequently reuse the cached token for subsequent requests using a cache key.

```http
### First request - seeds the cache
# @auth oauth2 token_url={{oauth.tokenUrl}} client_id={{oauth.clientId}} client_secret={{oauth.clientSecret}} scope="read write" cache_key=myapi
GET {{base.url}}/users

### Later request - reuses cached token
# @auth oauth2 cache_key=myapi
GET {{base.url}}/projects
```

--------------------------------

### Example Resterm Environment JSON

Source: https://github.com/unkn0wn-root/resterm/blob/main/docs/resterm.md

Demonstrates the structure of a `resterm.env.json` file, which can contain nested objects and arrays for defining environment-specific variables. These variables are flattened using dot and bracket notation.

```json
{
  "dev": {
    "settings.http-root-cas": "dev-ca.pem",
    "settings.grpc-insecure": "false",
    "services": {
      "api": {
        "base": "https://httpbin.org/anything/api"
      }
    },
    "auth": {
      "token": "dev-token-123"
    }
  }
}
```

--------------------------------

### gRPC with Descriptor File

Source: https://context7.com/unkn0wn-root/resterm/llms.txt

Makes a gRPC call to get report status using a descriptor file.

```APIDOC
## GRPC {{grpc.host}}

### Description
Retrieves report status using gRPC with a descriptor file.

### Method
GRPC

### Endpoint
{{grpc.host}}

### Parameters
#### Service Method
- **analytics.ReportingService/GetReportStatus** (string) - Required

#### gRPC Options
- **grpc-descriptor**: descriptors/analytics.protoset

#### Headers
- **authorization**: Bearer {{analytics.sessionToken}}

#### Settings
- **grpc-root-cas**: ./ca.pem

#### Request Body
- **reportId** (string) - Required - rep-{{$uuid}}

### Request Example
```json
{
  "reportId": "rep-{{$uuid}}"
}
```

### Response
#### Success Response (200)
- **Status** (object) - The status of the report.
```

--------------------------------

### Implement Authentication Directives

Source: https://context7.com/unkn0wn-root/resterm/llms.txt

Details the support for various authentication methods within Resterm, including Basic, Bearer Token, API Key, and OAuth 2.0. The examples show how to use the `@auth` directive with different schemes and credentials.

```http
### Basic Authentication
# @auth basic username password123
GET https://httpbin.org/basic-auth/username/password123

### Bearer Token
# @name bearerEcho
# @auth bearer {{auth.token}}
GET https://httpbin.org/bearer
Accept: application/json

### API Key Authentication
# @auth apikey header X-API-Key {{api.key}}
GET https://api.example.com/data

### OAuth 2.0 Client Credentials
# @name oauthClientCreds

```

--------------------------------

### Run Resterm and Send a Request

Source: https://github.com/unkn0wn-root/resterm/blob/main/README.md

Starts the Resterm application and allows users to send API requests. Requests can be typed directly into the editor or imported from cURL commands. Pressing Ctrl+Enter sends the highlighted request.

```bash
resterm
```

--------------------------------

### Auth0 OAuth2 (Confidential Client) with Client Secret

Source: https://github.com/unkn0wn-root/resterm/blob/main/docs/resterm.md

Illustrates how to authenticate with Auth0 using OAuth2 for a confidential client, requiring both a client ID and a client secret. This example sets up the necessary URLs, credentials, scopes, and audience for accessing user information.

```http
### Auth0 with client secret
# @auth oauth2 auth_url=https://{{auth0.domain}}/authorize token_url=https://{{auth0.domain}}/oauth/token client_id={{auth0.clientId}} client_secret={{auth0.clientSecret}} scope="openid profile" audience={{auth0.audience}} grant=authorization_code
GET {{api.url}}/userinfo
```

--------------------------------

### Response Pane Navigation and Manipulation in Resterm

Source: https://github.com/unkn0wn-root/resterm/blob/main/docs/resterm.md

This snippet outlines keyboard shortcuts for manipulating and navigating response panes in Resterm. It includes splitting panes, pinning secondary panes for comparison, copying tab content, and jumping to the start or end of content.

```text
Ctrl+V or Ctrl+U: Split response pane
Ctrl+Shift+C or g y: Copy tab content to clipboard
g+g: Jump to start of tab content
G: Jump to end of tab content
```

--------------------------------

### Initialize a Resterm Project

Source: https://context7.com/unkn0wn-root/resterm/llms.txt

Demonstrates how to bootstrap a new Resterm workspace with starter files using the `resterm init` command. Options include using a minimal template, previewing changes without creating files, and initializing in a specific directory.

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

# Use minimal template
resterm init --template minimal

# Preview without creating files
resterm init --dry-run

# Initialize in specific directory
resterm init ./api-tests
```

--------------------------------

### Set Request Timeout using @timeout Directive

Source: https://github.com/unkn0wn-root/resterm/blob/main/docs/resterm.md

Demonstrates how to set a request timeout using the `@timeout` directive. This directive is a shorthand for `@setting timeout`. The example shows a GET request to a URL that introduces a delay, with a timeout set to 2 seconds, which would typically cause the request to fail if the delay exceeds the timeout.

```http
### Fast timeout
# @name TimeoutDemo
# @timeout 2s
GET https://httpbin.org/delay/5
```

--------------------------------

### Bootstrap Session with Pre-request Script

Source: https://context7.com/unkn0wn-root/resterm/llms.txt

Demonstrates setting up a session using a pre-request script that manages a token, sets headers, and prepares a JSON payload.

```APIDOC
## POST https://httpbin.org/anything/reports/sessions

### Description
This endpoint initiates a new session for reports. It uses a pre-request script to manage a global token, set authorization and trace ID headers, and construct a JSON payload with correlation details.

### Method
POST

### Endpoint
https://httpbin.org/anything/reports/sessions

### Parameters
#### Request Body
- **Content-Type** (string) - Required - Must be `application/json`.

### Request Example
```http
# @script pre-request
> var existing = vars.global.get("reporting.token");
> var token = existing || `script-${Date.now()}`;
> vars.global.set("reporting.token", token, {secret: true});
> request.setHeader("Authorization", `Bearer ${token}`);
> request.setHeader("X-Trace-ID", `trace-${Date.now()}`);
> var payload = {
>   correlationId: `corr-${Date.now()}`,
>   scope: "reports",
>   requestedAt: new Date().toISOString()
> };
> request.setBody(JSON.stringify(payload, null, 2));
POST https://httpbin.org/anything/reports/sessions
Content-Type: application/json

{
  "correlationId": "corr-1678886400000",
  "scope": "reports",
  "requestedAt": "2023-03-15T10:00:00.000Z"
}
```

### Response
#### Success Response (200)
- **data** (object) - The echoed request details.

#### Response Example
```json
{
  "data": {
    "args": {},
    "data": "{\n  \"correlationId\": \"corr-1678886400000\",\n  \"scope\": \"reports\",\n  \"requestedAt\": \"2023-03-15T10:00:00.000Z\"\n}",
    "files": {},
    "form": {},
    "headers": {
      "Accept": "*/*",
      "Authorization": "Bearer script-1678886400000",
      "Content-Length": "100",
      "Content-Type": "application/json",
      "Host": "httpbin.org",
      "Trace-Id": "trace-1678886400000",
      "User-Agent": "curl/7.64.1",
      "X-Amzn-Trace-Id": "Root=1-6411d7e0-7f1d1e1e1e1e1e1e1e1e1e1"
    },
    "json": {
      "correlationId": "corr-1678886400000",
      "requestedAt": "2023-03-15T10:00:00.000Z",
      "scope": "reports"
    },
    "origin": "192.168.1.1",
    "url": "https://httpbin.org/anything/reports/sessions"
  }
}
```
```

--------------------------------

### Set Resterm Themes Directory and Launch

Source: https://github.com/unkn0wn-root/resterm/blob/main/docs/resterm.md

This command sets the environment variable RESTERM_THEMES_DIR to the current directory's '_examples/themes' subdirectory and then launches the 'resterm' application. This is used to test custom themes by pointing Resterm to their location.

```bash
export RESTERM_THEMES_DIR="$(pwd)/_examples/themes"
resterm
```

--------------------------------

### Install Resterm via Homebrew (Linux/macOS)

Source: https://github.com/unkn0wn-root/resterm/blob/main/README.md

Installs Resterm using the Homebrew package manager on Linux and macOS systems. This is a common method for managing command-line tools on these operating systems.

```bash
# Linux/macOS (Homebrew)
brew install resterm
```

--------------------------------

### Configure Environments with JSON Variables

Source: https://context7.com/unkn0wn-root/resterm/llms.txt

Shows how to define environment-specific configurations using JSON files. Variables and nested objects are flattened using dot notation, allowing for easy access to settings like base URLs, API keys, and authentication tokens across different environments (e.g., 'dev', 'prod').

```json
{
  "dev": {
    "settings.http-root-cas": "dev-ca.pem",
    "services": {
      "api": {
        "base": "https://httpbin.org/anything/api"
      }
    },
    "auth": {
      "token": "dev-token-123"
    }
  },
  "prod": {
    "services": {
      "api": {
        "base": "https://api.example.com"
      }
    },
    "auth": {
      "token": "prod-token-456"
    }
  }
}
```

--------------------------------

### Multi-step Workflows

Source: https://context7.com/unkn0wn-root/resterm/llms.txt

Defines a multi-step workflow named 'Sample Order' that includes authentication, fetching headers, and creating a resource, with options for failure handling and variable passing.

```APIDOC
# @global base_url https://httpbin.org
# @global-secret auth.token seed-token

# @workflow sample-order on-failure=continue vars.workflow.name="Sample Order" vars.workflow.item_id="workflow-42"
# @description Multi-step workflow with expectations and variable overrides.
# @tag demo workflow
# @step Authenticate using=AcquireToken expect.statuscode=200
# @step FetchHeaders using=FetchHeaders expect.status="200 OK" vars.request.trace_header="workflow-trace"
# @step CreateResource using=CreateResource vars.request.item_value="workflow created" expect.statuscode=200

### Description
This defines a multi-step API workflow named 'Sample Order'. It starts by authenticating using a request named 'AcquireToken', expecting a 200 status code. The next step, 'FetchHeaders', uses a request named 'FetchHeaders' and expects a '200 OK' status, while also setting a request variable `trace_header` to 'workflow-trace'. The final step, 'CreateResource', uses a request named 'CreateResource', expects a 200 status code, and sets a request variable `item_value` to 'workflow created'. The workflow is configured to continue on failure and has global variables `base_url` and a secret `auth.token`.

### Workflow Configuration
- **Name**: `sample-order`
- **Description**: Multi-step workflow with expectations and variable overrides.
- **Tags**: `demo`, `workflow`
- **Failure Handling**: `continue`
- **Workflow Variables**: `name='Sample Order'`, `item_id='workflow-42'`
- **Global Variables**: `base_url='https://httpbin.org'`, `auth.token` (secret)

### Steps
1.  **Authenticate**: Uses `AcquireToken`, expects status code `200`.
2.  **FetchHeaders**: Uses `FetchHeaders`, expects status `200 OK`, sets `vars.request.trace_header='workflow-trace'`.
3.  **CreateResource**: Uses `CreateResource`, expects status code `200`, sets `vars.request.item_value='workflow created'`.
```

--------------------------------

### Bootstrap a Resterm Workspace

Source: https://github.com/unkn0wn-root/resterm/blob/main/README.md

Initializes a new Resterm workspace by creating a directory and running the 'resterm init' command. This sets up the basic file structure for managing API requests.

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

--------------------------------

### GetUser API

Source: https://github.com/unkn0wn-root/resterm/blob/main/docs/resterm.md

Retrieves user information using a GET request. The user ID is dynamically provided via a workflow variable.

```APIDOC
## GET /users/{{vars.workflow.userId}}

### Description
Retrieves user information using a GET request. The user ID is dynamically provided via a workflow variable.

### Method
GET

### Endpoint
https://example.com/users/{{vars.workflow.userId}}

### Parameters
#### Path Parameters
- **userId** (string) - Required - The ID of the user to retrieve.

### Request Example
```json
{
  "example": "No request body for GET request"
}
```

### Response
#### Success Response (200)
- **(response structure depends on the API)** - Description of the user data returned.

#### Response Example
```json
{
  "example": "{\"id\": \"{{vars.workflow.userId}}\", \"name\": \"John Doe\"}"
}
```
```

--------------------------------

### Custom Token Header Authentication

Source: https://github.com/unkn0wn-root/resterm/blob/main/docs/resterm.md

This example demonstrates how to send an OAuth2 token in a custom HTTP header, rather than the default 'Authorization' header.

```APIDOC
## GET https://api.example.com/data

### Description
Fetches data from an API where the access token is expected in a custom header, such as 'X-Access-Token'.

### Method
GET

### Endpoint
https://api.example.com/data

### Parameters
#### Request Body
(No request body is typically sent for this type of GET request, but if required, it would be detailed here.)

### Request Example
```http
### API expecting X-Access-Token header
# @auth oauth2 token_url={{oauth.tokenUrl}} client_id={{oauth.clientId}} client_secret={{oauth.clientSecret}} header=X-Access-Token
GET https://api.example.com/data
```

### Response
#### Success Response (200)
- **data** (object) - The requested data payload from the API.

#### Response Example
```json
{
  "data": {
    "message": "Successfully retrieved data."
  }
}
```
```

--------------------------------

### RestermScript Literals

Source: https://github.com/unkn0wn-root/resterm/blob/main/docs/restermscript.md

Provides examples of various literal types supported in RestermScript, including null, booleans, numbers, strings, arrays, and dictionaries.

```RestermScript
null
true / false
123  3.14
"string"  'string'
[1, 2, 3]
{a: 1, "b": 2}
```

--------------------------------

### Apply Patches

Source: https://context7.com/unkn0wn-root/resterm/llms.txt

Demonstrates how to apply dynamic patches to requests, including defining reusable patches and applying them inline or by name.

```APIDOC
## GET https://httpbin.org/anything?debug=0

### Description
This endpoint applies an inline patch to modify the request headers and query parameters before sending. It then asserts that a specific query parameter (`from`) has the expected value.

### Method
GET

### Endpoint
https://httpbin.org/anything?debug=0

### Parameters
#### Query Parameters
- **debug** (string) - Set to `0`.
- **from** (string) - Added by the inline patch, set to `apply`.
- **applied** (string) - Added by the inline patch, set to `1`.

#### Headers
- **X-Test** (string) - Added by the inline patch, set to `1`.

### Request Example
```http
# @apply {headers: {"X-Test": "1"}, query: {from: "apply", applied: "1"}}
# @assert response.json("args.from") == "apply"
GET https://httpbin.org/anything?debug=0
```

## POST https://httpbin.org/anything

### Description
This endpoint applies named patches (`jsonApi`) to modify the request headers before sending a POST request with a JSON body.

### Method
POST

### Endpoint
https://httpbin.org/anything

### Parameters
#### Headers
- **Accept** (string) - Set to `application/json` by the `jsonApi` patch.
- **Content-Type** (string) - Set to `application/json` by the `jsonApi` patch.

### Request Body
- **data** (string) - The string "test".

### Request Example
```http
# @patch file jsonApi {headers: {"Accept":"application/json","Content-Type":"application/json"}}
# @apply use=jsonApi
POST https://httpbin.org/anything

{"data": "test"}
```

### Response
#### Success Response (200)
- **data** (object) - The echoed request details.

#### Response Example
```json
{
  "data": {
    "args": {},
    "data": "{\"data\": \"test\"}",
    "files": {},
    "form": {},
    "headers": {
      "Accept": "application/json",
      "Content-Type": "application/json",
      "Host": "httpbin.org",
      "User-Agent": "curl/7.64.1",
      "X-Amzn-Trace-Id": "Root=1-6411d7e0-7f1d1e1e1e1e1e1e1e1e1e1"
    },
    "json": {
      "data": "test"
    },
    "origin": "192.168.1.1",
    "url": "https://httpbin.org/anything"
  }
}
```
```

--------------------------------

### Using RTS Modules

Source: https://context7.com/unkn0wn-root/resterm/llms.txt

Demonstrates how to use reusable RestermScript (RTS) modules to define helper functions for authentication headers, environment modes, and trace IDs.

```APIDOC
## GET https://httpbin.org/bearer

### Description
This endpoint utilizes functions from an external RTS module (`./rts/helpers.rts`) to dynamically generate the `Authorization` and `X-Trace-Id` headers, and determine the `X-Mode` header based on the environment.

### Method
GET

### Endpoint
https://httpbin.org/bearer

### Parameters
#### Headers
- **Authorization** (string) - Generated using `helpers.authHeader(vars.get("api.token"))`.
- **X-Mode** (string) - Generated using `helpers.mode(env)`.
- **X-Trace-Id** (string) - Generated using `helpers.traceId()`.

### Request Example
```http
# @use ./rts/helpers.rts
# @when vars.has("api.token")
# @assert response.statusCode == 200
GET https://httpbin.org/bearer
Authorization: {{= helpers.authHeader(vars.get("api.token")) }}
X-Mode: {{= helpers.mode(env) }}
X-Trace-Id: {{= helpers.traceId() }}
```

### Response
#### Success Response (200)
- **data** (object) - The echoed request details, including headers.

#### Response Example
```json
{
  "data": {
    "args": {},
    "data": "",
    "files": {},
    "form": {},
    "headers": {
      "Authorization": "Bearer your_api_token",
      "Host": "httpbin.org",
      "Trace-Id": "trace-1234567890",
      "User-Agent": "curl/7.64.1",
      "X-Amzn-Trace-Id": "Root=1-6411d7e0-7f1d1e1e1e1e1e1e1e1e1e1",
      "X-Mode": "debug"
    },
    "json": null,
    "origin": "192.168.1.1",
    "url": "https://httpbin.org/bearer"
  }
}
```
```

--------------------------------

### Conditional Directives with RestermScript

Source: https://github.com/unkn0wn-root/resterm/blob/main/docs/restermscript.md

Shows examples of RestermScript expressions used in directives to control request execution flow or validate responses. Directives are read-only and do not mutate request state.

```RestermScript
# @when env.has("feature")
# @assert response.statusCode == 200
```

--------------------------------

### Use Environment Variables in HTTP Requests

Source: https://context7.com/unkn0wn-root/resterm/llms.txt

Demonstrates how to utilize environment variables within `.http` files for dynamic request construction. It shows the use of `@global`, `@var`, and template variables like `{{auth.token}}` to inject configuration values into request headers and bodies.

```http
### Using Environment Variables
# @name envDemo
# @global analytics.apiKey demo-analytics-key
# @var file analytics.baseUrl https://httpbin.org/anything/analytics
# @var request analytics.jobId job-{{$uuid}}
POST {{analytics.baseUrl}}/sessions
Content-Type: application/json
Authorization: Bearer {{auth.token}}
X-API-Key: {{analytics.apiKey}}

{
  "jobId": "{{analytics.jobId}}",
  "tenant": "{{tenant.id}}"
}
```

--------------------------------

### RestermScript (RTS) Helper Module

Source: https://github.com/unkn0wn-root/resterm/blob/main/README.md

An example of a RestermScript module defining a helper function `authHeader` to generate an Authorization Bearer token. This demonstrates modularity within RestermScript.

```rts
// rts/helpers.rts
module helpers
export fn authHeader(token) {
  return token ? "Bearer " + token : ""
}
```

--------------------------------

### Using Reusable Module Logic

Source: https://github.com/unkn0wn-root/resterm/blob/main/docs/restermscript.md

This example shows how to import and use logic from a reusable RestermScript module (`.rts` file). The `users.label` function is called to dynamically generate a header value.

```http
# @use ./rts/users.rts
X-User: {{= users.label(user) }}
```

--------------------------------

### OAuth 2.0 Token URL

Source: https://context7.com/unkn0wn-root/resterm/llms.txt

Demonstrates how to authenticate using OAuth 2.0 with a token URL, client ID, client secret, and scope.

```APIDOC
## GET https://api.example.com/resource

### Description
This endpoint retrieves resources using OAuth 2.0 authentication with a pre-configured token URL, client ID, client secret, and specified scopes. The authentication details are cached for reuse.

### Method
GET

### Endpoint
https://api.example.com/resource

### Parameters
#### Query Parameters
- **oauth.tokenUrl** (string) - Required - The URL for obtaining the OAuth 2.0 token.
- **oauth.clientId** (string) - Required - The client ID for OAuth 2.0 authentication.
- **oauth.clientSecret** (string) - Required - The client secret for OAuth 2.0 authentication.
- **scope** (string) - Optional - The scope of the access request (e.g., "api:read api:write").
- **cache_key** (string) - Optional - A key to cache the authentication details.

### Request Example
```http
GET https://api.example.com/resource
```

### Response
#### Success Response (200)
- **data** (any) - The response data from the resource.

#### Response Example
```json
{
  "data": "..."
}
```
```

--------------------------------

### Resterm CLI: Launching and Importing

Source: https://context7.com/unkn0wn-root/resterm/llms.txt

Common command-line interface flags for launching Resterm, specifying workspace, selecting environments, and importing various formats like cURL commands and OpenAPI specifications.

```bash
# Open specific file
resterm --file requests.http

# Set workspace root
resterm --workspace ./api-tests --recursive

# Select environment
resterm --env production

# Import curl command
resterm --from-curl "curl https://example.com -H 'X-Test: 1'" --http-out example.http

# Import curl from file
resterm --from-curl ./requests.curl --http-out requests.http

# Import OpenAPI spec
resterm --from-openapi openapi.yml --http-out api.http --openapi-resolve-refs

# Compare environments from CLI
resterm --compare dev,stage,prod --compare-base stage

# Update Resterm
resterm --check-update
resterm --update

# History management
resterm history export --out backup.json
resterm history import --in backup.json
resterm history stats
```

--------------------------------

### GraphQL API

Source: https://github.com/unkn0wn-root/resterm/blob/main/docs/resterm.md

Handles GraphQL requests. Supports POST and GET methods with specific body and query parameter formats. Directives like `@graphql`, `@operation`, `@variables`, and `@query` customize behavior.

```APIDOC
## GraphQL API

### Description
Enable GraphQL handling with `# @graphql` (requests start with it disabled). Resterm packages GraphQL requests according to HTTP method:

- **POST**: body becomes `{ "query": ..., "variables": ..., "operationName": ... }`.
- **GET**: query parameters `query`, `variables`, `operationName` are attached.
- Template variables in the URL are expanded before the GET parameters are attached, so `GET {{graphql.endpoint}}` works even when the host is templated.

Available directives:

| Directive | Description |
| --- | --- |
| `@graphql [true|false]` | Enable/disable GraphQL processing for the request. |
| `@operation` / `@graphql-operation` | Sets the `operationName`. |
| `@variables` | Starts a variables block; inline JSON or `< file.json`. |
| `@query` | Loads the query from a file instead of the inline body. |

### Request Example (POST)
```http
### Inline GraphQL Query
# @graphql
# @operation FetchWorkspace
POST {{graphql.endpoint}}

query FetchWorkspace($id: ID!) {
  workspace(id: $id) {
    id
    name
  }
}

# @variables
{
  "id": "{{graphql.workspaceId}}"
}
```

### Request Example (GET)
```http
# @graphql
GET {{graphql.endpoint}}?query=query%20FetchWorkspace($id%3A%20ID!)%20%7B%0A%20%20workspace(id%3A%20$id)%20%7B%0A%20%20%20%20id%0A%20%20%20%20name%0A%20%20%7D%0A%7D&operationName=FetchWorkspace&variables=%7B%22id%22%3A%20%22some-id%22%7D
```
```

--------------------------------

### Guarded Request Example

Source: https://github.com/unkn0wn-root/resterm/blob/main/docs/restermscript.md

This pattern demonstrates a guarded request where the request is only sent if a specific condition is met, in this case, if an authentication token is present in the variables. It also shows how to dynamically construct headers.

```RestermScript
# @when vars.has("auth.token")
GET {{base_url}}/bearer
Authorization: {{= "Bearer " + vars.get("auth.token") }}
```

--------------------------------

### Timeline Tracing with Phase Budgets

Source: https://context7.com/unkn0wn-root/resterm/llms.txt

Enable HTTP tracing with phase budgets (DNS, connect, TTFB, total) for performance monitoring. Allows setting tolerances and asserting trace data, useful for identifying performance bottlenecks.

```http
### Trace with Budgets (Happy Path)
# @name trace-ok
# @trace dns<=40ms connect<=120ms ttfb<=300ms total<=600ms tolerance=25ms
GET https://httpbin.org/delay/0.05
Accept: application/json

### Trace with Intentional Breach
# @name trace-breach
# @trace total<=150ms tolerance=25ms
GET https://httpbin.org/delay/0.25
Accept: application/json

### Assert on Trace Data
# @name traceAssert
# @trace dns<=200ms connect<=400ms ttfb<=600ms total<=1000ms tolerance=100ms
# @assert trace.enabled() == true
# @assert trace.budgets().enabled == true
# @assert trace.durationMs() >= 0
GET https://httpbin.org/delay/0.1
Accept: application/json
```

--------------------------------

### Dotenv File Configuration for Resterm

Source: https://github.com/unkn0wn-root/resterm/blob/main/docs/resterm.md

Shows how to use a dotenv file with Resterm via the `--env-file` flag. This method is for single-environment configurations and supports standard dotenv syntax, including interpolation.

```bash
--env-file path/to/.env
```

--------------------------------

### Check and Update Resterm

Source: https://github.com/unkn0wn-root/resterm/blob/main/README.md

Commands to check for and apply updates to the Resterm tool. The `--check-update` command reports if a new version is available, while `--update` downloads and installs the latest release.

```bash
resterm --check-update
resterm --update
```

--------------------------------

### OAuth 2.0 Authorization Code + PKCE

Source: https://context7.com/unkn0wn-root/resterm/llms.txt

Illustrates OAuth 2.0 authentication using the Authorization Code grant with PKCE, including authorization URL, token URL, client ID, scope, and code challenge method.

```APIDOC
## GET https://api.example.com/userinfo

### Description
This endpoint fetches user information using OAuth 2.0 with the Authorization Code grant type and Proof Key for Code Exchange (PKCE). It requires the authorization URL, token URL, client ID, scope, and specifies the code challenge method.

### Method
GET

### Endpoint
https://api.example.com/userinfo

### Parameters
#### Query Parameters
- **oauth.authUrl** (string) - Required - The URL for initiating the OAuth 2.0 authorization flow.
- **oauth.tokenUrl** (string) - Required - The URL for obtaining the OAuth 2.0 token.
- **oauth.clientId** (string) - Required - The client ID for OAuth 2.0 authentication.
- **scope** (string) - Optional - The scope of the access request (e.g., "openid profile").
- **grant** (string) - Optional - Specifies the grant type, defaults to "authorization_code".
- **code_challenge_method** (string) - Optional - The method used for generating the code challenge (e.g., "s256").

### Request Example
```http
GET https://api.example.com/userinfo
```

### Response
#### Success Response (200)
- **userInfo** (object) - An object containing the user's information.

#### Response Example
```json
{
  "userInfo": {
    "sub": "1234567890",
    "name": "John Doe",
    "iat": 1516239022
  }
}
```
```

--------------------------------

### Request File Anatomy: Separators and Comments

Source: https://github.com/unkn0wn-root/resterm/blob/main/docs/resterm.md

Explains the basic structure of a Resterm request file, including how to define individual requests using '###' separators and how comments (lines starting with '#', '//', or '--') are handled, including metadata directives.

```http
### This is a request separator
# This is a comment line
GET /example

### Another request
// Another comment
POST /submit
```

--------------------------------

### Create resource

Source: https://context7.com/unkn0wn-root/resterm/llms.txt

Creates a new resource by sending a POST request with resource details.

```APIDOC
## POST /anything/resource

### Description
Creates a new resource.

### Method
POST

### Endpoint
{{base_url}}/anything/resource

### Parameters
#### Headers
- **Content-Type** (string) - Required - application/json
- **Authorization** (string) - Required - Bearer {{auth.token}}

#### Request Body
- **id** (string) - Required - {{vars.workflow.item_id}}
- **value** (string) - Required - {{vars.request.item_value}}

### Request Example
```json
{
  "id": "{{vars.workflow.item_id}}",
  "value": "{{vars.request.item_value}}"
}
```

### Response
#### Success Response (200)
- **Resource** (object) - The created resource details.
```

--------------------------------

### Resterm HTTP Request with RestermScript

Source: https://github.com/unkn0wn-root/resterm/blob/main/README.md

An example of an HTTP request file utilizing RestermScript directives. It imports a helper module, conditionally asserts a response status, and dynamically sets the Authorization header using a RestermScript function.

```http
# @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")) }}
```

--------------------------------

### Capturing and Reusing Tokens in Resterm

Source: https://github.com/unkn0wn-root/resterm/blob/main/docs/resterm.md

This example shows how to capture a token from a response and reuse it for subsequent authenticated requests in Resterm. The `@capture` directive extracts the token from the JSON response and stores it in a global variable, which is then used in the `Authorization` header for the next request.

```http
### Login
# @capture global-secret auth.token = response.json.token
POST {{base.url}}/login

{
  "user": "{{user.email}}",
  "password": "{{user.password}}"
}

### Authorized request
# @auth bearer {{auth.token}}
GET {{base.url}}/profile
```

--------------------------------

### Manual Terminal SSH Tunnel vs. Resterm (Bash)

Source: https://github.com/unkn0wn-root/resterm/blob/main/docs/resterm.md

Compares the manual process of setting up an SSH tunnel in the terminal using the 'ssh -L' command with Resterm's automated approach. Shows the equivalent Resterm configuration for achieving the same tunneling.

```bash
# Create tunnel in terminal
ssh -L 8080:10.0.0.100:80 ops@bastion.example.com
curl http://localhost:8080/api/users  # in another terminal

```