## Diagram export CLI reference Headless SysML v2 / KerML diagram export. Renders the same views the [SysML v2 VS Code extension](https://marketplace.visualstudio.com/items?itemName=voidaliot.vscode-sysml-v2) 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. ```bash 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 [options] --file Model file to render (required). --view gv | iv | afv | stv | sv | cv | gev | grv (default: project's). --anchor Qualified name to anchor on (default: the file overview). --out Output path (default: ..svg). --all Render every view that has content for the anchor. --out-dir Output directory for --all (default: the working directory). --theme dark | light (default: dark). --gv-mode General View presentation: structure | tree (default: as saved). --workspace 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 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: ```console $ 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: ```console $ 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: ```console $ 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`](https://www.npmjs.com/package/sysml-validate). **Feed the written paths to another tool**, since stdout is just the file list: ```console $ 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: ```console $ 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: ```console $ 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/.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 | 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: ```yaml - 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](https://marketplace.visualstudio.com/items?itemName=voidaliot.vscode-sysml-v2) Problems panel, in a terminal or a CI job. No VS Code, no browser, no display server. ```bash 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 text | compact | json | sarif | github (default: text). text grouped and aligned, colour on a terminal compact file:line:col: severity [CODE]: message --out Write the report to a file instead of stdout. --strict Fail on warnings as well as errors. --max-warnings Fail when more than n warnings are reported. --all Report informational notices and hints too. --lint-profile

Override sysml.lint.profile: default | quiet | strict. --workspace Index this project for cross-file reference resolution. --no-config Ignore .vscode/settings.json and .vscode/sysml/project.json. --library 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 ` 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: ```console $ 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: ```console $ 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: ```console $ 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: ```console $ 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: ```console $ sysml-validate models/ --max-warnings 5 && echo "model is publishable" ``` **Check just what changed**, without loading any model outside that list: ```console $ 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: ```console $ 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: ```console $ 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`: | Setting | Effect | |---|---| | `sysml.lint.profile` | `default` / `quiet` / `strict` style-notice volume | | `sysml.validation.severities` | Per-code severity overrides (e.g. `{ "SEM006": "warning" }`) | | `sysml.diagnostics.unusedImports` | `off` / `warning` / `error` | | `sysml.diagnostics.units` | UNIT001 to UNIT005 dimensional analysis on/off | `--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 | Code | Meaning | |---|---| | `0` | no blocking diagnostics | | `1` | errors, or warnings under `--strict` / `--max-warnings` | | `2` | the command line or the environment was wrong (bad flag, unreadable path) | 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: ```yaml - 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: ```yaml - 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 ```