SysML v2
The holarch Command Line Tool
Check, format and export SysML v2 models in builds and CI with the holarch command line tool and the Holarch Language Engine; GitHub Actions and other CI systems, JSON and SARIF reports, exit codes, sign-in with an API token or a license file.
On this page
Overview
holarch is a command line tool that checks SysML v2 text files with the Holarch Language Engine, the same engine the Holarch editor uses. Run it on your own computer or in a build: it reads every .sysml file in a folder, reports problems with file, line and column, and exits with a non-zero code when the model has errors, so a pull request with a broken model fails its checks.
The tool does three things:
- Check: syntax, names, types, specializations, multiplicities, units and the other rules of the engine, across all files of the model. Reports as text, JSON, SARIF (for code scanning) or GitHub annotations.
- Format: rewrites files in one canonical layout (four-space indentation, one element per line, canonical spacing), keeping every comment.
- Export: writes the model as SysML v2 JSON, the interchange format of the Systems Modeling API.
The tool comes with the Individual and Team plans (including the trial), a Holarch Language Engine license and a self-hosted edition license. It does not need a Holarch project: it works on the files in your repository.
Concepts
- Model: all
.sysmlfiles under the folders you name (default: the current folder), read as one model. A name declared in one file resolves in the others, as packages do in a Holarch project. Folders whose names start with a dot (such as.git) are skipped. - KerML files:
.kermlfiles are checked as KerML by engine versions that read KerML. Older engine versions list them as skipped, which is not an error. - Diagnostics: each problem has a code (for example
name.unresolved), a severity (error, warning or note), a position and a message in the same words as the Holarch editor. Only errors fail a check, unless you add--warnings-as-errors. - Sign-in: the tool checks once a day that your API token belongs to an Individual or Team plan, or reads a license file without any network access. See Sign-in for the tool.
- The engine: the tool contains the compiled Holarch Language Engine and the SysML v2 standard library.
holarch versionprints their versions and the engine's copyright notice.
How to use it
When and why
Use the tool where SysML v2 text lives in a source repository: designers edit .sysml files in their editor of choice, and every change is checked before it is merged. It answers "does this model still hold together?" on every commit, the way a compiler does for code. Use the Holarch editor for modeling, diagrams and reviews; use the tool to guard the files between edits. To move a model between the repository and a Holarch project, use Import and Export.
Install
- Install Python 3.9 or later.
- Install the tool for your system (Linux x86-64, Linux arm64 or macOS on Apple silicon) with pip:
python3 -m pip install holarch-cli
- Check the installation:
holarch versionprints the tool, engine and library versions.
Sign in with an API token
- In Holarch, open Account Settings → API tokens and create a token. Read only access is enough.
- Put the token in the
HOLARCH_API_KEYenvironment variable (in CI: a secret). - Run
holarch whoami. It prints your plan and account, for example"plan": "team".
Check a model
holarch check models/
Each problem is one line, then a summary:
models/requirements.sysml:14:27: error name.unresolved: “MassValu” is not defined here. Check the spelling, or import its package.
6 files checked: 1 error, 0 warnings.
The exit code is 1 when the model has errors and 0 otherwise. Add --warnings-as-errors to fail on warnings too.
Format files
- Run
holarch format models/. Each changed file is listed as "reformatted <file>". - To check the layout in CI without changing files, run
holarch format --check models/. It lists "would reformat <file>" and exits with 1 when a file would change. - To see the changes first, run
holarch format --diff models/.
A file with syntax errors is not formatted ("not formatted: the file has syntax errors."). Comments stay where they were: notes before an element stay above it, a note at the end of a line stays at the end of that line.
Export the model as SysML v2 JSON
holarch export models/ -o model.json
The file holds the standard element array of the Systems Modeling API. The same files always give the same JSON, so the export can be committed and compared. A model with errors is not exported ("The model has errors, so it was not exported."); add --force to export it anyway. Add --holarch-fields to keep what only Holarch reads (element order, spelling), for an exact import into a Holarch project.
Run it in GitHub Actions
- Add the API token as a repository secret named
HOLARCH_API_KEY(Settings → Secrets and variables → Actions). - Add a workflow file, for example
.github/workflows/sysml.yml:
name: SysML model
on: [push, pull_request]
jobs:
check:
runs-on: ubuntu-latest
permissions:
contents: read
security-events: write
steps:
- uses: actions/checkout@v4
- uses: actions/setup-python@v5
with:
python-version: "3.12"
- run: python -m pip install holarch-cli
- run: holarch check models --format github --sarif holarch.sarif
env:
HOLARCH_API_KEY: ${{ secrets.HOLARCH_API_KEY }}
- run: holarch format --check models
- uses: github/codeql-action/upload-sarif@v3
if: always()
with:
sarif_file: holarch.sarif
- Push. Problems appear as annotations on the changed lines of the pull request, and the job fails when the model has errors or a file is not in the canonical layout. Leave out the
holarch format --checkstep to check the model only.
The last step uploads the SARIF report to code scanning, where problems are listed under Security → Code scanning. Leave it out if your repository does not use code scanning: the annotations work without it.
Run it in other CI systems
Any CI system with Python 3.9 or later runs the same commands. Install the tool, set the token from a secret, check:
python3 -m pip install holarch-cli
holarch check models/ --sarif holarch.sarif --json holarch.json
For example, GitLab CI (.gitlab-ci.yml, with HOLARCH_API_KEY as a masked CI/CD variable):
sysml:
image: python:3.12
script:
- pip install holarch-cli
- holarch check models/ --sarif gl-holarch.sarif
- holarch format --check models/
artifacts:
when: always
paths: [gl-holarch.sarif]
Jenkins, Azure Pipelines, CircleCI and others work the same way: one step installs the tool, the next runs holarch check; a non-zero exit code fails the build. Keep the JSON report (--json) as a build artifact when you want the numbers in a dashboard.
Worked example: the Hybrid Car demo
- Create the demo: on Manage Projects, click Project Files ▾ → New Demo Project → Hybrid Car (SysML v2).
- Open Model → Import and Export. Under Export, choose The whole model and SysML v2 text, click Export, and unzip the download into a folder
modelsof your repository. - Run
holarch check models. The result is "6 files checked: 0 errors, 0 warnings." - In
requirements.sysml, changeattribute maxCurbMass : MassValuetoMassValuand run the check again. It reportsrequirements.sysml:14:27: error name.unresolved: “MassValu” is not defined here.and exits with 1. - Undo the change. Run
holarch format modelsonce and commit the files, so laterformat --checkruns pass. - Add the GitHub workflow above. Every later pull request that breaks the model fails its check.
Tips and good practice
- Keep each file's content in a package. Elements outside any package work, but a package per file keeps names unique across files.
- Use a read-only token for CI, limited to no projects: the tool needs no project access.
- Format once and commit the result before you turn on
format-check, or the first run fails on every file. - Pin the tool's version in CI (
holarch-cli==<version>) so a new engine release does not change results in the middle of a review. - Runners without internet access use a license file instead of a token.
Common mistakes
- "No .sysml or .kerml files found": the path is wrong, or the files are in a folder whose name starts with a dot.
- Names unresolved in one file only: the file declares names that another file uses, and that other file has a syntax error. Fix the syntax error first; the report says which files were left out.
- The job fails with exit code 3: the token is missing, wrong, or belongs to an account on the Free plan. The message says which.
How it connects to other features
- The checks are those of the Holarch editor's SysML v2 text and of Model Checks for SysML v2 projects, with the same messages (The SysML v2 Text Editor).
- Files exported from a project (Import and Export) check cleanly; the JSON the tool exports imports into a project.
- For changes that should go through review in Holarch rather than through files, use the API or the Python client, whose changes arrive as proposals.
Commands
| Command | What it does |
|---|---|
holarch check [paths] | Checks the model; reports problems; exit 1 on errors |
holarch format [paths] | Rewrites files in the canonical layout |
holarch export [paths] | Writes the model as SysML v2 JSON |
holarch whoami | Shows what the token or license file allows |
holarch version | Prints the tool, engine and library versions and the engine's copyright notice (no sign-in needed) |
Paths are files or folders; the default is the current folder. Folders are searched with their subfolders.
Options of check
| Option | Meaning |
|---|---|
--format human|json|sarif|github | The report on standard output (default human) |
--output FILE | Write that report to a file instead |
--sarif FILE | Also write a SARIF 2.1.0 report |
--json FILE | Also write a JSON report |
--warnings-as-errors | Exit 1 on warnings too |
Options of format
| Option | Meaning |
|---|---|
--check | Change nothing; exit 1 when a file would change |
--diff | Change nothing; print the changes as a unified diff |
--stdout | Print the formatted text of one file instead of writing it |
Options of export
| Option | Meaning |
|---|---|
-o FILE, --output FILE | Write to a file (default: standard output) |
--holarch-fields | Add the fields only Holarch reads, for an exact round trip |
--force | Export a model with errors (never one with syntax errors) |
Options of every command that signs in
| Option | Environment variable | Meaning |
|---|---|---|
--api-key KEY | HOLARCH_API_KEY | An API token (hol_…); prefer the variable, so the token stays out of logs |
--license FILE | HOLARCH_LICENSE_FILE | A license file for offline use |
--server URL | HOLARCH_SERVER | The Holarch server that checks the token (an https address) |
--timeout SECONDS | Time limit for each engine step (default 60) |
Sign-in for the tool
The tool runs when one of these is present:
- An API token of an Individual or Team plan, including the Individual trial. The tool asks the server once and keeps the answer for a day in a cache file (
~/.cache/holarch/entitlement.json;HOLARCH_CACHE_DIRmoves it). The cache holds the plan and the account email, never the token. When the server cannot be reached, an answer up to 7 days old still counts, with a note. - A license file, for Holarch Language Engine licensees, self-hosted edition customers and runners without internet access. The tool checks the file's signature itself and never connects to a server. Every valid license includes the tool at no extra charge:
- Holarch Language Engine license: save the license key from your engine delivery (the text that starts with
l1.) in a file, for exampleholarch-engine.key, and point--licenseorHOLARCH_LICENSE_FILEat it. Line breaks that an email added do not matter. The key's licensed web addresses and server use apply to the engine in your product, not to the tool. In the 14 days after the key's end date the tool keeps working and prints a reminder. - Self-hosted edition license: use the license file of your Holarch server as it is. In its last 30 days the tool prints a reminder. In the 30 days after the end date (the license's grace period) the tool keeps working and prints the days left; after that it stops until a renewed license is installed.
- Holarch Language Engine license: save the license key from your engine delivery (the text that starts with
An engine key past its 14 days, too, stops the tool until a renewed key is installed.
A token of an account on the Free plan is refused, also when the account keeps the API through an academic email address. The Individual trial includes the tool.
License files in CI
Store the license as a secret, never in the repository. In CI, write the secret to a file outside the checkout (in GitHub Actions, under $RUNNER_TEMP) and set HOLARCH_LICENSE_FILE to its path.
Reports
JSON output
--format json and --json FILE write:
| Field | Meaning |
|---|---|
tool, version, engine | holarch, the tool's version, the engine's version |
files | The files checked, as paths relative to the folder the tool ran in |
summary | errors, warnings, notes, files |
diagnostics | file, line, column, endLine, endColumn (1-based), severity (error, warning, info), code, message, args |
skipped | Files not checked, with the reason (KerML files with an older engine) |
excluded | Files with syntax errors, left out of the checks across files |
Columns count Unicode characters (code points).
SARIF
--format sarif and --sarif FILE write SARIF 2.1.0 with one rule per diagnostic code, the severity as error, warning or note, and paths relative to the folder the tool ran in. Run the tool at the repository root so code scanning finds the files.
GitHub annotations
--format github prints one workflow command per problem (::error file=…,line=…,col=…::message), which GitHub Actions shows as annotations, then the summary line.
Exit codes
| Code | Meaning |
|---|---|
| 0 | No errors (format: nothing left to change) |
| 1 | The model has errors; format --check or --diff: a file would change, or a file could not be formatted; export: refused because of errors |
| 2 | Wrong usage: an unknown option, a path that does not exist, no model files |
| 3 | Not signed in or not entitled: no token or license file, a refused token, a Free plan, a license file that is invalid, changed or expired |
| 4 | The engine cannot run, or refused the model as too large or too slow to check |
Messages
| Message | Meaning |
|---|---|
| "The holarch command line tool needs a Holarch API token of an Individual or Team plan (HOLARCH_API_KEY, or --api-key) or a Holarch Language Engine license file (HOLARCH_LICENSE_FILE, or --license)." | Neither a token nor a license file is set |
| "The holarch command line tool comes with the Individual and Team plans. Choose a plan in Account Settings → Plan & Billing, or use a Holarch Language Engine license file." | The token's account is on the Free plan |
| "The API and MCP come with the Individual and Team plans." | The token's account is on the Free plan and has no API access either |
| "The API token is not valid: it is wrong, revoked or expired, or its account cannot sign in." | Create a new token |
| "The license file's signature does not verify. Use the file exactly as it was delivered." | The license file was changed or damaged |
| "License <id> expired on <date>. Install a renewed license file." | A self-hosted license ended more than 30 days ago, or an engine license key more than 14 days ago |
| "The engine license key's signature does not verify. Use the key exactly as it was delivered." | The key in the file was changed or is from another product |
| "The engine license key is not complete. Copy the whole key (l1.….…) into the file." | Part of the key is missing |
| "… cannot be reached to check the API token" | No connection and no recent answer in the cache; try again, or use a license file |
| "<file>: not formatted: the file has syntax errors." | Run holarch check to see them |
| "<file>: not formatted: a comment could not be kept in place." | The file stays unchanged; the tool never drops a comment |
| "The model has errors, so it was not exported." | Fix the errors, or add --force |
| "The installed engine does not carry the Holarch Language Engine copyright notice, so it is not a genuine Holarch build." | Reinstall the tool |
Limits
- At most 8 MB of SysML text per language in one model, and lines up to 64 KB, as in the editor.
- At most 10,000 files in one run.
- Each engine step stops after
--timeoutseconds (default 60). - Names resolve across files of the same language: a
.sysmlfile does not see names declared in a.kermlfile.