spectralab

Curl Cookbook

Mon, 01 Jan 0001 00:00:00 +0000

Curl Cookbook#

Every example below works against the real stub files shipped in the repository (stubs/) with the server running on its default port:

simuhook

Static Response#

curl http://localhost:8080/health
# → {"status":"ok"}

Source: health.yaml — minimal static response.

Wildcard Method#

curl http://localhost:8080/catch-all
curl -X POST http://localhost:8080/catch-all
curl -X DELETE http://localhost:8080/catch-all
# → {"message":"matched any method"}

Source: method-match.yaml — empty method matches any verb.

Query Parameter Matching#

curl "http://localhost:8080/ping?ping_id=11022022&ping_child=43443"
# → {"message":"pong"}

Source: ping.yaml — both params required with exact values. Missing either → 404.

Echo Mode

Mon, 01 Jan 0001 00:00:00 +0000

Echo Mode#

echo: true makes Simuhook return the request body verbatim as the response.

id: debug-echo
method: POST
path: /webhooks/echo
response:
 status_code: 200
 echo: true

curl -X POST http://localhost:8080/webhooks/echo \
 -H "Content-Type: application/json" \
 -d '{"hello":"world"}'
# → {"hello":"world"}

Why It’s Useful#

Echo mode is a debugging tool — it shows you exactly what your client is sending, byte for byte. Combined with the TUI dashboard you can see the request headers, query, body, and the echoed response all in one place.

Installation

Mon, 01 Jan 0001 00:00:00 +0000

Installation#

Download a Binary#

Pre-built binaries are available for the following platforms:

Platform	Architecture
macOS	Apple Silicon (arm64)
macOS	Intel (amd64)
Linux	arm64
Linux	amd64

Download the binary for your platform, extract it, make it executable, and move it somewhere on your PATH:

chmod +x simuhook-darwin-arm64
mv simuhook-darwin-arm64 /usr/local/bin/simuhook

Build from Source#

Requires Go 1.21+.

git clone https://github.com/abojaber/simuhook
cd simuhook
go build -o simuhook ./src

This produces the simuhook binary in the current directory.

Overview

Mon, 01 Jan 0001 00:00:00 +0000

Dashboard Overview#

The dashboard is a single full-screen terminal view, refreshed once per second, showing everything happening in your Simuhook instance.

Running the Dashboard#

Mode	When it starts
`--tui auto` (default)	On a terminal (TTY); falls back to one-line-per-request output otherwise.
`--tui on`	Always shows the dashboard, even piped.
`--tui off`	Never shows the dashboard; prints the startup banner + one line per request.

simuhook # dashboard on a normal terminal
simuhook --tui off # line output

What It Shows#

Wide Layout (terminal ≥ 100 columns wide)#

At a normal terminal size the dashboard shows two side-by-side panels:

Variables

Mon, 01 Jan 0001 00:00:00 +0000

Template Variables#

When template: true is set on a response, the response body and header values are rendered as a Go template. These variables are available:

Variable	Description
`{{.UUID}}`	UUID v4 — unique per request
`{{.Now}}`	Current time in RFC3339 format
`{{.Timestamp}}`	Current Unix timestamp (seconds)
`{{.RequestID}}`	Unique request ID (also logged)
`{{.Method}}`	Incoming HTTP method
`{{.Path}}`	Incoming URL path
`{{.Body}}`	Raw request body

Example#

id: order-created
method: POST
path: /webhooks/orders
response:
 status_code: 200
 template: true
 headers:
 X-Request-ID: "{{.RequestID}}"
 X-Timestamp: "{{.Now}}"
 body: '{"id":"{{.UUID}}","event":"order.created","timestamp":{{.Timestamp}},"method":"{{.Method}}","body":"{{.Body}}"}'

Send a request:

YAML Reference

Mon, 01 Jan 0001 00:00:00 +0000

YAML Reference#

Each .yaml / .yml file in the stubs directory defines one endpoint. Every field is optional unless marked required.

Minimal Stub#

id: my-endpoint
path: /some/path
response:
 status_code: 200

Full Stub — Every Option#

id: my-endpoint
method: POST  # HTTP method (empty = match any)
path: /webhooks/event  # URL path (exact match)
path_glob: /users/**  # URL path glob (see Path Patterns)
path_regex: '^/orders/[0-9]{5}$' # URL path regex (RE2 — anchor with ^…$ yourself)
headers: # Request headers to match (optional)
 X-Event: event.created
query: # Query params to match (optional)
 token: abc123
payload: '{"type":"test"}' # Exact request body to match (optional)
payload_contains: '{"event":"user.created"}' # Partial JSON request-body match (optional)
response:
 status_code: 201 # HTTP status (default: 200)
 body: '{"ok":true}' # Response body (optional)
 headers: # Response headers (optional)
 Content-Type: application/json
 X-Custom: myvalue
 delay: 300ms  # Simulated latency (optional)
 echo: true # Return request body verbatim (optional)
 template: true # Enable Go template in body/headers (optional)

Field Reference#

Field	Required	Type	Description
`id`	yes	string	Unique endpoint identifier. Used as the stub name in logs and the dashboard.
`method`	no	string	HTTP method the request must use (`GET`, `POST`, …). Empty matches any method.
`path`	no*	string	Exact request path to match.
`path_glob`	no*	string	Segment-wise glob path match (`*`, ``, `?`).
`path_regex`	no*	string	Go RE2 regex path match (not implicitly anchored).
`headers`	no	map	Request headers that must be present with exact values.
`query`	no	map	Query params that must be present with exact values.
`payload`	no	string	Exact request body the request must match (byte-level).
`payload_contains`	no	string	Partial JSON spec the request body must contain.
`response.status_code`	no	int	HTTP status code to return (default: `200`).
`response.body`	no	string	Response body. Ignored when `echo: true`.
`response.headers`	no	map	Response headers to send.
`response.delay`	no	duration	Simulated latency before responding (e.g. `200ms`, `1s`).
`response.echo`	no	bool	Return the request body verbatim.
`response.template`	no	bool	Process `body`/headers as a Go template.
`responses[]`	no	list	Multiple response variants with weights (see below).

* Exactly one of path / path_glob / path_regex per stub. Setting more than one fails to load with a parse error naming the stub ID and the conflicting fields. A stub with none of them is also invalid — you must match on something.

Functions

Mon, 01 Jan 0001 00:00:00 +0000

Template Functions#

Beyond the request variables, templates can call functions — either built-in request helpers or random generators.

Request Helpers#

Function	Description
`{{Header "X-Key"}}`	Value of a request header (empty string if absent).
`{{Query "param"}}`	Value of a query parameter (empty string if absent).

Random Helpers#

Function	Description
`{{RandomInt 1 100}}`	Random integer in the inclusive range.
`{{RandomHex 8}}`	Random hex string of the given length.

The full set of realistic random data generators — {{Name}}, {{Email}}, {{Company}}, etc. — is on the Faker Generators page.

Key Bindings

Mon, 01 Jan 0001 00:00:00 +0000

Key Bindings#

Press ? inside the dashboard for this reference anytime.

Actions#

Key	Action
`q` / `ctrl+c`	Quit (in the filter prompt, cancels the prompt first)

The feed has a highlight cursor. Cursor keys move it entry-by-entry; the view auto-scrolls to keep the selection visible.

Key	Action
`j` / `↓`	Move cursor down one entry (+ auto-scroll)
`k` / `↑`	Move cursor up one entry (+ auto-scroll)
`pgup` / `pgdn` / `b` / `space`	Jump cursor a full page (+ auto-scroll)
`u` / `ctrl+u` / `d` / `ctrl+d`	Jump cursor half a page (+ auto-scroll)
`g` / `G`	Jump cursor to the top / bottom of the feed (`g` pauses live-follow, `G` resumes it)

Inspecting#

Key	Action
`enter`	Expand / collapse the selected row inline (full request + response detail)
`i`	Toggle the standalone request/response inspector
`esc` / `c`	Collapse an expansion / clear a filter (context dependent)

Filtering#

Key	Action
`/` or `f`	Open the filter prompt
`enter`	Apply the filter (in prompt)
`esc`	Cancel the prompt / clear the filter
`c`	Clear the filter

Dashboard Control#

Key	Action
`L`	Pause / resume live-follow (freezes / resumes the feed)
`e`	Toggle the endpoints panel (wide layout)
`r`	Manual refresh
`?`	Toggle the help overlay
`shift+↑` / `shift+↓` or `K` / `J`	Scroll the endpoints panel (wide layout, left visible)

Notes#

Cursor movement never resumes live-follow — even when the cursor is on the newest entry. Use L to resume, or G to jump to the bottom and resume.
Escaping or collapsing an expansion returns the cursor to the newest entry and resumes live-follow.

Matching

Mon, 01 Jan 0001 00:00:00 +0000

Request Matching#

An endpoint matches a request when all specified conditions are met:

Field	Behavior
`method`	Must equal the request method. Empty matches any method.
`path` / `path_glob` / `path_regex`	Exactly one path matcher — exact, glob, or regex.
`headers`	All listed headers must be present with the exact values.
`query`	All listed query params must be present with the exact values.
`payload` / `payload_contains`	The request body must match exactly, or contain the JSON subset.

Request matching is AND logic: every condition you specify must hold. Conditions you don’t specify are ignored.

Quick Start

Mon, 01 Jan 0001 00:00:00 +0000

Quick Start#

Five steps from zero to a working mocked endpoint.

1. Start the Server#

simuhook

The server starts on :8080, watches the stubs/ directory, and logs requests to logs/. On a terminal it opens the interactive TUI dashboard; on a non-TTY (like a pipe) it prints a startup banner and one line per request.

2. Verify It’s Running#

curl http://localhost:8080/health
# → {"status":"ok"}

The repository ships with example stubs, including a GET /health endpoint.

Response Variants

Mon, 01 Jan 0001 00:00:00 +0000

Response Variants#

A stub can define several possible responses with a responses[] list instead of a single response. This lets you simulate flaky or varied third-party behavior: mostly success, sometimes an error, occasionally a timeout.

id: flaky-webhook
method: POST
path: /webhooks/payment
responses:
 - status_code: 200
 body: '{"status":"completed","transaction_id":"txn_12345"}'
 weight: 80
 - status_code: 400
 body: '{"error":"insufficient_funds"}'
 weight: 15
 - status_code: 500
 body: '{"error":"internal_error"}'
 weight: 5
 delay: 2s

Send the same request several times and you’ll see roughly: 80% succeed, 15% get a 400, 5% get a slow 500.

REST API Guide

Mon, 01 Jan 0001 00:00:00 +0000

RESTful API Simulation — Patterns#

How to simulate RESTful API behavior with Simuhook stub files. Nine patterns, each with a YAML stub, the curl command, and a link to the shipped example.

CRUD ↔ HTTP Mapping#

Operation	HTTP Method	Typical Status	Example Stub
List / Read	`GET`	`200 OK`	`health.yaml`, `ping.yaml`
Create	`POST`	`201 Created`	`user-create.yaml`
Replace	`PUT`	`200 OK`	—
Partial update	`PATCH`	`200 OK`	—
Delete	`DELETE`	`204 No Content`	—
Any method	(empty)	`200 OK`	`method-match.yaml`

1. Static Read Endpoint#

Return a fixed JSON response for a GET request.

Configuration

Mon, 01 Jan 0001 00:00:00 +0000

Configuration#

Simuhook is configured through CLI flags and environment variables. Flags take precedence over environment variables.

CLI Flags#

simuhook [flags]

 --addr :8080 listen address (env PORT)
 --stubs ../stubs stubs directory (env STUBS_DIR)
 --log-dir logs log directory (env LOG_DIR)
 --tui auto|on|off dashboard mode: auto = TUI on a TTY, line output otherwise
 --recent N recent-log ring buffer size (default 50; also the TUI feed depth)
 --max-log-body N cap stored request/response body size in bytes for logs and
 dashboard (default 0 = unlimited; env LOG_MAX_BODY). Never affects
 the actual HTTP response bytes.
 --help print usage and exit
 --version print version and exit

Environment Variables#

Variable	Default	Overrides
`PORT`	`:8080`	`--addr`
`STUBS_DIR`	`stubs/`	`--stubs`
`LOG_DIR`	`logs/`	`--log-dir`
`LOG_MAX_BODY`	`0` (unlimited)	`--max-log-body`

Common Scenarios#

Run on a different port:

Delays

Mon, 01 Jan 0001 00:00:00 +0000

Delays#

delay adds artificial latency before the response is sent — useful for testing client timeouts, retries, and back-off behavior.

id: slow-endpoint
path: /slow
response:
 status_code: 200
 body: '{"ok":true}'
 delay: 2s

time curl -s http://localhost:8080/slow
# → {"ok":true}
# real 0m2.003s

Duration Syntax#

delay accepts Go duration syntax:

YAML	Duration
`delay: 0s` (or omit)	Instant — normal operation
`delay: 200ms`	200 milliseconds
`delay: 500ms`	Moderate latency
`delay: 2s`	Client timeout testing
`delay: 5s`	Aggressive timeout testing
`delay: 2m30s`	Two and a half minutes

Where Delays Apply#

The singular response — response.delay.
Any variant inside responses[] — per-variant latency (each variant can have a different delay).

id: flaky-webhook
method: POST
path: /webhooks/payment
responses:
 - status_code: 200
 body: '{"status":"completed"}'
 weight: 80
 - status_code: 500
 body: '{"error":"internal_error"}'
 weight: 5
 delay: 2s  # only this variant is slow

Notes#

Delays are applied after the request is matched and template data is built, and the measured latency in the logs and dashboard includes the delay.
The dashboard’s latency stats (avg/min/max/p95) count the artificial delay, so a delay: 2s stub will show up in p95 — expected, since that’s the latency your client experiences too.

Also See#

stubs/user-create.yaml — 200ms delay.
stubs/order-placed.yaml — 500ms delay.
stubs/flaky-webhook.yaml — 2s delay on one variant.

Faker Generators

Mon, 01 Jan 0001 00:00:00 +0000

Faker Data Generators#

Simuhook ships a curated set of 27 realistic random data generators, powered by gofakeit. Each call renders a realistic random value — a name, an email, a price — so your mock responses look like data from a real third-party service. All generators are thread-safe and return a fresh value per render.

Person#

Function	Example output
`{{Name}}`	`Markus Moen`
`{{FirstName}}`	`Fred`
`{{LastName}}`	`Moen`
`{{Email}}`	`alaynawuckert@kozey.biz`
`{{Phone}}`	`(570)245-7485`

Address#

Function	Example output
`{{City}}`	`Lake Maxine`
`{{Country}}`	`Canada`
`{{State}}`	`Nebraska`
`{{Zip}}`	`38762`
`{{Street}}`	`98789 Hane Locks`

Company#

Function	Example output
`{{Company}}`	`Moen, Pagac and Wuckert`
`{{JobTitle}}`	`Director`

Internet#

Function	Example output
`{{IPv4Address}}`	`192.168.1.42`
`{{IPv6Address}}`	`2001:db8::1`
`{{DomainName}}`	`kozey.biz`
`{{MACAddress}}`	`ab:cd:ef:01:23:45`
`{{UserAgent}}`	`Mozilla/5.0 …`

Payment#

Function	Example output
`{{CreditCardNumber}}`	`4287271570245748`
`{{Price}}`	`42.99`

Product & ID#

Function	Example output
`{{ProductName}}`	`Incredible Metal Chair`
`{{ULID}}`	`pfsfktb87rcmj6bqha2fz9`
`{{UUID}}`	`0d1e6f2a-…`

Text & Misc#

Function	Example output
`{{Word}}`	`river`
`{{Sentence}}`	`Record river mind.`
`{{Paragraph}}`	`Quia voluptatem…`
`{{HexColor}}`	`#a3e4f2`
`{{Bool}}`	`true`

Example — Webhook-Shaped Response#

id: customer-created
method: POST
path: /webhooks/customer
response:
 status_code: 200
 template: true
 body: '{"event":"customer.created","customer":{"id":"{{UUID}}","name":"{{Name}}","email":"{{Email}}","address":{"city":"{{City}}","country":"{{Country}}"}},"payment":{"card":"{{CreditCardNumber}}","amount":"{{Price}}","currency":"USD"}}'

Each request returns a full, realistic customer profile:

Filtering

Mon, 01 Jan 0001 00:00:00 +0000

Filtering#

Press / or f to open the filter prompt. Type a filter and press enter to apply; the feed shows only matching entries. Press esc or c to clear.

Filter Syntax#

Prefix	Matches
`ep:<id>`	Endpoint with that stub ID
`method:<METHOD>`	HTTP method (e.g. `method:POST`)
`status:<code>`	Response status code (e.g. `status:500`)
Bare text	Any text in the log line

Filters combine with spaces:

ep:ping status:200 method:GET

Matches entries for the ping endpoint that returned 200 via a GET.

Path Patterns

Mon, 01 Jan 0001 00:00:00 +0000

Path Patterns#

Simuhook supports three ways to match the request path. A stub may set exactly one of them.

Field	Semantics
`path`	Exact match on the raw URL path: `/api/users` matches `/api/users` only — never `/api/users/1` or `/api/users/1/orders`.
`path_glob`	Segment-wise glob with `*`, ``, and `?` wildcards.
`path_regex`	Go stdlib `regexp` (RE2). Not implicitly anchored — write `^…$` yourself for a full-path match.

Setting more than one is a load-time parse error naming the stub ID and the conflicting fields.

JSONPath

Mon, 01 Jan 0001 00:00:00 +0000

JSONPath#

{{JSONPath "$…"}} extracts a field from the JSON request body. The body is parsed once per request; {{.Body}} still renders the full raw body string.

Syntax#

Path	Meaning
`$`	The whole request body (as JSON string)
`$.user`	Object key `user`
`$.user.name`	Nested object key
`$.items[0]`	Array index 0
`$.items[0].name`	Nested into an array element
`$.items[1].tags[0]`	Deeper nesting

Return Semantics#

Value	Renders as
String	Unquoted (`Ada`)
Number	Unquoted (`42`, `42.5`)
Boolean	`true` / `false`
`null`	`null`
Object / array	Compact JSON (`{"a":1}`)
Missing path, out-of-bounds index, non-JSON body	Empty string (no panic, no fallback)

Example#

id: customer-echo
method: POST
path: /webhooks/customer-echo
response:
 status_code: 200
 template: true
 body: '{"received":{"id":"{{JSONPath "$.customer.id"}}","name":"{{JSONPath "$.customer.name"}}"},"full_payload":{{JSONPath "$"}}}'

Send a request:

Logging

Mon, 01 Jan 0001 00:00:00 +0000

Logging#

Every request to a webhook endpoint is logged as a JSON line:

Log file	Contents
`logs/<webhook-id>.log`	Matched requests for the endpoint with that `id`.
`logs/_unmatched.log`	Requests that matched no endpoint (responded `404`).

The log directory defaults to logs/ — override with --log-dir or the LOG_DIR environment variable.

Log Entry#

{
 "timestamp": "2026-08-18T10:30:00.123Z",
 "request_id": "uuid-v4",
 "webhook": "health",
 "method": "GET",
 "path": "/health",
 "headers": {"User-Agent": "curl/8.7.1"},
 "body": "",
 "query": {},
 "response_status": 200,
 "response_headers": {"Content-Type": "application/json"},
 "response_body": "",
 "latency_ms": 0.02,
 "matched": true
}

Field	Description
`timestamp`	Request time, RFC3339 with milliseconds (UTC).
`request_id`	Unique request ID (same value available in templates as `{{.RequestID}}`).
`webhook`	The endpoint `id` that matched (absent / empty for unmatched).
`method`	HTTP method.
`path`	Request path.
`headers`	Request headers (map).
`body`	Request body.
`query`	Query parameters (map).
`response_status`	Status code returned.
`response_headers`	Response headers (map).
`response_body`	Response body.
`latency_ms`	Total time to serve the request — includes any configured delay.
`matched`	`true` if a stub matched, `false` for a `404`.

Capping Stored Bodies#

Large payloads blow up your logs. --max-log-body N (or LOG_MAX_BODY) caps the stored body / response_body at capture time, in bytes:

Payload Matching

Mon, 01 Jan 0001 00:00:00 +0000

Payload Matching#

Simuhook can constrain a stub to specific request bodies — two ways, depending on whether you need an exact byte match or a partial JSON match.

Field	Meaning	Use when
`payload`	The request body must match exactly (byte-level).	You want to enforce that your client sends precisely the body you expect.
`payload_contains`	The request body must be valid JSON that contains the given spec.	You want to match on a few fields and ignore everything else.

A stub may set at most one of the two — setting both is a load-time parse error. Specs must be quoted in YAML; invalid spec JSON is a load-time parse error.

Changelog

Mon, 01 Jan 0001 00:00:00 +0000

Changelog#

v0.1.0#

Mock HTTP server: define endpoints as YAML files, watch the directory, hot-reload live, and log every request as a JSON line. Ships with a full-screen TUI dashboard.

Highlights#

Colorized request detail — enter expansion and i inspector show cyan labels/keys, yellow request bodies, green response bodies, and JSON syntax highlighting.
Response in the enter expansion — expanding a feed row shows the full response alongside the request: status-tinted RESPONSE header, response headers, and a multi-line response body. Unmatched requests show RESPONSE 404.
Request/response visual separation — a muted ─ separator plus full-width background bands (REQUEST dark gray 236, RESPONSE dark navy 17) make the two sides instantly distinguishable; response keys are magenta, request keys cyan.
--version flag — print the version and exit. Release builds carry v0.1.0 via ldflags; dev builds report dev.
TUI dashboard — live counts, latency stats (incl. approximate p95), filterable recent-request feed (ep:/method:/status: prefixes), per-endpoint stats, request/response inspector, pause/resume, g/G scroll jumps.
Mock engine — YAML stubs with method/path/query/header/payload matching, echo/template modes, configurable delay, weighted response variants (round-robin on equal weight), hot-reload via fsnotify.
Logging — every request (matched and unmatched) logged as a JSON line; --max-log-body caps stored body size.

CLI#

simuhook [flags]
 --addr :8080 listen address (env PORT)
 --stubs ../stubs stubs directory (env STUBS_DIR)
 --log-dir logs log directory (env LOG_DIR)
 --tui auto|on|off dashboard mode: auto = TUI on a TTY, line output otherwise
 --recent N recent-log ring buffer size (default 50)
 --max-log-body N cap stored body size for logs/dashboard (0 = unlimited; env LOG_MAX_BODY)
 --help, --version usage / version

Features In Depth#

Matching — method, exact path, glob path, regex path, query, headers, exact payload, and partial-JSON payload matching. Most-specific match wins deterministically.
Response templates — variables, Header/Query/RandomInt/RandomHex functions, 27 faker data generators, and JSONPath request-body extraction.
Dashboard — live dashboard with counts, latency stats (avg/min/max/p95), filterable feed, and per-request expansion and inspector views.
Logging — JSON Lines, per-endpoint files, unmatched request capture.

Binary Assets#

simuhook-darwin-arm64 (Apple Silicon)
simuhook-darwin-amd64 (Intel Mac)
simuhook-linux-arm64
simuhook-linux-amd64

See Installation for download and setup.

spectralab

Curl Cookbook

Curl Cookbook#

Static Response#

Wildcard Method#

Query Parameter Matching#

Echo Mode

Echo Mode#

Why It’s Useful#

Installation

Installation#

Download a Binary#

Build from Source#

Overview

Dashboard Overview#

Running the Dashboard#

What It Shows#

Wide Layout (terminal ≥ 100 columns wide)#

Variables

Template Variables#

Example#

YAML Reference

YAML Reference#

Minimal Stub#

Full Stub — Every Option#

Field Reference#

Functions

Template Functions#

Request Helpers#

Random Helpers#

Key Bindings

Key Bindings#

Actions#

Navigation#

Inspecting#

Filtering#

Dashboard Control#

Notes#

Matching

Request Matching#

Quick Start

Quick Start#

1. Start the Server#

2. Verify It’s Running#

Response Variants

Response Variants#

REST API Guide

RESTful API Simulation — Patterns#

CRUD ↔ HTTP Mapping#

1. Static Read Endpoint#

Configuration

Configuration#

CLI Flags#

Environment Variables#

Common Scenarios#

Delays

Delays#

Duration Syntax#

Where Delays Apply#

Notes#

Also See#

Faker Generators

Faker Data Generators#

Person#

Address#

Company#

Internet#

Payment#

Product & ID#

Text & Misc#

Example — Webhook-Shaped Response#

Filtering

Filtering#

Filter Syntax#

Path Patterns

Path Patterns#

JSONPath

JSONPath#

Syntax#

Return Semantics#