Docs / Agents and API
Command line
Check, render and verify diagrams on your own machine, with no account and no network.
The volley command line tool runs Volley's parser and renderer on your own machine. It needs no account and no network, and it is not metered.
Install
The tool lives in the Volley repository and runs on Node 24 or later, with no build step:
node bin/volley.ts check flow.volleyFrom the repository you can also run it with npm run volley -- <command>, link it as a volley command with npm link, or run it in Docker with docker compose run --rm cli <command> <file>. It is not published to npm.
Every command reads a file, or standard input when the file is -:
cat flow.volley | node bin/volley.ts check -PNG images exported from Volley work as input too, because they carry their source.
Commands
| Command | Does |
|---|---|
check <file> | Lists problems as file:line:column: severity: message, or says ok with the number of lanes |
describe <file> | Prints the diagram as Markdown, payloads included |
json <file> | Prints the parsed diagram as JSON |
svg <file> | Prints an SVG image |
url <file> | Prints a share link that carries the diagram |
har <file> | Converts a HAR recording into Volley source |
verify <diagram> <har> | Checks a diagram against a recording |
help | Prints usage |
check
node bin/volley.ts check flow.volleyExits with 1 when there is an error. Warnings do not fail the check, so it is safe to use in CI and in pre-commit hooks.
describe and json
Both print their output even when the diagram has errors, and exit with 1 if it does.
svg
node bin/volley.ts svg flow.volley --theme dark --payloads > flow.svg| Option | Effect |
|---|---|
--theme light or --theme dark | The appearance. Light is the default. |
--payloads | Draw payloads under their messages |
--no-badge | Leave out the "Made with Volley" badge |
url
node bin/volley.ts url flow.volleyPrints a share link like https://volley.sh/#src=.... Use --base <url> to point it at another Volley address.
har
node bin/volley.ts har checkout.har --host api.example.com --title "Checkout" > checkout.volleyConverts a recording the same way the editor's HAR import does, with the same redaction, and with no limit on the number of requests.
| Option | Effect |
|---|---|
--host <text> | Keep only requests whose host contains the text |
--title <text> | The diagram's title |
--headers | Include the request line and useful headers in payloads |
--all | Keep static assets such as images and scripts |
Exits with 1 when no requests match.
verify
node bin/volley.ts verify checkout.volley checkout.harRuns a drift check and prints a report with one line per checked step.
| Option | Effect |
|---|---|
--strict | Also fail when the recording has requests the diagram does not mention |
--json | Print the full report as JSON, as the HTTP API returns it |
--host <text> | Check only requests to hosts containing the text |
--all | Include static assets |
| Exit code | Meaning |
|---|---|
| 0 | The diagram matches the recording |
| 1 | The diagram has drifted, or with --strict, the recording has undocumented requests |
| 2 | The check could not run: a missing argument, an unreadable file, or errors in the diagram |