The CLI

#Run it

With Node 22.12 or later, nothing to install first:

The commands below call it stackmap; with npx it is npx @omsimos/stackmap@0.4.0.

#validate

$ stackmap validate <diagram.json> [--json]

Checks the diagram and lists every problem with a code, where it is and the fixes it allows, including card text that won’t fit. It exits 1 when the diagram has errors; warnings alone exit 0.

$ stackmap validate .stackmap/commerce-api/diagram.jsonerror  refs/unknown-node  /edges/6/to  Unknown node "orders-db"  fix: use "orders"  fix: add node "orders-db" or remove the edge✗ 1 error

--json

The same diagnostics, for a program to read: each one has its code, severity, subject (a JSON pointer), message, evidence and allowed fixes.

1{2  "ok": false,3  "diagnostics": [4    {5      "code": "refs/unknown-node",6      "severity": "error",7      "subject": "/edges/0/to",8      "message": "Unknown node \"orders-db\"",9      "evidence": {10        "id": "orders-db",11        "closest": []12      },13      "allowedFixes": [14        "add node \"orders-db\" or remove the edge"15      ]16    },17    {18      "code": "semantics/orphan-node",19      "severity": "warning",20      "subject": "/nodes/1",21      "message": "Node \"db\" has no connections",22      "evidence": {23        "id": "db"24      },25      "allowedFixes": [26        "add an edge to or from \"db\"",27        "remove the node"28      ]29    }30  ]31}

#deliver

$ stackmap deliver <diagram.json> [-o out.html] [--open]

Validates, lays out and writes one offline HTML file, next to the input unless you pass -o. It refuses to overwrite its input. Delivery is deterministic: the same JSON always gives the same file, byte for byte, so the receipt’s hash is worth keeping. With --open it then opens the file in your default browser; the skill passes it, so a diagram opens as soon as the agent delivers it.

$ stackmap deliver .stackmap/commerce-api/diagram.jsondelivered .stackmap/commerce-api/diagram.html · sha256 0a6f2ce5f590380e62bfcc0b9ae1537dc7140ea14b83b5ca3556009aee7c11e1 · 500770 bytes

The receipt is the only thing on stdout. Warnings go to stderr; with errors, nothing is written and the command exits 1.

#serve

$ stackmap serve <diagram.json> [--port 4400]

A live viewer that reloads whenever the file changes, for editing a diagram by hand or watching an agent work. It binds 127.0.0.1 only and takes the next free port when 4400 is taken. When a save is invalid it keeps the last good version on screen, and it keeps your camera and selection across reloads.

$ stackmap serve diagram.jsonserving http://127.0.0.1:4400 · watching diagram.json · Ctrl-C to stop✓ diagram.json ready✗ diagram.json: 1 error; keeping the last good version✓ diagram.json reloaded

#Options

#Diagnostics

Every diagnostic has the same shape, so an agent can act on it without guessing:

$ stackmap validate diagram.jsonerror  schema/invalid_value  /nodes/1/type  Invalid option: expected one of "client"|"service"|"gateway"|"database"|"cache"|"queue"|"storage"|"external"|"security"|"start"|"active"|"waiting"|"decision"|"success"|"failure"|"neutral"  fix: use one of: client, service, gateway, database, cache, queue, storage, external, security, start, active, waiting, decision, success, failure, neutral✗ 1 error

$ stackmap validate diagram.jsonerror  refs/unknown-node  /edges/6/to  Unknown node "orders-db"  fix: use "orders"  fix: add node "orders-db" or remove the edge✗ 1 error

$ stackmap validate diagram.jsonwarning  semantics/orphan-node  /nodes/11  Node "audit" has no connections  fix: add an edge to or from "audit"  fix: remove the node✓ valid with 1 warning

$ stackmap validate diagram.jsonerror  card-fit/overflow  /nodes/0/card/subtitle  "REST API for the storefront, admin and partner apps" is 297px wide; this slot fits 200px (~35 characters)  fix: shorten to at most 35 characters  fix: move the detail into a card row✗ 1 error

#Diagnostic codes

Every code validate can report. Schema codes are named after the check that failed.

#Exit codes