HTTP Playbook executioner — a single Go binary that runs playbooks: ordered, named, inter-dependent HTTP requests defined in a plain-text DSL, with captures, assertions, durable run records, and artefact flow between steps.
httplay run deploy.htpl
httplay run deploy.htpl verify --with-deps
Existing tools each own one niche: Hurl is an assertion-first test tool with disposable responses; .http files are an IDE format for humans poking endpoints one request at a time; Bruno/Postman are GUI collection managers; HTTPie/xh are single-request CLIs.
Nobody owns the playbook case: a repeatable, replayable, partially re-runnable sequence of dependent requests with durable run records. HTTPlay fills that gap.
Each step has a directive zone (structured syntax, sigil-prefixed) and a request zone (literal bytes — headers and body are transmitted exactly as written, no comment stripping, no interpretation).
### Provision a tenant and grab an admin token.
# Owner: @maxja · run: httplay run deploy.htpl login
@name login
@retry 3
$token <- jsonpath $.token
! status == 200
POST https://api.example.com/login
Content-Type: application/json
{"user": "{{env.USER}}", "pass": "{{env.PASS}}"}
###
@name upload-users
@requires login
@save users-resp.json
! status == 201
POST https://api.example.com/users?token={{token}}
Authorization: Bearer {{token}}
@{{file:users.csv}}
###
@name verify
@requires login
! jsonpath $.count > 0
@on_failure warn
GET https://api.example.com/users/count?token={{token}}| Sigil | Category | Examples |
|---|---|---|
@ |
step meta | @name login, @save out.json, @retry 3, @requires login, @on_failure abort|continue|warn |
$ |
context mutation (captures) | $token <- jsonpath $.token, $sid <- xpath //SessionId/text(), $v <- regex 'v(\d+\.\d+)', $raw <- body |
> |
external pipe | > exec [protoc, --decode, mypkg.User, descriptors/user.proto] |
! |
assertions | ! status == 201, ! jsonpath $.count > 0, ! contains "OK" |
# |
human comment (directive zone only) | # TODO: rotate creds |
Rules:
@nameis required and must match[a-z0-9_-]+— names are CLI-addressable and referenceable.- Comments (
#) are legal only in the directive zone. Everything in the request zone is sent byte-for-byte (a#in a body is payload, not a comment). - No inline/trailing comments anywhere.
###(and####+) at line start = step separator.- Line endings are LF; a single trailing
\rper line is stripped as part of the line ending (CRLF-tolerant) — bodies included. > exectakes a JSON argv array — no shell, no string interpolation into commands. Captured values flow via explicitstdin:/stdoutcontract: stdin in, stdout captured, non-zero exit = step failure with stderr in the report.
{{token}} (capture), {{env.X}} (environment), {{login.response.body...}} (named response), @{{file:path}} (file as body — binary-safe). Rendering operates on bytes, never UTF-8 strings; captured values are byte slices decoded only at explicit text boundaries.
Bodies are raw bytes until a step declares (or auto-sniffs from Content-Type) a representation via @as auto|json|xml|text|binary:
| Representation | Captures | Content asserts |
|---|---|---|
json |
jsonpath, regex | jsonpath |
xml |
xpath, regex | xpath |
text |
regex, substr | contains, regex |
binary |
raw body only | size, sha256, bytes-contains |
status, header, cookie always work regardless of representation. Exotic formats (protobuf, msgpack, avro) are handled as binary + > exec pipes through their canonical CLI tools.
httplay run [-f] <playbook> [steps...] [-e env] [-o json|text] [--dry-run] [--with-deps] [--record RUN]
httplay list [-f] <playbook> [-o json] # steps + reference graph
httplay init [name] # scaffold playbook + env file
httplay fmt [-w] <playbook>... # normalize formatting
httplay env [-e env] # resolved variables (secrets redacted)
Execution model: linear order; @needs injects missing predecessors (cycle-checked at load). @on_failure: abort (default) / continue / warn. --record <run> seeds context from a previous run's report so step 5 can re-run without steps 1–4. Step selectors may be names, unique prefixes, or ranges (login..verify), akin to kubectl's resource positionals.
Every option exists in a long (--flag) and short (-f) form — the convention popularized by docker/kubectl. The short set is deliberately tiny and closed: -f (file), -e (environment), -o (output), -w (write, for fmt). No new short flags may be added retroactively without the long form leading in docs and deprecation notes. The playbook file may be given as a bare positional or via -f, mirroring kubectl apply -f manifest.yaml.
Every execution writes a run directory:
runs/2026-10-14T10-30-00/
report.json # per-step: request meta, timings, captures, assert results,
# content_type, size, sha256 (+base64/truncated preview)
users-resp.json # bodies saved via @save — raw bytes, never lossily decoded
Retention policy prunes to the last N runs. Captured values live in pipeline scope (in-memory); artefacts are opt-in and explicit; the report is the audit trail.
0— all steps passed1— step/assert failure2— parse/usage error
--output json emits the machine-readable run report on stdout.
- No embedded scripting language; no raw shell strings, ever (injection-safe by construction).
- Secrets come from env files / environment variables only; HTTPlay never stores or manages credentials;
httplay envredacts. --strict-toolspreflight-checks that every> execbinary exists before any request fires.
- Go. Stdlib
net/http,encoding/json,os/exec(argv slices). - Format is a real DSL: EBNF spec (below) is the contract; hand-written two-mode lexer (directive/raw) + recursive-descent parser; bodies are a single
RAWtoken the grammar never inspects. - Property under test: parse → print → re-parse is an identity function.
playbook := step ( sep step )* ;
sep := "###" [ "#" ] ;
step := { directive } request_line { header } [ body ] ;
directive := meta | capture | assert | exec | comment ;
meta := "@" name | "@" "needs" ident | "@" "save" path
| "@" "retry" int | "@" "as" repr | "@" "on_failure" policy ;
capture := "$" ident "<-" cap_source ;
cap_source := "jsonpath" jsonpath | "xpath" xpath | "regex" regex
| "header" hname | "status" | "body" | "stdout" ;
assert := "!" assert_expr ;
exec := ">" "exec" json_array [ "stdin:" template ] ;
comment := "#" any_text ;
request_line := method SP url ;
header := hname ":" hvalue ;
body := raw_bytes ; (* to next sep; grammar-invisible *)MIT — see LICENSE.