Getman

Command-line HTTP API tester. Define routes in a TOML config file, run them from the terminal.

How it works

Create a getman.toml file describing the API endpoints you want to test:

[route.healthcheck]
path = "/"

Run it:

getman --collection getman.toml run .

getman sends the request and prints the response.

Route config

Field	What it does	Example
path	URL path (combined with base from client config)	/users
method	HTTP method (default GET)	POST, PUT
headers	Request headers	Authorization = "Bearer token123"
query	URL query parameters	{ page = 1, limit = 10 }
body	Request body (text or JSON)	{ name = "Alice" }
status	Expected response status code	201
extract	How to read the response (body, header, regex, jq, discard, debug)	.id or { type = "header", key = "Set-Cookie" }
expect	Assert the extracted value	"user_123"
absolute	Skip base URL composition	true

Client config

[client]
base = "https://api.example.com"
timeout = 30
redirects = 5
user_agent = "getman/1.0"
headers = { X-API-Key = "${API_KEY}" }

Environment variables

Use ${VAR_NAME} in any field. Variables are resolved from the [env] section first, then from the process environment.

[env]
API_KEY = "my-secret-key"

[route.get-user]
path = "/users/me"
headers = { Authorization = "Bearer ${API_KEY}" }

Built-in variables:

• ${GETMAN_TIMESTAMP} — current Unix timestamp
• ${GETMAN_TODAY} — current date (DD/MM/YYYY)
• ${GETMAN_LOCAL_ID} — random ID per request
• ${GETMAN_SESSION_ID} — persistent ID for the session

Commands

Command	What it does
getman	List all routes (compact)
getman list --full	List routes with all details
getman run .	Run all routes
getman run healthcheck	Run routes matching "healthcheck" (regex filter)
getman run . --parallel	Run all routes concurrently
getman run . --debug	Show full response details
getman run . --dry-run	Preview which routes would match
getman --report run .	Output results as JSON (one line per route)
getman --collection path/to/file.toml run .	Use a custom config file

Exit codes

getman run exits with code 0 if all routes pass, 1 if any route fails — suitable for CI pipelines.

Example

[env]
PW_TOKEN = "set-me-as-an-environment-variable!"

[client]
user_agent = "getman@sample/0.1.0"
timeout = 60
redirects = 5
base = "https://api.alemi.dev"

[route.healthcheck]
path = "/"

[route.debug]
path = "/debug"
method = "PUT"
query = { body = "json", cache = 0 }
headers = { Content-Type = "application/json", Authorization = "Bearer ${PW_TOKEN}" }
body = { hello = "world!", success = true }

[route.payload]
path = "/debug"
method = "POST"
body = '''{"complex": {"json": "payloads"}}'''
extract = ".path"
expect = "/debug"

[route.cookie]
path = "/getcookie"
method = "GET"
extract = { type = "header", key = "Set-Cookie" }

[route.notfound]
path = "https://cdn.alemi.dev/does-not-exist"
absolute = true
status = 404
extract = { type = "regex", pattern = "nginx/[0-9.]+" }

Installation

pip install getman

Or from source:

git clone <repo-url>
cd getman
pip install -e .