Table of Contents

Getting Started

• Overview
• Installation
• Quick Start
• CLI Usage

Features

• Three-Pane Layout
• Fuzzy Search
• Schema Validation
• Mock Export

Integrations

• Ecosystem Integrations

Development

• Available Scripts
• Tech Stack
• Project Structure

Overview

spec-tui is a keyboard-driven TUI alternative to Swagger UI and Scalar. It parses any OpenAPI 3.x spec and renders an interactive three-pane interface for exploring endpoints, building requests with validated inputs, and inspecting responses — all without leaving the terminal.

What Makes This Project Unique

• Terminal-Native: No browser needed — explore APIs from the same terminal where you code
• Schema-Driven Validation: Zod validators generated from JSON Schema catch input errors before sending
• Ecosystem Bridges: Integrates with env-lock (auth), mesh-sync (auto-refresh), and run-ctx (base URLs)
• Mock Generation: Export any API response as a typed TypeScript mock file for unit tests

Installation

# Install globally from npm
npm install -g @yaos-git/spec-tui

# Or install as a dev dependency
npm install -D @yaos-git/spec-tui

From Source

# Clone the repository
git clone https://github.com/YAOSGit/spec-tui.git
cd spec-tui

# Install dependencies
npm install

# Build the project
npm run build

# Link globally (optional)
npm link

Quick Start

# Point at a local spec file
spec-tui ./petstore.yaml

# Or a remote URL
spec-tui https://petstore3.swagger.io/api/v3/openapi.json

The TUI will parse the spec and render all endpoints in a navigable three-pane layout.

CLI Usage

spec-tui <spec>                    Open an OpenAPI spec (path or URL)
spec-tui <spec> -b <url>           Override the base URL from the spec
spec-tui --help, -h                Show help message
spec-tui --version, -v             Show version information

Examples

# Open a local file
spec-tui petstore.yaml

# Open a remote spec
spec-tui https://api.example.com/openapi.json

# Override base URL for staging
spec-tui petstore.yaml -b https://staging.api.com

# Print version
spec-tui --version

Three-Pane Layout

The TUI is organized into three panes:

Endpoint Navigator (Left)

• Browse all API operations grouped by tags
• Color-coded HTTP methods: GET (green), POST (yellow), PUT (blue), PATCH (cyan), DELETE (red)
• Keyboard navigation with visual selection indicator
• Deprecated endpoints are visually dimmed

Request Workshop (Center)

• Dynamic input forms auto-generated from OpenAPI parameters and request body schemas
• Real-time Zod validation against the spec before sending
• Integration with env-lock for auto-injecting auth headers

Response & Schema Viewer (Right)

• Response body with status code and timing
• TypeScript-like schema view converted from JSON Schema
• Request history for replaying previous calls

Fuzzy Search

Filter endpoints by any field using fuse.js-powered fuzzy matching:

• Path: /pets, /users/{id}
• Summary: List all pets, Create user
• Operation ID: listPets, createUser
• Tags: pets, admin

Schema Validation

Request inputs are validated at runtime using Zod schemas auto-generated from the OpenAPI spec's JSON Schema definitions. This catches type mismatches, missing required fields, and invalid values before the request is sent.

Mock Export

After receiving a response, export it as a typed TypeScript mock file:

// Auto-generated mock from spec-tui
// Status: 200 OK
// Captured: 2026-03-04T00:00:00.000Z

export const listPetsMock = [
  { "id": 1, "name": "Rex" }
] as const;

Ecosystem Integrations

| Integration | Env Variable | Description | |-------------|-------------|-------------| | env-lock | ENV_LOCK_TOKEN | Auto-injects Bearer token into request headers | | mesh-sync | — | Detects when spec file is managed by mesh-sync for auto-refresh | | run-ctx | SPEC_TUI_BASE_URL | Overrides base URL for context-aware environments |

Available Scripts

Development Scripts

| Script | Description | |--------|-------------| | npm run dev | Run TypeScript checking + test watcher concurrently | | npm run dev:typescript | Run TypeScript type checking in watch mode | | npm run dev:test | Run Vitest in watch mode |

Build Scripts

| Script | Description | |--------|-------------| | npm run build | Bundle the CLI with esbuild |

Lint Scripts

| Script | Description | |--------|-------------| | npm run lint | Run type checking, linting, formatting, and audit | | npm run lint:check | Check code for linting issues with Biome | | npm run lint:fix | Check and fix linting issues with Biome | | npm run lint:format | Format all files with Biome | | npm run lint:types | Run TypeScript type checking only | | npm run lint:audit | Run npm audit |

Testing Scripts

| Script | Description | |--------|-------------| | npm test | Run all tests (unit, react, types, e2e) | | npm run test:unit | Run unit tests | | npm run test:react | Run React component tests | | npm run test:types | Run type-level tests | | npm run test:e2e | Build and run end-to-end tests |

Tech Stack

Core

• React 19 — UI component library
• Ink 6 — React for CLIs
• TypeScript 5 — Type-safe JavaScript
• @apidevtools/swagger-parser — OpenAPI parsing and $ref resolution
• fuse.js — Lightweight fuzzy search
• Zod — Runtime schema validation
• axios — HTTP client

Build & Development

• esbuild — Fast bundler
• Vitest — Unit testing framework
• Biome — Linter and formatter

UI Components

• @inkjs/ui — Ink UI components
• Chalk — Terminal string styling

Project Structure

spec-tui/
├── src/
│   ├── app/                    # Application entry points
│   │   ├── cli.tsx             # CLI entry point (Commander)
│   │   ├── app.tsx             # Main three-pane layout
│   │   ├── index.tsx           # React app root
│   │   └── providers.tsx       # Provider wrapper
│   ├── components/             # React (Ink) components
│   │   ├── EndpointNavigator/  # Left pane — endpoint list
│   │   ├── StatusBar/          # Top bar — spec info
│   │   ├── ResponseViewer/     # Right pane — response display
│   │   └── SchemaViewer/       # Right pane — schema display
│   ├── parser/                 # OpenAPI parsing
│   │   ├── openapi/            # Spec → Endpoint[] extraction
│   │   └── schemaToZod/        # JSON Schema → Zod validators
│   ├── providers/              # React context providers
│   │   ├── SpecProvider/       # Parsed spec state
│   │   ├── NavigationProvider/ # Pane/selection state
│   │   └── RequestProvider/    # Request/response state
│   ├── types/                  # TypeScript type definitions
│   │   ├── Endpoint/           # Endpoint, HttpMethod, Parameter
│   │   ├── RequestConfig/      # Request configuration
│   │   ├── ResponseData/       # Response and history types
│   │   └── AppConfig/          # CLI configuration
│   ├── utils/                  # Utility functions
│   │   ├── request/            # URL builder and HTTP executor
│   │   ├── search/             # Fuzzy endpoint search (fuse.js)
│   │   ├── schemaToType/       # JSON Schema → TypeScript string
│   │   └── mock/               # Mock file generator
│   └── integrations/           # Ecosystem bridges
│       ├── envLock/            # env-lock auth header injection
│       ├── meshSync/           # mesh-sync managed spec detection
│       └── runCtx/             # run-ctx base URL resolution
├── e2e/                        # End-to-end tests
├── examples/                   # Example OpenAPI specs
│   └── basic/petstore.yaml
├── biome.json                  # Biome configuration
├── tsconfig.json               # TypeScript configuration
├── vitest.unit.config.ts       # Unit test configuration
├── vitest.react.config.ts      # React test configuration
├── vitest.type.config.ts       # Type test configuration
├── vitest.e2e.config.ts        # E2E test configuration
├── esbuild.config.js           # esbuild bundler configuration
└── package.json

Versioning

This project uses a custom versioning scheme: MAJORYY.MINOR.PATCH

| Part | Description | Example | |------|-------------|---------| | MAJOR | Major version number | 1 | | YY | Year (last 2 digits) | 26 for 2026 | | MINOR | Minor version | 0 | | PATCH | Patch version | 0 |

Example: 126.0.0 = Major version 1, released in 2026, minor 0, patch 0

License

ISC