@t-req/app (t-req CLI)

t-req is an API testing CLI and HTTP client for .http files. Run requests, automate checks, and inspect responses from the command line, interactive TUI, or web dashboard.

Developer Workflow

# 1. Scaffold a new project
treq init my-api

# 2. Open the TUI + server (starts everything)
cd my-api && treq open

# 3. Browse .http files, execute requests, run scripts -- all from the TUI
#    Scripts automatically report HTTP requests back to the TUI (observer mode)

# 4. Or add --web to also open the browser dashboard
treq open --web

Installation

# Install via curl
curl -fsSL https://t-req.io/install | bash

# Or via package manager
npm install -g @t-req/app
bun add -g @t-req/app

Commands

treq open - Open workspace (recommended)

Starts the server and TUI together. This is the primary way to use t-req interactively.

# Open current directory
treq open

# Open a specific workspace
treq open ./my-api

# Open with the web dashboard in your browser
treq open --web

# Custom port
treq open --port 8080

Options

Security: a random token is generated on every launch. --web and --expose cannot be combined (SSRF protection).

treq init - Create a new project

treq init my-project

This will prompt you to select:

• Runtime: bun (recommended) or node
• Package manager: bun, npm, pnpm, or yarn

Skip prompts with defaults:

treq init my-project --yes

Uses defaults: bun runtime, bun package manager, bun test runner.

Skip test file generation:

treq init my-project --yes --no-tests

Use a specific test runner:

treq init my-project --yes --test-runner vitest

Options

Generated project structure

my-project/
├── treq.jsonc            # Project configuration
├── client.ts             # Shared t-req client
├── run.ts                # Example script (imports client)
├── tests/                # Test files (when tests enabled)
│   └── list.test.ts      # Example test for users/list.http
├── collection/
│   ├── posts/
│   │   └── create.http   # Example POST request
│   └── users/
│       ├── list.http     # Example GET request (list)
│       └── get.http      # Example GET request (single)
├── README.md
├── package.json
├── tsconfig.json
├── .treq/                # Local state (e.g. cookie jar)
└── .gitignore

treq run - Execute HTTP requests

Execute .http files directly from the command line:

# Execute the first request in a file
treq run collection/auth/login.http

# Use a config profile
treq run collection/auth/login.http --profile dev

# Execute a specific request by name
treq run collection/users.http --name "Get User"

# Execute a specific request by index
treq run collection/users.http --index 2

# Pass variables
treq run collection/auth/login.http --var email=test@example.com --var password=secret

# Legacy environment module (kept for compatibility)
# Loads environments/<env>.ts or environments/<env>.js from the workspace
treq run collection/auth/login.http --env dev

# Set timeout (in milliseconds)
treq run collection/auth/login.http --timeout 30000

# Verbose output (show headers)
treq run collection/auth/login.http --verbose

Options

treq ws - Test WebSocket sessions

Open an interactive or batch WebSocket session through a running t-req server.

# URL mode (interactive)
treq ws wss://echo.websocket.events

# File mode (select by name)
treq ws --file collection/chat.http --name connect --profile dev

# Batch mode with one-shot payload
treq ws wss://echo.websocket.events --execute '{"ping":true}' --wait 2

# NDJSON output for automation
echo '{"ping":true}' | treq ws wss://echo.websocket.events --json

Options

Use exactly one request source: URL positional argument or --file.

treq serve - Start HTTP server

Start an HTTP server that exposes the t-req API, enabling any programming language to execute .http files:

# Start server on default port (4097)
treq serve

# Custom port
treq serve --port 8080

# Bind to all interfaces (for remote access)
treq serve --host 0.0.0.0 --token your-secret-token

# Enable CORS for specific origins
treq serve --cors "http://localhost:3000,http://localhost:5173"

# stdio mode (JSON-RPC over stdin/stdout)
treq serve --stdio

Options

API Endpoints

When --token auth is enabled, /event and /event/ws require either sessionId or flowId to prevent cross-session leakage.

Example: Python Client

import requests

# Execute a request
response = requests.post("http://localhost:4097/execute", json={
    "content": "GET https://api.example.com/users",
    "variables": {"token": "abc123"}
})
print(response.json())

Example: Go Client

resp, _ := http.Post("http://localhost:4097/execute", "application/json",
    strings.NewReader(`{"content": "GET https://api.example.com/users"}`))

Example: SSE Streaming (curl)

curl -N -X POST http://localhost:4097/execute/sse \
  -H "Content-Type: application/json" \
  -d '{"content": "# @sse\nGET https://sse.dev/test\n"}'

Example: WebSocket Session Execute (curl)

curl -X POST http://localhost:4097/execute/ws \
  -H "Content-Type: application/json" \
  -d '{"content": "# @ws\nGET wss://echo.websocket.events\n"}'

See examples/app/ for complete client examples in Python, Go, and TypeScript.

treq tui - Connect to existing server

Launch the TUI and connect to a server that is already running (started separately with treq serve).

# Connect to default server
treq tui

# Connect to a custom server
treq tui --server http://localhost:8080 --token my-token

Options

treq upgrade - Upgrade treq

Upgrade treq to the latest version (or a specific version). Auto-detects the installation method.

# Upgrade to latest
treq upgrade

# Upgrade to a specific version
treq upgrade 0.3.0

Auto-update

Interactive commands (treq open, treq tui, treq web) perform startup update checks and attempt auto-upgrade for known install methods.

• Checks are cached for 24 hours in ~/.treq/auto-update.json
• Failed auto-upgrade attempts are backed off for 24 hours for the same target version
• Successful installs apply on the next run (current process continues)
• Use --no-auto-update to disable per command
• Use TREQ_AUTO_UPDATE=0 to disable via environment variable

Help

treq --help
treq init --help
treq run --help
treq ws --help
treq serve --help
treq open --help

TUI

The TUI provides an interactive terminal interface for browsing and executing your workspace.

Layout

• Left panel: Executions list
• Right panel: Execution details with tabs for body, headers, plugins, and output

Keyboard Shortcuts

Script & Test Runner

The TUI can run scripts and tests directly. Supported runners:

Scripts: bun, node, npx tsx, npx ts-node, python Test frameworks: bun test, vitest, jest, pytest

Runners are auto-detected from your project's lockfiles, config files, and package.json devDependencies.

Observer Mode

Observer mode lets your scripts report HTTP requests back to the TUI and web dashboard with zero code changes.

When you run a script from the TUI (or web dashboard), t-req injects these environment variables into the child process:

@t-req/core's createClient() auto-detects TREQ_SERVER and routes requests through the server instead of executing them locally. Every request appears in the TUI/dashboard in real time via SSE.

The injected token is scoped to the specific flow and session, and is revoked when the script exits.

No code changes needed -- if your script already uses createClient(), observer mode works automatically.

Protocol Version

The server uses protocol version 1.1.

Migration note: 1.0 -> 1.1

1.1 is additive:

• Existing /execute, /execute/sse, and /event workflows are unchanged.
• New WebSocket capabilities are available via:
  • POST /execute/ws
  • GET /ws/session/{wsSessionId}
  • GET /event/ws

WebSocket scope in 1.1

• .http WebSocket blocks are connection definitions (messages are runtime-driven).
• Binary WebSocket payloads are not supported in 1.1 (binaryPayloads: false).
• Replay is bounded in-memory only (no durable event history).
• Client-specific UI workflows are intentionally out of scope at the protocol layer.

/health is intentionally lean and only returns a basic status and server version:

{
  "healthy": true,
  "version": "0.1.0"
}

Security

• Localhost by default: Server binds to 127.0.0.1 unless --host is specified
• Token authentication: Use --token flag for bearer auth (required for remote access)
• Path scoping: All file paths are relative to workspace root; absolute paths and .. traversal are rejected
• CORS disabled by default: Use --cors to enable specific origins

License

MIT