Skip to content
t-req t-req
HomeDocs

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:

  1. A modern terminal emulator like:

  2. API keys for the LLM providers you want to use.

Install

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

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

Initialize a Workspace

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

Terminal window
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.

  1. Launch t-req and run the /connect command:

    Terminal window
    treq
    /connect

  2. Select your provider and follow the instructions to add 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"
}

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 in HTTP file format with optional markdown documentation:

collections/{collection-name}/
├── collection.json             # Collection metadata
└── get-users/
    ├── request.http            # HTTP request file
    └── get-users.md            # Documentation

Example Request

GET {{BASE_URL}}/api/users?limit=10
Accept: application/json

Request IDs are the formatted directory names (e.g., get-users).

Environments

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

Environment Variables - Experimental

(this feature is experimental and may change or be removed without notice)

Create environment files in environments/:

environments/development.json
{
  "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 can be stored in .secrets.json files (automatically gitignored) or referenced directly from system environment variables using {env:VARIABLE_NAME} syntax.

See Environments for details.

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:

Terminal window
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