🦾 Getman — Declarative API Tester for CLI & TUI

Define API routes in TOML config files, run them from terminal or TUI with assertions and extractors. Like Postman for your shell, with CI-friendly output.

🎯 What It Does

Getman is a CLI and TUI tool for testing HTTP APIs. Define your API routes in simple TOML configuration files, then run them from the command line with automatic assertions, response extraction, and CI-friendly JSON reports.

$ getman run collections/api.toml
✓ GET /api/users → 200 (342ms)
✓ POST /api/users → 201 (156ms)
✗ GET /api/users/:id → 404 (expected 200)

It supports parallel execution, environment variable interpolation, dynamic request chaining, and a full Textual TUI for interactive exploration.

🧱 Tech Stack

🏗️ Architecture

getman/
├── cli.py          # Click CLI: run, list, tui subcommands
├── collection.py   # TOML loading → Collection/RouteConfig/ClientConfig dataclasses
├── client.py       # httpx AsyncClient builder from config
├── runner.py       # Async request execution orchestration
├── extractors.py   # Response extraction strategies
├── reporter.py     # Output formatting + JSON report
├── tui.py          # Textual App with route list, detail panel, result log
└── errors.py       # Custom exceptions

📋 TOML Route Definitions

Routes are declared in TOML files — clean, readable, and version-controllable:

[env]
base_url = "https://api.example.com"
token = "${API_TOKEN}"

[[routes]]
name = "List Users"
method = "GET"
path = "/users"
expected = 200

[[routes]]
name = "Create User"
method = "POST"
path = "/users"
headers = { Authorization = "Bearer ${token}" }
body = { name = "Alice", email = "alice@example.com" }
expected = 201

[[routes]]
name = "Get User"
method = "GET"
path = "/users/${userId}"
expected = 200

🔧 Response Extractors

Extract and inspect parts of the response:

Routes can reference extracted values from previous routes using session variables, enabling request chaining:

[[routes]]
name = "Create User"
extract = { userId = "json(.id)" }

[[routes]]
name = "Get Created User"
path = "/users/${userId}"

🖥️ TUI Mode

The Textual TUI provides an interactive three-panel layout:

• Left: Route list with check/status indicators
• Center: Route detail view with request/response panels
• Bottom: Execution log with timestamps and results

Navigate with arrow keys, run individual routes or entire collections, and inspect responses without leaving the terminal.

📊 CI Integration

Getman produces JSON reports suitable for CI pipelines:

getman run collections/api.toml --report report.json

Exit code is 0 if all assertions pass, 1 if any fail — standard CI convention. The JSON report includes per-route timing, status codes, and assertion results.

🚀 Quick Start

pip install getman

# Create a collection
getman init > api.toml

# List routes
getman list api.toml

# Run all routes
getman run api.toml

# Run matching routes (regex filter)
getman run api.toml --filter "user"

# Launch TUI
getman tui api.toml

💡 Why It’s Interesting

Getman solves a real pain: testing APIs should not require a GUI tool or writing pytest boilerplate. The TOML-as-config approach means your API tests are declarative, readable, and live in version control alongside your code. Parallel execution, variable interpolation, JMESPath extraction, and CI-friendly output make it a legitimate alternative to Postman for developer workflows — entirely in your terminal.