Holarch

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.

How to use it →

On this page
  1. Overview
  2. Concepts
  3. How to use it
    1. When and why
    2. Install
    3. Sign in with an API token
    4. Check a model
    5. Format files
    6. Export the model as SysML v2 JSON
    7. Run it in GitHub Actions
    8. Run it in other CI systems
    9. Worked example: the Hybrid Car demo
    10. Tips and good practice
    11. Common mistakes
    12. How it connects to other features
  4. Commands
    1. Options of check
    2. Options of format
    3. Options of export
    4. Options of every command that signs in
  5. Sign-in for the tool
    1. License files in CI
  6. Reports
    1. JSON output
    2. SARIF
    3. GitHub annotations
  7. Exit codes
  8. Messages
  9. Limits
  10. Related pages

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 .sysml files 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: .kerml files 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 version prints 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

  1. Install Python 3.9 or later.
  2. Install the tool for your system (Linux x86-64, Linux arm64 or macOS on Apple silicon) with pip:
python3 -m pip install holarch-cli
  1. Check the installation: holarch version prints the tool, engine and library versions.

Sign in with an API token

  1. In Holarch, open Account Settings → API tokens and create a token. Read only access is enough.
  2. Put the token in the HOLARCH_API_KEY environment variable (in CI: a secret).
  3. 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

  1. Run holarch format models/. Each changed file is listed as "reformatted <file>".
  2. 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.
  3. 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

  1. Add the API token as a repository secret named HOLARCH_API_KEY (Settings → Secrets and variables → Actions).
  2. 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
  1. 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 --check step 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

  1. Create the demo: on Manage Projects, click Project Files ▾ → New Demo Project → Hybrid Car (SysML v2).
  2. Open Model → Import and Export. Under Export, choose The whole model and SysML v2 text, click Export, and unzip the download into a folder models of your repository.
  3. Run holarch check models. The result is "6 files checked: 0 errors, 0 warnings."
  4. In requirements.sysml, change attribute maxCurbMass : MassValue to MassValu and run the check again. It reports requirements.sysml:14:27: error name.unresolved: “MassValu” is not defined here. and exits with 1.
  5. Undo the change. Run holarch format models once and commit the files, so later format --check runs pass.
  6. 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

CommandWhat 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 whoamiShows what the token or license file allows
holarch versionPrints 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

OptionMeaning
--format human|json|sarif|githubThe report on standard output (default human)
--output FILEWrite that report to a file instead
--sarif FILEAlso write a SARIF 2.1.0 report
--json FILEAlso write a JSON report
--warnings-as-errorsExit 1 on warnings too

Options of format

OptionMeaning
--checkChange nothing; exit 1 when a file would change
--diffChange nothing; print the changes as a unified diff
--stdoutPrint the formatted text of one file instead of writing it

Options of export

OptionMeaning
-o FILE, --output FILEWrite to a file (default: standard output)
--holarch-fieldsAdd the fields only Holarch reads, for an exact round trip
--forceExport a model with errors (never one with syntax errors)

Options of every command that signs in

OptionEnvironment variableMeaning
--api-key KEYHOLARCH_API_KEYAn API token (hol_…); prefer the variable, so the token stays out of logs
--license FILEHOLARCH_LICENSE_FILEA license file for offline use
--server URLHOLARCH_SERVERThe Holarch server that checks the token (an https address)
--timeout SECONDSTime 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_DIR moves 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 example holarch-engine.key, and point --license or HOLARCH_LICENSE_FILE at 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.

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:

FieldMeaning
tool, version, engineholarch, the tool's version, the engine's version
filesThe files checked, as paths relative to the folder the tool ran in
summaryerrors, warnings, notes, files
diagnosticsfile, line, column, endLine, endColumn (1-based), severity (error, warning, info), code, message, args
skippedFiles not checked, with the reason (KerML files with an older engine)
excludedFiles 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

CodeMeaning
0No errors (format: nothing left to change)
1The model has errors; format --check or --diff: a file would change, or a file could not be formatted; export: refused because of errors
2Wrong usage: an unknown option, a path that does not exist, no model files
3Not 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
4The engine cannot run, or refused the model as too large or too slow to check

Messages

MessageMeaning
"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 --timeout seconds (default 60).
  • Names resolve across files of the same language: a .sysml file does not see names declared in a .kerml file.