Skip to content

app

Directory actions

More options

Directory actions

More options

Latest commit

 

History

History

app

README.md

@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

Option Description
[workspace] Workspace root directory (default: .)
--port, -p Port to listen on (default: 4097)
--host, -H Host to bind to (default: 127.0.0.1)
--web Open the browser dashboard
--expose Allow non-loopback binding (disables cookie auth)
--auto-update / --no-auto-update Enable or disable startup auto-update checks (default: enabled)

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

Option Description
[name] Project name / directory
--yes, -y Skip prompts, use defaults
--no-tests Skip test file generation
--test-runner Test runner to use (bun, vitest, jest)

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

Option Description
--name, -n Select request by @name directive
--index, -i Select request by index (0-based)
--profile, -p Config profile to use
--env, -e Legacy environment module to load (environments/<env>.ts or environments/<env>.js)
--var Set variable (can be used multiple times)
--timeout, -t Request timeout in milliseconds
--workspace, -w Workspace root directory
--verbose, -v Show response headers

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

Option Description
[url] WebSocket URL (ws:// or wss://)
--file, -f Path to .http file containing a WebSocket request
--name, -n Select request by @name directive (file mode)
--index, -i Select request by index (0-based, file mode)
--profile, -p Config profile to use
--var, -v Variables in key=value format (repeatable)
--server, -s Server URL to connect to (default: http://127.0.0.1:4097)
--token, -t Bearer token for authentication
--timeout WebSocket connect timeout in milliseconds
--execute, -x Send one message and switch to batch wait behavior
--wait, -w Batch wait seconds before close (-1 waits indefinitely, default: 2)
--json Emit live NDJSON events (meta.connected, ws.outbound, ws.inbound, ws.error, meta.closed, meta.summary)
--verbose Show verbose output (~ frames and detailed error payloads)
--no-color Disable ANSI colors in human-readable mode

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

Option Description
--port, -p Port to listen on (default: 4097)
--host, -H Host to bind to (default: 127.0.0.1)
--token Bearer token for authentication
--cors Allowed CORS origins (comma-separated)
--workspace, -w Workspace root directory
--max-body-size Max response body size in bytes (default: 10MB)
--max-sessions Max concurrent sessions (default: 100)
--stdio Use JSON-RPC over stdin/stdout instead of HTTP

API Endpoints

Method Path Description
GET /health Server health and version info
GET /config Resolved config summary (supports ?profile= and ?path=)
POST /parse Parse .http file content
POST /execute Execute HTTP request
POST /execute/sse Execute SSE streaming request
POST /execute/ws Execute WebSocket request definition (server-owned session)
POST /session Create new session
GET /session/:id Get session state
PUT /session/:id/variables Update session variables
DELETE /session/:id Delete session
POST /flows Create a flow (Observer Mode grouping)
POST /flows/:flowId/finish Finish a flow (best-effort; server TTL will also clean up)
GET /flows/:flowId/executions/:reqExecId Fetch stored execution detail (Observer Mode)
GET /workspace/files List .http files in workspace
GET /workspace/requests?path=... List requests within a .http file
GET /event?sessionId=... SSE event stream filtered by session
GET /event?flowId=... SSE event stream filtered by flow
GET /event/ws?sessionId=... WebSocket event stream filtered by session
GET /event/ws?flowId=... WebSocket event stream filtered by flow
GET /ws/session/:wsSessionId Request session downstream control socket (WebSocket upgrade)
GET /doc OpenAPI documentation

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

Option Description
--server, -s Server URL to connect to (default: http://localhost:4097)
--token, -t Bearer token for authentication
--auto-update / --no-auto-update Enable or disable startup auto-update checks (default: enabled)

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

Key Action
j / Down Navigate down
k / Up Navigate up
Enter Execute selected file / toggle directory
Tab Toggle between File Tree and Executions panel
Ctrl+H Hide/show left panel
Ctrl+T File/request picker
Ctrl+P Command palette
Ctrl+E Open in external editor
1 / 2 / 3 / 4 Switch detail tab (body / headers / plugins / output)
Escape Cancel running script
Ctrl+C Quit

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:

Variable Purpose
TREQ_SERVER Server URL (e.g. http://localhost:4097)
TREQ_FLOW_ID Flow ID grouping related requests
TREQ_SESSION_ID Pre-created session ID
TREQ_TOKEN Scoped, short-lived auth token

@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