tsreq

TypeScript-first API client built on OpenAPI. File-based, type-safe, LLM-optimized.

A lightweight Postman alternative that:

• Lives inside your codebase (.api/ folder)
• Built on openapi.json — no new formats to learn
• TypeScript-first for type safety and autocomplete
• LLM-optimized (agents can create, run, and test requests)
• Handles environments, variables, and post-request scripts
• Long-lived sessions (auth tokens persist)

The Problem

Postman/Bruno pain points:

1. Proprietary formats — Bruno uses .bru, Postman uses JSON with custom schema
2. Not git-native — Collections sync to cloud, not your repo
3. No TypeScript types — LLMs and devs can't get autocomplete/validation
4. Not OpenAPI-first — Import works, but it's a one-way conversion
5. Heavy — Electron apps, accounts, cloud sync for a glorified HTTP client

The gap: No tool is truly file-first, OpenAPI-native, TypeScript-typed, and LLM-friendly.

The Solution

your-repo/
├── openapi.json              # Source of truth
├── .api/
│   ├── config.ts             # Environments, variables
│   ├── requests/
│   │   ├── auth.login.ts     # TypeScript request definitions
│   │   ├── users.get.ts
│   │   └── users.create.ts
│   └── scripts/
│       └── save-token.ts     # Post-request hooks

Request Definition

// .api/requests/auth.login.ts
import { defineRequest } from 'tsreq';
import { api } from '../generated';

export default defineRequest({
  operation: api.auth.login,
  
  body: {
    email: '{{env.TEST_EMAIL}}',
    password: '{{env.TEST_PASSWORD}}',
  },
  
  afterResponse: async (response, ctx) => {
    if (response.ok) {
      ctx.setVariable('accessToken', response.data.token);
    }
  },
});

Environment Config

// .api/config.ts
export default {
  environments: {
    local: { baseUrl: 'http://localhost:3000' },
    staging: { baseUrl: 'https://staging.api.example.com' },
    production: { baseUrl: 'https://api.example.com' },
  },
  
  variables: {
    accessToken: null,
  },
  
  session: {
    persist: true,
    ttl: '180d',
  },
};

CLI

# Run a request
tsreq run auth.login --env staging

# Run with variables
tsreq run users.create --var userId=123

# Generate types from OpenAPI
tsreq generate ./openapi.json

# Interactive TUI
tsreq

# JSON output for LLM consumption
tsreq run auth.login --json

Why TypeScript?

1. Types from OpenAPI — Generate types from openapi.json, requests are type-checked
2. LLMs love TS — Claude/GPT can write valid requests with autocomplete knowledge
3. ts-rest/tRPC compatible — Same contract, different runtime
4. Executable — Import in tests or run via CLI

Key Features

MVP

• Generate types from openapi.json
• TypeScript request definitions
• Environment variables (.env support)
• Post-request scripts (save tokens, etc.)
• CLI runner
• JSON output for LLM consumption

Planned

• TUI for interactive use
• Request chaining
• Session persistence
• Import from Bruno/Postman
• VS Code extension
• Watch mode
• Mock server from OpenAPI

Competitive Positioning

Tool	Format	OpenAPI	TypeScript	LLM-Friendly
Bruno	.bru (custom)	Import only	❌	⚠️
Postman	JSON (custom)	Import only	❌	❌
Slumber	YAML	❌	❌	✅
httpYac	.http	❌	❌	⚠️
tsreq	TypeScript	✅ Native	✅	✅

Development

# Install dependencies
bun install

# Start development
bun run dev

# Run checks
bun run check

Project Structure

tsreq/
├── apps/
│   ├── web/         # Landing page (Astro)
│   ├── docs/        # Documentation (Starlight)
│   └── tui/         # Terminal UI (OpenTUI)
├── packages/
│   └── ...          # Core library (coming soon)

Why Now?

1. LLMs are writing code — They need type-safe, file-based tools
2. Bruno proved the market — 22k+ GitHub stars for a file-first API client
3. TypeScript dominance — Most API backends are TS now
4. OpenAPI is standard — Everyone has it, no one builds on it properly

License

MIT

---

Built with Better-T-Stack and OpenTUI.