sysml-diagram

Headless SysML v2 / KerML diagram export. Renders the same views the SysML v2 VS Code extension draws — General, Interconnection, Action Flow, State Transition, Sequence, Case, Geometry, and the Grid table — from a terminal or a CI job. No VS Code, no browser, no display server.

npx sysml-diagram export --file models/vehicle.sysml --view gv --out docs/vehicle-gv.svg

docs/vehicle-gv.svg

Written files go to stdout, one per line; model errors and warnings go to stderr and set the exit code. Nothing else is printed, so the output pipes cleanly into another command.

Usage

sysml-diagram export --file <model.sysml> [options]

  --file <path>       Model file to render (required).
  --view <kind>       gv | iv | afv | stv | sv | cv | gev | grv (default: project's).
  --anchor <qname>    Qualified name to anchor on (default: the file overview).
  --out <path>        Output path (default: <file-stem>.<view>.svg).
  --all               Render every view that has content for the anchor.
  --out-dir <path>    Output directory for --all (default: the working directory).
  --theme <name>      dark | light (default: dark).
  --gv-mode <mode>    General View presentation: group | tree (default: as saved).
  --workspace <path>  Project root holding .vscode/sysml/ (default: auto-detected).
  --auto-layout       Ignore the committed diagram layout and lay out fresh.
  --strict            Fail on warnings as well as errors.
  --library <path>    Standard-library directory (default: the bundled library).

The OMG standard library ships with the package, so nothing else needs to be installed or configured.

Examples

Render one view. The path of every file written is printed, relative to the working directory:

$ sysml-diagram export --file models/vehicle.sysml --view iv --anchor Vehicle::Car --out docs/car-iv.svg
docs/car-iv.svg

Render every view that has content, in one pass over the model:

$ sysml-diagram export --file models/vehicle.sysml --all --out-dir docs
docs/vehicle.gv.svg
docs/vehicle.iv.svg
docs/vehicle.sv.svg
docs/vehicle.grv.csv

The Grid View is a table in the editor too, so it lands as CSV. Views with no content for the anchor are skipped rather than written empty.

A model with problems still renders — you get the artifact and the failure, which is what you want when a pipeline goes red:

$ sysml-diagram export --file models/vehicle.sysml --view gv --out docs/gv.svg ; echo "exit=$?"
models/vehicle.sysml:12:23: error [RES001]: Could not resolve reference to Element named 'Engien'.
docs/gv.svg
sysml-diagram: 1 error in models/vehicle.sysml.
exit=1

Diagnostics are one line each, file:line:col: severity [CODE]: message, on stderr — so sysml-diagram … 2>/dev/null leaves only the written paths. Only errors and warnings are shown; for the advisory notices use sysml-validate --all.

Feed the written paths to another tool, since stdout is just the file list:

$ sysml-diagram export --file models/vehicle.sysml --all --out-dir docs | xargs -r ls -lh

Documentation build: light theme, the General View's relation tree, into the docs folder:

$ sysml-diagram export --file models/vehicle.sysml --view gv --gv-mode tree --theme light --out docs/architecture.svg
docs/architecture.svg

Snapshot every package of a multi-file project:

$ for model in models/*.sysml; do sysml-diagram export --file "$model" --all --out-dir docs/diagrams; done

Your project's configuration is honoured

The CLI reads the same two files the editor writes, so a rendered diagram is the diagram your team arranged — not a fresh automatic layout of the same model:

• .vscode/sysml/project.json — project-scoped sysml.preview.diagrams.* settings: default view, port labels, multiplicities, connector line style, connect-point spacing, Case View subject boundary.
• .vscode/sysml/diagrams/<source>.json — the per-anchor, per-view side-car: node positions and sizes, port placements, connector waypoints and docking anchors, layout direction, General View mode and quick filters, Interconnection View compartment collapse, Grid preset and column order.

Precedence is the editor's, with the command line on top: manifest default → project.json → saved per-view state → CLI flag.

The project root is the nearest ancestor holding .vscode/sysml/ (else the repository root); --workspace names it explicitly, and --auto-layout ignores the committed geometry.

Output is a self-contained vector SVG: its own stylesheet, its own marker definitions, embedded theme colours, no external references, and well-formed XML. The Grid View is a table in the editor as well, so --view grv writes CSV.

Exit codes

| Code | Meaning | |---|---| | 0 | every requested diagram was written and the model has no blocking diagnostics | | 1 | the model reported errors (or warnings under --strict), or nothing could be rendered | | 2 | the command line or the environment was wrong (bad flag, unreadable file) |

Diagnostics go to stderr in file:line:col: severity [CODE]: message form; written paths go to stdout.

GitHub Actions

Render diagrams into build artifacts, or fail the build when the model breaks:

- uses: actions/setup-node@v4
  with: { node-version: 20 }

- name: Render diagrams
  run: npx sysml-diagram export --file model.sysml --all --out-dir docs/diagrams

- name: Fail if the committed diagrams are stale
  run: git diff --exit-code docs/diagrams

- uses: actions/upload-artifact@v4
  with:
    name: diagrams
    path: docs/diagrams

sysml-diagram writes the diagram even when the model has errors, and still exits 1 — so the artifact is there to look at when the gate fails.

License

The CLI uses the extension's Freeware License (see LICENSE). The vendored OMG standard library under resources/sysml.library keeps its upstream OMG LICENSE / LICENSE-GPL terms; see that directory's NOTICE.md.