Command reference

Diagram export CLI reference

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: structure | 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, Browser visibility, 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.

Configuration files accept JSON comments and trailing commas without changing quoted values. A malformed or unreadable settings or project file reports its path and exits with code 2. A malformed diagram sidecar warns and uses the existing default layout fallback.

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

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.

Validation CLI reference

Headless SysML v2 / KerML validation. Runs the same parser, linker, and diagnostics as the SysML v2 VS Code extension Problems panel, in a terminal or a CI job. No VS Code, no browser, no display server.

npx sysml-validate models/

models/control.sysml
  2:5    error  SYN067  Import visibility is required by the Release syntax; use 'private import' unless re-export is intended.

models/vehicle.sysml
  12:23  error  RES001  Could not resolve reference to Element named 'Engien'.

✖ 2 problems (2 errors) in 2 of 2 files

…and when the model is healthy:

✓ 2 files checked, no problems found

Colour is used on a terminal and dropped everywhere else, a pipe, a log file, or a coding agent's chat window gets exactly the plain text above. --color and --no-color force it either way, and NO_COLOR is honoured.

Usage

sysml-validate [paths...] [options]

  --format <fmt>        text | compact | json | sarif | github (default: text).
                        text     grouped and aligned, colour on a terminal
                        compact  file:line:col: severity [CODE]: message
  --out <path>          Write the report to a file instead of stdout.
  --strict              Fail on warnings as well as errors.
  --max-warnings <n>    Fail when more than n warnings are reported.
  --all                 Report informational notices and hints too.
  --lint-profile <p>    Override sysml.lint.profile: default | quiet | strict.
  --workspace <path>    Index this project for cross-file reference resolution.
  --no-config           Ignore .vscode/settings.json and .vscode/sysml/project.json.
  --library <path>      Standard-library directory (default: the bundled library).
  --color, --no-color   Force ANSI colour on or off (default: on a terminal only).

Paths may be files or directories; directories are searched recursively for .sysml and .kerml, skipping node_modules, VCS directories, build output, and vendored library trees. With no path, the working directory is checked. By default, no model file outside the paths you name is discovered or indexed. Use --workspace <path> only when references should resolve against other project files.

The OMG standard library ships with the package, so Real, ISQ::*, SI::* and the rest resolve with nothing else installed.

Examples

Check one file while you work. Paths, positions, severity, and the diagnostic code, everything needed to jump to the problem:

$ sysml-validate models/vehicle.sysml
models/vehicle.sysml
  12:23  error  RES001  Could not resolve reference to Element named 'Engien'.

✖ 1 problem (1 error) in 1 of 1 file

See the advisory notices too. Hints and info are out of the way by default, --all brings them in:

$ sysml-validate models/ --all
models/vehicle.sysml
  5:19   hint  RES016  'power' shadows a standard-library element of the same name; the library symbol is hidden in this scope.
  16:21  hint  SEM006  Requirement definition 'MassLimit' has no 'subject' declaration.

▲ 2 problems (2 hints) in 1 of 2 files

One line per problem for grep, an editor error matcher, or a coding agent that wants to parse the output:

$ sysml-validate models/ --format compact
models/control.sysml:2:5: error [SYN067]: Import visibility is required by the Release syntax; use 'private import' unless re-export is intended.
models/vehicle.sysml:12:23: error [RES001]: Could not resolve reference to Element named 'Engien'.

Compact prints nothing at all on a clean run, so [ -s report.txt ] and if sysml-validate . --format compact | grep . both behave.

Structured output for a script or a dashboard:

$ sysml-validate models/ --format json | jq '.counts.diagnostics[0].code'
{
  "error": 2,
  "warning": 0,
  "info": 0,
  "hint": 0
}
"SYN067"

Gate a commit hook on errors, and allow a small warning budget:

$ sysml-validate models/ --max-warnings 5 && echo "model is publishable"

Check just what changed, without loading any model outside that list:

$ git diff --name-only --diff-filter=d origin/main | grep -E '\.(sysml|kerml)$' | xargs -r sysml-validate

If those files need definitions elsewhere in the checkout, opt into workspace indexing explicitly:

$ git diff --name-only --diff-filter=d origin/main | grep -E '\.(sysml|kerml)$' | xargs -r sysml-validate --workspace .

--workspace . indexes the rest of the project for reference resolution, but still reports diagnostics only for the files you named.

Use it from a coding agent. The default output is plain text with a stable one-line summary, so an agent can act on it directly:

$ sysml-validate models/ --format compact ; echo "exit=$?"
models/vehicle.sysml:12:23: error [RES001]: Could not resolve reference to Element named 'Engien'.
exit=1

Your project's configuration is honoured

The validator reads the settings your team commits, in the editor's own precedence, .vscode/settings.json first, then .vscode/sysml/project.json:

--lint-profile overrides the profile for one run, and --no-config ignores both files. Note that sysml.validation.severities covers the validator's own codes; unresolved-reference errors (RES001) come from the linker and are always errors.

Exit codes

Informational notices and hints never fail a run; they are only printed with --all.

GitHub Actions

Fail the build on model errors, with inline annotations on the diff:

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

- name: Validate the SysML model
  run: npx sysml-validate models/ --format github --strict

Or upload SARIF so diagnostics land in Security → Code scanning and on the pull request:

- name: Validate the SysML model
  run: npx sysml-validate models/ --format sarif --out sysml.sarif
  continue-on-error: true

- uses: github/codeql-action/upload-sarif@v3
  with:
    sarif_file: sysml.sarif