Arazzo · CLI · Go · Apache-2.0

arazzo-maestro

Lint, render & test Arazzo workflows. One Go binary. Eco-designed, accessible by default.

arazzo-maestro turns Arazzo workflow specs into three things the rest of your team can actually use: validation that fails your CI when something is wrong, standalone HTML pages anyone can open in a browser, and runnable end-to-end and load tests you point at any environment, no server, no build, no JavaScript.

View on GitHub Quick start

$ arazzo-maestro lint workflow.yaml
OK: workflow.yaml, no issues found

$ arazzo-maestro lint broken.yaml
[error] arazzo: value does not match pattern '^1\.[01]\.\d+'
[error] workflows[checkout].steps[create-order].operationId:
        operation "createOrder" not found in source "shop-api"
Error: 2 issue(s) found

$ arazzo-maestro view workflow.yaml -o dist/
# dist/happy-path-checkout.html  (~4.5 kB gzipped)

$ arazzo-maestro view workflow.yaml --format mermaid -o dist/
# dist/happy-path-checkout.mmd  (paste into any .md, GitHub renders it)

$ arazzo-maestro test run e2e workflow.yaml --base-url https://staging.example.com
Success: 6 requests, all assertions passed
# add --report-html dist/report for an HTML report

$ arazzo-maestro test gen perf workflow.yaml -o dist/
# dist/perf/k6/happy-path-checkout.k6.js

Three subcommands

One score, three batons

The maestro inspects the score, conducts it, and rehearses it: lint validates, view renders, test generates runnable tests. No other moving parts.

lint

Validate, then fail CI on demand

Three passes: the official OAI JSON Schema, internal semantic rules (unique IDs, $steps.x.outputs.y references), and a cross-file check that every step operationId actually exists in the referenced OpenAPI contract. Exit 0/1 plus parseable findings, offline, deterministic.

view

Render to standalone HTML

One self-contained page per workflow: START → steps → END, runtime expressions highlighted, success criteria, request bodies. ~4.5 kB gzipped, opens offline in any browser. Portrait or --layout landscape; or --format mermaid for a flowchart GitHub renders natively. Commit it, or ship it to GitHub Pages.

test

Generate runnable tests from a workflow

test gen e2e turns a workflow into Hurl files: each step becomes a request, outputs become captures, success criteria become asserts, the host stays a {{baseUrl}} variable. test run e2e runs them against any environment with an optional HTML report. test gen perf does the same for load testing, emitting a k6 script.

workflow.yamlArazzo

openapi.yamlcontract

arazzo-maestrosingle binary

arazzo-maestro

lintexit 0/1 + findings

viewdist/*.html

test*.hurl · *.k6.js

What view produces

The Blueprint render

Not a mockup: the panels below are the actual HTML view emits, embedded verbatim and regenerated from the tool, so they never drift. Grid paper, hairline frames, a vertical rail wiring steps, monospace headers, one warm amber accent for runtime expressions. Light and dark, both WCAG AA audited. And view is not HTML-only: the same command exports a Mermaid flowchart, shown at the bottom next to its source.

Theme: light, live `view` output

Theme: dark, live `view` output

Layout: landscape (--layout landscape), scrolls sideways, live `view` output

Or view --format mermaid: the same workflow as a flowchart GitHub renders natively, zero image (here the retry path, live `view` output beside its render)


flowchart TD
  wfStart([Start])
  s0["01 add-to-cart<br/>addToCart"]
  s1["02 pay-refused<br/>processPayment"]
  wfEnd([End])
  wfStart --> s0
  s0 --> s1
  s1 --> wfEnd
  s1 -. "retry x2 after 2s" .-> s1
  s1 -. "on failure" .-> wfEnd

Built for after authoring

Editor plugins help you write Arazzo. We handle everything after.

Validation in CI, an artifact you can commit and deploy, zero runtime dependency. Complementary to your IDE plugin, the same person can run both.

Three-pass linter

Official JSON Schema, semantic rules, and cross-file operationId resolution against your OpenAPI contracts.

Standalone HTML

No server, no client-side rendering, no JavaScript. One file, ~29 kB raw / ~4.5 kB gzipped, viewable offline.

Test generation

Turn a workflow into runnable tests. test gen/run e2e emits Hurl files ({{baseUrl}}, captures, asserts) and runs them with an HTML report; test gen perf emits a k6 load-test script (VUs, duration, thresholds).

Eco-designed by rule

System fonts only, inline SVG, minimal requests, a single static binary on a FROM scratch image. Sobriety is enforced, not aspirational.

Accessible by default

WCAG 2.2 AA contrasts, semantic HTML, visible focus, no info by colour alone, prefers-reduced-motion honoured.

Themeable

Three themes built in (light, dark, pb33f); drop a themes.yml to set a default or add your own. Custom themes are contrast-audited at load time.

One binary, no runtime

No Python, no Node, no cgo. Trivial cross-compilation, instant startup, a tiny Docker image. Install in one command.

Practice what we render

This page eats its own dog food

It is built with the very rules the tool enforces. View source, there is nothing to hide, and nothing phoning home.

0 network requests
0 bytes of JavaScript
System fonts only
Inline SVG, no raster images
WCAG 2.2 AA contrast
Light & dark via your OS preference
Single self-contained file

arazzo-maestro at a glance
Generated workflow HTML	~29 kB raw · ~4.5 kB gzipped
Requests at page load	1 (output) · 0 (this page)
Direct Go dependencies	4
Binary size	~20 MB, static, no cgo
Built-in themes passing WCAG AA	11 / 11 critical pairs
Arazzo versions	1.0 · 1.1 (partial)

Get going

Quick start

Go 1.25+ for a source install, or run it straight from Docker, nothing else to set up.

# Install (Go 1.25+)
$ go install github.com/emmanuelperu/arazzo-maestro/cmd/arazzo-maestro@latest

# Validate
$ arazzo-maestro lint workflow.yaml

# Render (light + dark)
$ arazzo-maestro view workflow.yaml -o dist/light
$ arazzo-maestro view workflow.yaml -o dist/dark --theme dark
$ open dist/light/index.html

# Generate + run e2e tests (Hurl)
$ arazzo-maestro test run e2e workflow.yaml --base-url https://staging.example.com

# Generate perf tests (k6)
$ arazzo-maestro test gen perf workflow.yaml --vus 10 --duration 30s

# Or via Docker, FROM scratch image
$ docker run --rm -v "$PWD":/work \
    ghcr.io/emmanuelperu/arazzo-maestro:latest \
    view /work/workflow.yaml -o /work/dist

# List available themes
$ arazzo-maestro view --list-themes
dark
light (default)
pb33f