@eraserlabs/diagrams-cli

Introduction

@eraserlabs/diagrams-cli is the command-line interface for Eraser Diagrams. It renders diagram JSON to PNG or HTML and validates documents without a browser, using @eraserlabs/diagrams.

Usage

npm install -D @eraserlabs/diagrams-cli
npx eraser-diagrams render diagram.json -o diagram.png

Requires Node.js 22.23.4+, 24.22.1+, or 26.12.1+ and a Chromium-family browser on the machine (not bundled).

eraser-diagrams render <input...>     Render diagram JSON to PNG or HTML (needs Chromium)
eraser-diagrams validate <input...>   Validate diagram JSON without a browser
eraser-diagrams registry              Print the tag registry as JSON
eraser-diagrams schema <tag>          Print the JSON Schema of one tag
eraser-diagrams init                  Write eraser-diagrams.config.json in the current directory

<input> is a file path or - for stdin. Several inputs share one warm browser. Accepted documents are { "elements": [...] } or the split { "entities": [...], "connections": [...] }. A bare JSON array fails with E_ENVELOPE. A { "definition": { "elements": [...] } } wrapper is lifted with a note on stderr.

render options

For a PNG with a transparent background:

eraser-diagrams render diagram.json --transparent --scale 2 -o diagram.png

validate accepts --json, --fail-on-warning, --quiet, --debug.

Global options

Chromium

Precedence: --chromium-path > CHROMIUM_PATH > chromiumPath in the config file > auto-detect. Auto-detect probes the usual Chrome and Chromium install locations and reports which one it picked. eraser-diagrams init writes the detected path into a config file so it stays pinned.

Configuration file

eraser-diagrams.config.json is found by walking up from the current directory (stopping at the first directory that contains .git), or given with --config or ERASER_DIAGRAMS_CONFIG. Precedence is flag > environment > config file > default. Relative paths in the file resolve against the file's own directory. Unknown keys are rejected.

{
  "chromiumPath": "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
  "format": "png",
  "outDir": "./diagrams",
  "deviceScaleFactor": 2,
  "pages": 2,
  "icons": {
    "baseUrl": "https://storage.googleapis.com/eraser-public-assets/canvas-icons/",
    "cacheDir": "./.eraser/icons",
    "timeoutMs": 5000,
    "cacheTtlMs": 86400000,
    "onUnknown": "placeholder"
  },
  "fonts": "./fonts.json",
  "library": "./my-library.mjs",
  "overrides": "./my-overrides.mjs",
  "failOnWarning": false
}

Everything except --format and the output path is fixed when the browser boots, so it applies to the whole batch.

Output and exit codes

Status goes to stderr, one line per input, followed by its issues:

ok    diagram.json  → out/diagram.png  412 ms  1 warning
  warning W_UNKNOWN_ICON /elements/1/icon (Icon#api) — Unknown icon "nodejs"; using a placeholder glyph.
FAIL  other.json  E_UNKNOWN_TAG
  error   E_UNKNOWN_TAG /elements/0 (Shpe) — Unknown tag "Shpe". Did you mean "Shape"?

--json prints one report on stdout instead:

{
  "ok": false,
  "degradedFonts": [],
  "results": [
    {
      "input": "diagram.json",
      "out": "out/diagram.png",
      "ok": true,
      "errors": [],
      "warnings": [],
      "ms": 412
    },
    {
      "input": "other.json",
      "ok": false,
      "errors": [
        {
          "code": "E_UNKNOWN_TAG",
          "severity": "error",
          "path": "/elements/0",
          "message": "Unknown tag \"Shpe\".",
          "suggestion": "Shape"
        }
      ],
      "warnings": []
    }
  ]
}

Ctrl-C closes Chromium before exiting.