Intro

Get started with t-req.

t-req is an AI-powered HTTP client for your terminal. Think Postman meets Claude — an intelligent agent that helps you test APIs, manage collections, and work with API specifications.

Let’s get started.

Prerequisites

To use t-req in your terminal, you’ll need:

A modern terminal emulator like:
- WezTerm, cross-platform
- Alacritty, cross-platform
- Ghostty, Linux and macOS
- Kitty, Linux and macOS
API keys for the LLM providers you want to use.

Install

The easiest way to install t-req is through the install script.

curl -fsSL https://t-req.ai/install | bash

Initialize a Workspace

Navigate to your project directory and initialize a t-req workspace:

cd /path/to/project
treq init

This creates the following structure:

my-project/
├── workspace.json          # Workspace configuration
├── collections/            # HTTP request collections
├── environments/           # Environment variables & secrets
├── specs/                  # API specifications (OpenAPI, GraphQL, etc.)
├── lib/                    # Shared JavaScript libraries
└── history/                # Request execution history

Connect to a Provider

With t-req you can use any LLM provider by configuring their API keys.

Launch t-req and run the /connect command:
Terminal window
```
treq
```
```
/connect
```
Select treq and head to t-req.ai/auth.
Sign in, add your billing details, and copy your API key.
Paste your API key.
```
┌ API key
│
│
└ enter
```

Alternatively, you can select one of the other providers. Learn more.

Workspace Schema

The workspace.json file contains your workspace configuration:

{
  "id": "01KED8RRSM03G2AAVB9RRYDVFQ",
  "name": "my-api",
  "version": "1.0",
  "settings": {
    "timeout": 30000,
    "verifySsl": true,
    "cookieAutoCapture": true,
    "cookieSendFromJar": true
  }
}

Collections & Requests

Collections organize your HTTP requests into logical groups. Each collection lives in collections/ and contains requests supporting multiple protocols:

REST - Standard HTTP requests
GraphQL - GraphQL queries and mutations
gRPC - gRPC service calls
WebSocket - Real-time WebSocket connections
SSE - Server-Sent Events

Request Structure

Requests are stored as JSON with optional markdown documentation:

collections/{collectionId}/
├── api.json                    # Collection metadata
└── requests/
    └── get-users/
        ├── request.json        # Request definition
        └── get-users.md        # Documentation

Example Request

{
  "id": "01KED8RRSM03G2AAVB9RRYDVFQ",
  "name": "Get Users",
  "protocol": "rest",
  "rest": {
    "method": "GET",
    "path": "/api/users",
    "headers": [
      { "key": "Accept", "value": "application/json", "enabled": true }
    ],
    "queryParams": [
      { "key": "limit", "value": "10", "enabled": true }
    ]
  }
}

Environments

Environments let you manage variables across different stages (development, staging, production).

Environment Variables

Create environment files in environments/:

{
  "name": "development",
  "variables": [
    { "key": "baseUrl", "value": "http://localhost:3000", "type": "text", "enabled": true },
    { "key": "apiKey", "value": "", "type": "secret", "enabled": true, "valueSource": "secrets" }
  ]
}

Secrets

Secret values are stored separately in .secrets.json files (automatically gitignored):

{
  "apiKey": "sk-1234567890"
}

Variable Interpolation

Use {{variable}} syntax in your requests:

{
  "rest": {
    "path": "{{baseUrl}}/api/users",
    "headers": [
      { "key": "Authorization", "value": "Bearer {{apiKey}}", "enabled": true }
    ]
  }
}

Making Requests

Launch t-req and start making requests with AI assistance:

treq

With the AI Agent

Ask the agent to help you:

Create a POST request to /api/users with a JSON body containing name and email fields

Import the OpenAPI spec from https://api.example.com/openapi.json

Set up environments for dev and production with different base URLs

Plan Mode

Use Tab to switch to Plan mode. The agent will suggest changes without executing them — perfect for reviewing complex operations before applying.

<TAB>

Import API Specs

Import OpenAPI, GraphQL, or other API specifications:

/import https://api.example.com/openapi.json

Specs are stored in the specs/ directory:

specs/
├── index.json              # Spec registry
├── rest/                   # OpenAPI specs
├── graphql/                # GraphQL schemas
├── grpc/                   # gRPC proto files
└── async/                  # AsyncAPI specs

Customize

You’re ready to use t-req! To make it your own, check out:

Themes — Customize the look and feel
Keybinds — Configure keyboard shortcuts
Config — Advanced configuration options