Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Getting started

To get started with Sysand, first follow the instructions for installing Sysand, then try out the steps in the tutorial.

Some useful resources related to Sysand:

Installation

There are a few ways to download Sysand:

  • From PyPI
  • From this page
  • From GitHub releases
  • Compile from source

PyPI

Sysand is published to PyPI and includes both the CLI and Sysand Python library.

We recommend installing from PyPI into an isolated (virtual) environment. This can be done with pipx:

pipx install sysand

Or with uv:

uv tool install sysand

Note

pipx/uv tool will make only the CLI part of the package accessible

Both Sysand CLI and Python library can be installed with pip:

pip install sysand

Tip

pip is sometimes called pip3, so if pip command is not available, try pip3

Or with uv (run inside a virtual environment):

uv pip install sysand

Download latest release

Latest official Sysand CLI release can be downloaded below or from latest GitHub release.

Windows macOS Linux
x86_x64
ARM64
After downloading the appropriate file, installation depends on your platform:

It is recommended to then verify the installation.

Windows

The downloaded binary can either be installed manually or by running a few PowerShell commands.

Manual installation

  1. Move the downloaded .exe file to %LOCALAPPDATA%\Programs\Sysand\sysand.exe
  2. Add to PATH via Environment Variables:
    1. Open “Environment Variables” (search in Start menu)
    2. Under “User variables”, select “Path” and click “Edit”
    3. Click “New” and add %LOCALAPPDATA%\Programs\Sysand
    4. Click “Ok” to save

PowerShell installation

  1. Open PowerShell
  2. Run these commands:
# For x86_64 systems

# Create directory and move to it
mkdir "$env:LOCALAPPDATA\Programs\Sysand" -Force
mv sysand-windows-x86_64.exe "$env:LOCALAPPDATA\Programs\Sysand\sysand.exe"

# For ARM64 systems

# Create directory and move to it
mkdir "$env:LOCALAPPDATA\Programs\Sysand" -Force
mv sysand-windows-arm64.exe "$env:LOCALAPPDATA\Programs\Sysand\sysand.exe"
  1. Add folder to PATH:
# Add to PATH
$currentPath = [Environment]::GetEnvironmentVariable("Path", "User")
$newPath = "$env:LOCALAPPDATA\Programs\Sysand"
if ($currentPath -notlike "*$newPath*") {
   [Environment]::SetEnvironmentVariable("Path", "$currentPath;$newPath", "User")
}

Important

Restart your terminal after installation for PATH changes to take effect.

macOS

System installation (requires sudo)

  1. Open Terminal
  2. Make the binary executable and move to a folder in PATH by running the following commands:
# For Intel Macs
chmod +x ~/Downloads/sysand-macos-x86_64
sudo mv ~/Downloads/sysand-macos-x86_64 /usr/local/bin/sysand

# For Apple Silicon Macs
chmod +x ~/Downloads/sysand-macos-arm64
sudo mv ~/Downloads/sysand-macos-arm64 /usr/local/bin/sysand

Alternative: user installation (no sudo required)

It is also possible to install without sudo rights, but that requires additional steps.

  1. Run in Terminal:
# Create local bin directory if it doesn't exist
mkdir -p ~/.local/bin

# Add local bin directory to PATH in your shell profile
# (default ~/.zshrc, but could be ~/.bashrc etc.)
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
  1. Move the executable as shown above for the system installation, but instead of /usr/local/bin/sysand move to ~/.local/bin/sysand.

Linux

System installation (requires sudo)

  1. Open a terminal
  2. Make the binary executable and move to a folder in PATH by running the following commands:
# For x86_64 systems
chmod +x sysand-linux-x86_64
sudo mv sysand-linux-x86_64 /usr/local/bin/sysand

# For ARM64 systems
chmod +x sysand-linux-arm64
sudo mv sysand-linux-arm64 /usr/local/bin/sysand

Alternative: user installation (no sudo required)

It is also possible to install without sudo rights, but that requires additional steps.

  1. Run in a terminal:
# Create local bin directory if it doesn't exist
mkdir -p ~/.local/bin

# Add local bin directory to PATH in your shell profile (~/.bashrc, ~/.zshrc, etc.)
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
  1. Move the executable as shown above for the system installation, but instead of /usr/local/bin/sysand move to ~/.local/bin/sysand.

Verify the installation

Run in a terminal:

sysand --version

You should see an output similar to: sysand X.Y.Z

Download development version

Latest development version of Sysand can be downloaded from GitHub releases by choosing the latest release by date (which is usually labelled starting with “Nightly Release”).

Compiling from source code

Sysand is written in Rust programming language and so can be installed using cargo. Cargo is part of Rust language tooling. If you have it, run the following command in the terminal:

cargo install sysand --git=https://github.com/sensmetry/sysand.git

Tutorial

This section will show a basic way of using Sysand CLI to manage SysML v2 projects. More detailed guides are coming soon.

Initialize a new project using Sysand CLI

A model interchange project is a collection of SysML v2 (.sysml) or KerML (.kerml) files with additional metadata such as project name, versions, and the list of projects on which it depends. To create a new project called my_project run

$ sysand init my_project
    Creating interchange project `my_project`

This command will create a new directory (my_project) and populate it with a minimal interchange project, consisting of two files: .project.json and .meta.json. To instead create a new project in the current directory, omit the path (my_project in this case). In that case, the project’s name will be the same as the current directory name.

Inspect the project

Sysand can show some information about the project that was just created with the following commands:

$ cd my_project
$ sysand info
Name: my_project
Version: 0.0.1
No usages.

$ sysand sources
*NO OUTPUT*

Currently, the project has no usages (dependencies) and no source files of its own.

Add source files

For a project to be useful, it needs to have some .sysml/.kerml files of its own. Create a MyProject.sysml file with the following contents:

package MyProject;

Now, you can add MyProject.sysml to the project by running the following command:

$ sysand include MyProject.sysml
   Including file: `MyProject.sysml`

The source file is now a part of the project, which sysand sources can confirm:

$ sysand sources
/path/to/my_project/MyProject.sysml

Add usages (dependencies)

KerML (and by extension SysML v2) specification calls a project dependency a “usage”. All SysML v2 projects will have at least one dependency on the SysML v2 standard library itself, and many will have dependencies on more SysML v2 projects. The key benefit of Sysand is that it can automatically manage project dependencies for you.

Each usage is identified by an Internationalized Resource Identifier (IRI) with an optional version constraint. To add dependencies, use the sysand add command. The simplest way to use it is to give an IRI to a package you want to install from the Sysand Package Index. You can find the IRI (and the full install command) in the card of the package on the index. It is also possible to install packages from the URL that points to the .kpar file or to a directory that contains the project.

Install usage SYSMOD from Sysand Package Index:

sysand add urn:kpar:sysmod

This may take a few seconds to run, as Sysand needs to download the project (and its usages as well) into a new local environment. Once finished, a file sysand-lock.toml and a directory sysand_env will be created. The former records the precise versions of the external projects installed, so that the same installation can be reproduced later. The latter directory stores the added project and its usages.

$ sysand info
Name: my_project
Publisher: untitled
Version: 0.0.1
Usages:
    urn:kpar:sysmod

Running sysand sources again will list all the .sysml files from both the current project and its (transitive) dependencies.

$ sysand sources
warning: SysML v2/KerML standard library packages are omitted by default.
         If you want to include them, pass `--include-std` flag
/path/to/my_project/MyProject.sysml
/path/to/my_project/sysand_env/a0aacee34dd4cd5e2d07ab43d5e30772ec86dbf3c8fafb033bad338dd7a0f02e/5.0.0-alpha.2.kpar/SYSMOD.sysml

Note

SysML v2 and KerML standard libraries are usually provided by the tooling used to develop the models. For this reason Sysand will not install or show standard libraries (or their files) in its output, unless specifically requested with --include-std for a given command

Tip

sysand-lock.toml is sufficient to reproduce sysand_env on any computer; therefore, we recommend checking in sysand-lock.toml into your version control system and adding sysand_env to .gitignore (or equivalent).

List installed dependencies

When we executed sysand add in the previous subsection, it implicitly created and synchronized an environment for us. For users familiar with Python, Sysand environments serve the same purpose as Python virtual environments: they store dependencies needed for a specific project.

We can see everything installed in the local environment using sysand env list:

$ sysand env list
`urn:kpar:sysmod` 5.0.0-alpha.2

Note

Environment may contain packages that are not (transitive) dependencies of the current project, because projects can also be installed into the environment without adding them to project usages. Also, projects are never automatically removed from the environment, so it may contain projects that are no longer used by the current project.

If you want to recreate (the required part of) the environment on a new machine, make sure you have not only your project files, but also sysand-lock.toml and execute the following command:

$ sysand sync
    Creating env
warning: Direct or transitive usages of SysML v2/KerML standard library packages are
         ignored by default. If you want to process them, pass `--include-std` flag
     Syncing env
  Installing `urn:kpar:sysmod` 5.0.0-alpha.2

Package the project

After the project reaches some maturity level, there might be a need to package it to a .kpar file for sharing with others (either through the Sysand Package Index or otherwise). The .kpar file can be built by running:

$ sysand build
    Building kpar `/path/to/my_project/output/my_project-0.0.1.kpar`
$ ls output/
my_project-0.0.1.kpar

Sysand CLI creates a new directory output and puts the generated .kpar file there. The created .kpar file can then be installed or added as a usage for another project:

$ sysand init my_other_project
...
$ cd my_other_project/
$ sysand add file:///path/to/my_project/output/my_project-0.0.1.kpar
...

Project information and metadata

Each project is defined by interchange project information (.project.json) and metadata (.meta.json) files in the root directory of the project.

Contents of .project.json and .meta.json files are specified in KerML specification, chapter 10.3. Sysand imposes additional requirements for some fields, as documented below. These extra requirements are imposed to achieve better interoperability between different tools, user convenience and to have more structured project information.

To read or modify project information and metadata fields from the command line, use sysand info and its subcommands.

Fields of .project.json

publisher

Person or organization that publishes the project. This is currently not in the KerML specification, we will propose adding it as a mandatory field.

license

Specification does not have any requirements for license format. Sysand encourages the use of SPDX License Expressions to specify licenses. By default Sysand rejects license strings that are not valid SPDX License Expressions. Examples of valid expressions:

  • MIT - MIT license
  • MIT OR Apache-2.0 - MIT and/or Apache-2.0 license applies, chosen by the user
  • LicenseRef-My-License - a custom license (LicenseRef- part is mandatory in this case). This should be used when the license used is not in SPDX License list.

See the specification and license list for more information. If a project’s license is not given, it is assumed that the project cannot be used under any license without owner’s explicit permission.

As specified by REUSE project, license files should be included at the top level directory of the project inside LICENSES subdirectory. License file name should match the license field’s value with .txt appended, except when using composite expressions (those containing OR, AND or WITH). In those cases include all the license/exception files mentioned in the expression. For the complete set of SPDX license and exception files, see the SPDX GitHub repository. Custom licenses (such as LicenseRef-MyCustom) result in license file name LicenseRef-MyCustom.txt.

Each file should have its license specified at the top in a comment. See REUSE spec for details.

version

Specification does not impose any constraints on how the version should look like, it only recommends to use Semantic Versioning (SemVer). Sysand strongly encourages users to use SemVer and by default does not accept non-SemVer 2.0.0 version strings in its commands.

usage

An array identifying all the projects used by the current project (commonly called dependencies in programming contexts).

Each project is identified by an IRI (Internationalized Resource Identifier). IRI is a superset of URI (Uniform Resource Identifier), which is a superset of URL (Uniform Resource Locator), meaning that every URL or URI is also an IRI. For this reason, elsewhere in this documentation IRI, URI and URL are used interchangeably and mean IRI, unless specified otherwise.

IRIs are not required to be resolvable (i.e. be URLs that have a well-defined way of obtaining the identified resource). So Sysand tries to obtain each project using a variety of methods. The first method that successfully obtains the project is chosen. The order in which different methods are tried is unspecified and may change in the future.

Sysand currently supports (i.e. knows how to obtain) these IRI schemes:

  • http/https: can point to a few different things:

    • a KPAR file
    • a “directory” containing .project.json and .meta.json
    • a git repository containing .project.json and .meta.json at its root

  • file: can point to either a KPAR file or to a directory containing the project. Can also point to a directory containing a git repository, but the directory will be treated as a project directory, unless git+file is used.

  • urn:kpar: this is by convention used by all projects in the Sysand index, but otherwise has no special meaning

  • ssh: note that currently only git repositories are supported for this type. SSH repository URLs supported by git have to be translated to use standard IRI to be accepted by sysand. For example:

    git@github.com:myuser/myrepo.git

    translated into standard IRI syntax becomes

    ssh://git@github.com/myuser/myrepo.git

    See git URL documentation for details.

  • git+file/git+http/git+https/git+ssh: same as non-prefixed protocols, but explicitly identify that the destination is a git repository and should be treated as such. This is a way to force Sysand to only use git resolver to obtain the project.

Projects in HTTP(S) indexes can use any IRI schemes (including the ones mentioned above), since scheme is not taken into account when trying to obtain a project from an index. It is recommended to use urn scheme for projects in an index to avoid confusion over how to obtain it.

versionConstraint

versionConstraint field can be used to constrain the allowed versions of a specific project within a usage.

Version constraints use the same syntax as Rust’s Cargo. The usage resolution version selection mechanism is only implemented for semantic version constraints and semantic versions of used projects. Sysand will not be able to correctly (or at all) select versions for usages that do not adhere to SemVer.

See below for details.

Version constraint syntax

A version constraint consists of one or more version comparators, separated by commas. Each version comparator consists of an operator and a version. Version is a SemVer with possibly omitted trailing components, e.g. 1.0.0, 2.3, 5, 2.3.4-beta are all valid in a comparator. The missing components are ignored when matching against a version. Note that versions can only be truncated in version constraints, but not in any other context. In order for the version to satisfy a constraint, it must match all of the comparators in the constraint.

Version comparison operators are listed below. In the examples, := denotes equivalence between expressions.

No operator

A bare version specifier, such as 1.2.3, 2, 3.1. It is exactly equivalent to a caret (^) operator.

Caret operator

Caret operator (^) allows SemVer compatible updates.

Leaving off the caret is a simplified equivalent syntax. It is recommended to use the caret syntax for added clarity.

Versions are considered compatible if their left-most non-zero major/minor/patch component is the same. This is different from SemVer which considers all pre-1.0.0 packages to be incompatible.

Examples:

^1.2.3  := 1.2.3 := >=1.2.3, <2.0.0
^1.2    := 1.2   := >=1.2.0, <2.0.0
^1      := 1     := >=1.0.0, <2.0.0
^0.2.3  := 0.2.3 := >=0.2.3, <0.3.0
^0.2    := 0.2   := >=0.2.0, <0.3.0
^0.0.3  := 0.0.3 := >=0.0.3, <0.0.4
^0.0    := 0.0   := >=0.0.0, <0.1.0
^0      := 0     := >=0.0.0, <1.0.0

Tilde operator

Tilde operator (~) specifies a minimal version with some ability to update. If a major, minor, and patch version or only a major and minor version is specified, only patch-level changes are allowed. If only a major version is given, then minor- and patch-level changes are allowed.

Examples:

~1.2.3  := >=1.2.3, <1.3.0
~1.2    := >=1.2.0, <1.3.0
~1      := >=1.0.0, <2.0.0

Wildcard operator

Wildcard operator (*) allows for any version where the wildcard is positioned.

Examples:

*     := >=0.0.0
1.*   := >=1.0.0, <2.0.0
1.2.* := >=1.2.0, <1.3.0

Equals operator

Equals operator (=) means the exact version is required. Since the version in a comparator may be partial, only the parts specified are required to match exactly.

Examples:

=1.2.3 := >=1.2.3, <1.2.4
=1.2   := >=1.2.0, <1.3.0
=1     := >=1.0.0, <2.0.0

Comparison operators

Comparison operators (<, <=, >, >=) are the most basic, as all the other comparators can be equivalently translated to (possibly multiple) comparison comparators. If only one comparison operator is given, the allowed versions range has no opposite end.

Examples:

>=1.2.0
>1      := >=2.0.0
<2      :=  <2.0.0
<=1.5   :=  <1.6.0

Multiple comparators

As mentioned and shown in the examples above, multiple version comparators can be used in a single constraint when separated with a comma, e.g., >=1.2, <1.5. All comparators in a constraint must be satisfied, so a non-overlapping constraint like <1.2, ^1.2.2 is unsatisfiable.

Pre-releases

Version constraints exclude pre-release versions, such as 1.0.0-alpha, unless specifically asked for, i.e. the exact same version with any pre-release tag must be used in a comparator in order for that comparator to try to match the pre-release versions.

Pre-release versions are considered to be lower than regular versions in SemVer spec. Comparators specifying a pre-release tag can also match regular versions.

Examples:

  • constraint 1.0 will not be satisfied by version 1.0.0-alpha
  • constraint >=1.0.0-beta.2, <2.0.0-alpha.5 will be satisfied by version 1.2.3-rc.2
  • constraint >=5.4.2-beta1 will be satisfied by versions 5.4.2, 6.2.0 and 5.4.2-rc, but not 5.4.3-alpha
  • constraint ^1.2.3-rc will be satisfied by version 1.2.3

Version metadata

Version metadata, such as 1.0.0+21AF26D3, is ignored and should not be used in version requirements.

More information

See Cargo docs, semver crate docs (semver crate is used by both Sysand and Cargo for version selection) and SemVer specification for more detailed information regarding version constraints and semantic versioning.

Authentication

Project indices and remotely stored project KPARs (or sources) may require authentication in order to get authorised access. Sysand currently supports this for:

Support is planned for:

  • HTTP(S) with digest access and OAuth2 device authentication
  • Git with private-key and basic access authentication

Configuring

At the time of writing, authentication can only be configured through environment variables.

Providing credentials for the Basic authentication scheme is done by setting environment variables following the pattern

SYSAND_CRED_<X> = <PATTERN>
SYSAND_CRED_<X>_BASIC_USER = <USER>
SYSAND_CRED_<X>_BASIC_PASS = <PASSWORD>

Where <X> is arbitrary, <PATTERN> is a wildcard (glob) pattern matching URLs, and <USER>:<PASSWORD> are credentials that may be used with URLs matching the pattern.

Thus, for example,

SYSAND_CRED_TEST = "https://*.example.com/**"
SYSAND_CRED_TEST_BASIC_USER = "foo"
SYSAND_CRED_TEST_BASIC_PASS = "bar"

Would tell Sysand that it may use the credentials foo:bar with URLs such as

https://www.example.com/projects/project.kpar
https://projects.example.com/entries.txt
https://projects.example.com/projects/myproject/versions.txt

In the wildcard pattern, ? matches any single letter, * matches any sequence of characters not containing /, and ** matches any sequence of characters possibly including /.

Credentials will only be sent to URLs matching the pattern, and even then only if an unauthenticated response produces a status in the 4xx range. If multiple patterns match, they will be tried in an arbitrary order, after the initial unauthenticated attempt, until one results in a response not in the 4xx range.

Authentication by a (fixed) bearer token works similarly, using the pattern

SYSAND_CRED_<X> = <PATTERN>
SYSAND_CRED_<X>_BEARER_TOKEN = <TOKEN>

With the above the Sysand client will send Authorization: Bearer <TOKEN> in response to 4xx statuses when accessing URLs matching <PATTERN>.

Workspaces

Warning

Workspace support is experimental and may change or be removed in any release. See workspaces tracking issue for planned functionality and changes

Introduction

It is common to have multiple related projects that are all developed together and that usually use each other’s functionality.

Sysand supports such uses with workspaces. A workspace is a collection of projects, commonly structured like this:

workspace
 ├──project_1
 ├──project_2
 └──project_3

Such a structure is not a requirement, though. Projects can be anywhere under the workspace root directory.

Defining a workspace

A workspace is defined by .workspace.json file in the root directory of the workspace.

.workspace.json contains a JSON object. The only currently permitted key is projects, for which the value is an array of objects having two keys:

  • path: A Unix-style path relative to workspace root, specifying the project’s directory
  • iris: An array of IRIs identifying the project. The IRIs can be freely chosen, but reasonable care has to be taken to make them not clash with possible IRIs of third party projects. Any of the included IRIs can be used to refer to the project from other projects in the workspace instead of using file:// URLs

Example

An example .workspace.json file:

{
  "projects": [
    {
      "path": "projectGroup1/project1",
      "iris": ["urn:local:project1"]
    },
    {
      "path": "projectGroup1/project2",
      "iris": ["urn:local:project2"]
    },
    {
      "path": "project3",
      "iris": ["urn:local:project3"]
    }
  ]
}

Commands

Commands available for sysand

sysand init

Create new project in current directory

Usage

sysand init [OPTIONS] [PATH]

Description

Create new project in current directory, i.e. create .project.json and .meta.json files.

Arguments

  • [PATH]: The path to use for the project. Defaults to current directory

Options

  • --name <NAME>: The name of the project. Defaults to the directory name
  • --publisher <PUBLISHER>: The publisher of the project. Defaults to untitled
  • --version <VERSION>: Set the version in SemVer 2.0 format. Defaults to 0.0.1
  • --no-semver: Don’t require version to conform to SemVer
  • --license <LICENSE>: Set the license in the form of an SPDX license identifier. Defaults to omitting the license field
  • --no-spdx: Don’t require license to be an SPDX expression

Global options

  • -v, --verbose: Use verbose output
  • -q, --quiet: Do not output log messages
  • --no-config: Disable discovery of configuration files
  • --config-file <CONFIG_FILE>: Give path to ‘sysand.toml’ to use for configuration
  • -h, --help: Print help

sysand clone

Clone a project to a specified directory. Equivalent to manually downloading, extracting the project to the directory and running sysand sync.

Usage

sysand clone [OPTIONS] <LOCATOR|--iri <IRI>|--path <PATH>>

Description

Allows the user to quickly pull and open a library or an example from a project index. Acts similar to git clone – it needs an empty repository to write the contents to.

Arguments

  • [LOCATOR]: Clone the project from a given locator, trying to parse it as an IRI/URI/URL and otherwise falling back to using it as a path

Options

  • -i, --iri <IRI>: IRI/URI/URL identifying the project to be cloned [aliases: --uri, --url]
  • -s, --path <PATH>: Path to clone the project from. If version is also given, verifies that the project has the given version
  • -t, --target <TARGET>: Path to clone the project into. If already exists, must be an empty directory. Defaults to current directory
  • -V, --version <VERSION>: Version of the project to clone. Defaults to the latest version according to SemVer 2.0
  • --no-deps: Don’t resolve or install dependencies

Resolution options

  • --index [<INDEX>...]: Comma-delimited list of index URLs to use when resolving project(s) and/or their dependencies, in addition to the default indexes
  • --default-index [<DEFAULT_INDEX>...]: Comma-delimited list of URLs to use as default index URLs. Default indexes are tried before other indexes (default https://beta.sysand.org)
  • --no-index: Do not use any index when resolving project(s) and/or their dependencies
  • --include-std: Don’t ignore KerML/SysML v2 standard libraries if specified as dependencies

Global options

  • -v, --verbose: Use verbose output
  • -q, --quiet: Do not output log messages
  • --no-config: Disable discovery of configuration files
  • --config-file <CONFIG_FILE>: Give path to ‘sysand.toml’ to use for configuration
  • -h, --help: Print help

sysand add

Add usage to project information.

Usage

sysand add [OPTIONS] <IRI|--path <PATH>> [VERSION_CONSTRAINT]

Description

Adds IRI and optional version constraint to list of usages in the project information file .project.json. By default this will also update the lockfile and sync the local environment (creating one if not already present).

When adding a usage with one of the --from-* or --as-* flags the configuration file will be automatically updated with a project source override as described in Dependencies. If one of the --from-* flags are used, Sysand will attempt to guess the type of project source, while the --as-* flags let you specify the type explicitly. Sysand cannot determine if a project is to be editable, so for that you need to specify the path with the --as-editable flag.

The affected configuration file will either be the one given with --config-file or (if --no-config is not present) the sysand.toml at the root of the project. If no configuration file is given and --no-config is set, the usage will be added to the project, but no source will be configured, so future syncing will not take this into account.

Arguments

  • <IRI>: IRI/URI/URL identifying the project to be used. See usage field for details.
  • [VERSION_CONSTRAINT]: A constraint on the allowable versions of a used project. Assumes that the project uses Semantic Versioning. See versionConstraint for details

Options

  • -p, --path <PATH>: Path to the project to be added. Since every usage is identified by an IRI, file:// URL will be used to refer to the project.

    Warning: using this makes the project not portable between different computers, as file:// URL always contains an absolute path

  • --no-lock: Do not automatically resolve usages (and generate lockfile)

  • --no-sync: Do not automatically install dependencies

  • --from-path <PATH>: Add usage as a local interchange project at PATH and update configuration file attempting to guess the source from the PATH

  • --from-url <URL>: Add usage as a remote interchange project at URL and update configuration file attempting to guess the source from the URL

  • --as-editable <PATH>: Add usage as an editable interchange project at PATH and update configuration file with appropriate source

  • --as-local-src <PATH>: Add usage as a local interchange project at PATH and update configuration file with appropriate source

  • --as-local-kpar <PATH>: Add usage as a local interchange project archive at PATH and update configuration file with appropriate source

  • --as-remote-src <URL>: Add usage as a remote interchange project at URL and update configuration file with appropriate source

  • --as-remote-kpar <URL>: Add usage as a remote interchange project archive at URL and update configuration file with appropriate source

  • --as-remote-git <URL>: Add usage as a remote git interchange project at URL and update configuration file with appropriate source

Resolution options

  • --index [<INDEX>...]: Comma-delimited list of index URLs to use when resolving project(s) and/or their dependencies, in addition to the default indexes
  • --default-index [<DEFAULT_INDEX>...]: Comma-delimited list of URLs to use as default index URLs. Default indexes are tried before other indexes (default https://beta.sysand.org)
  • --no-index: Do not use any index when resolving project(s) and/or their dependencies
  • --include-std: Don’t ignore KerML/SysML v2 standard libraries if specified as dependencies

Global options

  • -v, --verbose: Use verbose output
  • -q, --quiet: Do not output log messages
  • --no-config: Disable discovery of configuration files
  • --config-file <CONFIG_FILE>: Give path to ‘sysand.toml’ to use for configuration
  • -h, --help: Print help

sysand remove

Remove usage from project information

Will also remove project source overrides from configuration file if available.

Usage

sysand remove [OPTIONS] <IRI>

Description

Removes all instances of IRI from list usages in the project information file .project.json. By default this will also update the lockfile and sync the local environment (creating one if not already present).

Arguments

  • <IRI>: IRI identifying the project usage to be removed

Global options

  • -v, --verbose: Use verbose output
  • -q, --quiet: Do not output log messages
  • --no-config: Disable discovery of configuration files
  • --config-file <CONFIG_FILE>: Give path to ‘sysand.toml’ to use for configuration
  • -h, --help: Print help

sysand include

Include model interchange files in project metadata

Usage

sysand include [OPTIONS] [PATHS]...

Description

Takes all files given by PATHS and adds them to project metadata index and checksum list in .meta.json for the current project. By default the checksum is not computed and is left blank (with algorithm as "None").

Current project is determined as in sysand print-root and if none is found uses the current directory instead.

Arguments

  • [PATHS]...: File(s) to include in the project

Options

  • --compute-checksum: Compute and add file (current) SHA256 checksum
  • --no-index-symbols: Do not detect and add top level symbols to index

Global options

  • -v, --verbose: Use verbose output
  • -q, --quiet: Do not output log messages
  • --no-config: Disable discovery of configuration files
  • --config-file <CONFIG_FILE>: Give path to ‘sysand.toml’ to use for configuration
  • -h, --help: Print help

sysand exclude

Exclude model interchange files from project metadata

Usage

sysand exclude [OPTIONS] [PATHS]...

Description

Takes all files given by PATHS and removes all instances of them to project metadata index and checksum list in .meta.json for the current project.

Current project is determined as in sysand print-root and if none is found uses the current directory instead.

Arguments

  • [PATHS]...: File(s) to exclude from the project

Global options

  • -v, --verbose: Use verbose output
  • -q, --quiet: Do not output log messages
  • --no-config: Disable discovery of configuration files
  • --config-file <CONFIG_FILE>: Give path to ‘sysand.toml’ to use for configuration
  • -h, --help: Print help

sysand build

Build a KerML Project Archive (KPAR). If executed in a workspace outside of a project, builds all projects in the workspace.

Usage

sysand build [OPTIONS] [PATH]

Description

Creates a KPAR file from the current project.

Current project is determined as in sysand print-root and if none is found uses the current directory instead.

Arguments

  • [PATH]: Path for the finished KPAR or KPARs. When building a workspace, it is a path to the folder to write the KPARs to (default: <current-workspace>/output). When building a single project, it is a path to the KPAR file to write (default <current-workspace>/output/<project name>-<version>.kpar or <current-project>/output/<project name>-<version>.kpar depending on whether the current project belongs to a workspace or not).

Options

  • -c, --compression: Method to compress the files in the KPAR.
    Possible values:

    • stored: Store the files as is
    • deflated: Compress the files using Deflate

    [default: deflated]

  • -a, --allow-path-usage Allow usages of local paths (file://). Warning: using this makes the project not portable between different computers, as file:// URL always contains an absolute path. For multiple related projects, consider using a workspace instead

Global options

  • -v, --verbose: Use verbose output
  • -q, --quiet: Do not output log messages
  • --no-config: Disable discovery of configuration files
  • --config-file <CONFIG_FILE>: Give path to ‘sysand.toml’ to use for configuration
  • -h, --help: Print help

sysand lock

Create or update lockfile

Usage

sysand lock [OPTIONS]

Description

Resolves all usages in project information for current project and generates a lockfile sysand-lock.toml in the project root directory with exact versions and sources for all dependencies.

Current project is determined as in sysand print-root and if none is found uses the current directory instead.

Resolution options

  • --index [<INDEX>...]: Comma-delimited list of index URLs to use when resolving project(s) and/or their dependencies, in addition to the default indexes
  • --default-index [<DEFAULT_INDEX>...]: Comma-delimited list of URLs to use as default index URLs. Default indexes are tried before other indexes (default https://beta.sysand.org)
  • --no-index: Do not use any index when resolving project(s) and/or their dependencies
  • --include-std: Don’t ignore KerML/SysML v2 standard libraries if specified as dependencies

Global options

  • -v, --verbose: Use verbose output
  • -q, --quiet: Do not output log messages
  • --no-config: Disable discovery of configuration files
  • --config-file <CONFIG_FILE>: Give path to ‘sysand.toml’ to use for configuration
  • -h, --help: Print help

sysand env

Create a local sysand_env environment for installing dependencies

Usage

sysand env [OPTIONS]

Description

Creates an empty sysand_env environment for the current project if no existing environment can be found, and otherwise leaves it unchanged.

Current project is determined as in sysand print-root and if none is found uses the current directory instead.

Global options

  • -v, --verbose: Use verbose output
  • -q, --quiet: Do not output log messages
  • --no-config: Disable discovery of configuration files
  • --config-file <CONFIG_FILE>: Give path to ‘sysand.toml’ to use for configuration
  • -h, --help: Print help

sysand env install

Install project in sysand_env

Usage

sysand env install [OPTIONS] <IRI> [VERSION]

Description

Installs a given project and all it’s dependencies in sysand_env for current project.

Current project is determined as in sysand print-root and if none is found uses the current directory instead.

If no existing sysand_env is found, a new one will be created in the same way as sysand env.

Arguments

  • <IRI>: IRI identifying the project to be installed
  • [VERSION]: Version to be installed

Options

  • --path <PATH>: Local path to interchange project
  • --allow-overwrite: Allow overwriting existing installation
  • --allow-multiple: Install even if another version is already installed
  • --no-deps: Don’t install any dependencies

Resolution options

  • --index [<INDEX>...]: Comma-delimited list of index URLs to use when resolving project(s) and/or their dependencies, in addition to the default indexes
  • --default-index [<DEFAULT_INDEX>...]: Comma-delimited list of URLs to use as default index URLs. Default indexes are tried before other indexes (default https://beta.sysand.org)
  • --no-index: Do not use any index when resolving project(s) and/or their dependencies
  • --include-std: Don’t ignore KerML/SysML v2 standard libraries if specified as dependencies

Global options

  • -v, --verbose: Use verbose output
  • -q, --quiet: Do not output log messages
  • --no-config: Disable discovery of configuration files
  • --config-file <CONFIG_FILE>: Give path to ‘sysand.toml’ to use for configuration
  • -h, --help: Print help

sysand env uninstall

Uninstall project in sysand_env

Description

Uninstalls a given project in sysand_env.

Usage

sysand env uninstall [OPTIONS] <IRI> [VERSION]

Arguments

  • <IRI>: IRI identifying the project to be uninstalled
  • [VERSION]: Version to be uninstalled

Global options

  • -v, --verbose: Use verbose output
  • -q, --quiet: Do not output log messages
  • --no-config: Disable discovery of configuration files
  • --config-file <CONFIG_FILE>: Give path to ‘sysand.toml’ to use for configuration
  • -h, --help: Print help

sysand env list

List projects installed in sysand_env

Usage

sysand env list [OPTIONS]

Description

List projects installed in sysand_env by IRI and version.

Global options

  • -v, --verbose: Use verbose output
  • -q, --quiet: Do not output log messages
  • --no-config: Disable discovery of configuration files
  • --config-file <CONFIG_FILE>: Give path to ‘sysand.toml’ to use for configuration
  • -h, --help: Print help

sysand env sources

List source files for an installed project and (optionally) its dependencies

Usage

sysand env sources [OPTIONS] <IRI> [VERSION]

Description

Prints the paths to the source files (separated by newlines) for an installed project and (optionally) its dependencies. Is intended to be machine readable.

By default sources for standard libraries are not included, as they are typically shipped with your language implementation.

Arguments

  • <IRI>: IRI of the (already installed) project for which to enumerate source files
  • [VERSION]: Version of project to list sources for

Options

  • --no-deps: Do not include sources for dependencies
  • --include-std: Include (installed) KerML/SysML v2 standard libraries

Global options

  • -v, --verbose: Use verbose output
  • -q, --quiet: Do not output log messages
  • --no-config: Disable discovery of configuration files
  • --config-file <CONFIG_FILE>: Give path to ‘sysand.toml’ to use for configuration
  • -h, --help: Print help

sysand sync

Sync sysand_env to lockfile, creating a lockfile and sysand_env if needed

Usage

sysand sync [OPTIONS]

Description

Installs all projects in the current projects lockfile sysand-lock.toml from the sources listed, into the local sysand_env environment.

If a lockfile is not found, a new lockfile will be generated from the usages in the project information in the same way as sysand lock.

If no existing sysand_env is found, a new one will be created in the same way as sysand env.

Current project is determined as in sysand print-root and if none is found uses the current directory instead.

Resolution options

  • --index [<INDEX>...]: Comma-delimited list of index URLs to use when resolving project(s) and/or their dependencies, in addition to the default indexes
  • --default-index [<DEFAULT_INDEX>...]: Comma-delimited list of URLs to use as default index URLs. Default indexes are tried before other indexes (default https://beta.sysand.org)
  • --no-index: Do not use any index when resolving project(s) and/or their dependencies
  • --include-std: Don’t ignore KerML/SysML v2 standard libraries if specified as dependencies

Global options

  • -v, --verbose: Use verbose output
  • -q, --quiet: Do not output log messages
  • --no-config: Disable discovery of configuration files
  • --config-file <CONFIG_FILE>: Give path to ‘sysand.toml’ to use for configuration
  • -h, --help: Print help

sysand info

Resolve and describe current project or one at at a specified path or IRI/URL

Usage

sysand info [OPTIONS]
sysand info [OPTIONS] <COMMAND>

Description

Prints out the information contained in the .project.json file for the specified project, defaulting to current project if no project is specified. Optionally an extra command can be given to get or set values in .project.json and .meta.json. Note that only local projects (including the current one) can be modified.

Current project is determined as in sysand print-root and if none is found uses the current directory instead.

Options

  • --path <PATH>: Use the project at the given path instead of the current project
  • --iri <PATH>: Use the project with the given IRI/URI/URL instead of the current project
  • --auto-location <AUTO_LOCATION>: Use the project with the given location, trying to parse it as an IRI/URI/URL and otherwise falling back to a local path
  • --no-normalise: Do not try to normalise the IRI/URI when resolving

Resolution options

  • --index [<INDEX>...]: Comma-delimited list of index URLs to use when resolving project(s) and/or their dependencies, in addition to the default indexes
  • --default-index [<DEFAULT_INDEX>...]: Comma-delimited list of URLs to use as default index URLs. Default indexes are tried before other indexes (default https://beta.sysand.org)
  • --no-index: Do not use any index when resolving project(s) and/or their dependencies
  • --include-std: Don’t ignore KerML/SysML v2 standard libraries if specified as dependencies

Global options

  • -v, --verbose: Use verbose output
  • -q, --quiet: Do not output log messages
  • --no-config: Disable discovery of configuration files
  • --config-file <CONFIG_FILE>: Give path to ‘sysand.toml’ to use for configuration
  • -h, --help: Print help

sysand info name

Get or set the name of the project

Usage

sysand info name [OPTIONS]

Description

Prints the name of the given project. With --set, updates the name.

The name field is required and cannot be cleared.

Options

  • --set <NAME>: Set the project name

Global options

  • -v, --verbose: Use verbose output
  • -q, --quiet: Do not output log messages
  • --no-config: Disable discovery of configuration files
  • --config-file <CONFIG_FILE>: Give path to ‘sysand.toml’ to use for configuration
  • -h, --help: Print help

sysand info description

Get or set the description of the project

Usage

sysand info description [OPTIONS]

Description

Prints the description of the given project. With --set or --clear, modifies the description.

Options

  • --set <DESCRIPTION>: Set the project description
  • --clear: Remove the project description

Global options

  • -v, --verbose: Use verbose output
  • -q, --quiet: Do not output log messages
  • --no-config: Disable discovery of configuration files
  • --config-file <CONFIG_FILE>: Give path to ‘sysand.toml’ to use for configuration
  • -h, --help: Print help

sysand info version

Get or set the version of the project

Usage

sysand info version [OPTIONS]

Description

Prints the version of the given project. For index projects, prints all available versions of the project. With --set, updates the version.

By default the version must conform to Semantic Versioning 2.0. Pass --no-semver alongside --set to allow an arbitrary version string.

The version field is required and cannot be cleared.

Options

  • --set <VERSION>: Set the version in SemVer 2.0 format
  • --no-semver: Don’t require version to conform to Semantic Versioning

Global options

  • -v, --verbose: Use verbose output
  • -q, --quiet: Do not output log messages
  • --no-config: Disable discovery of configuration files
  • --config-file <CONFIG_FILE>: Give path to ‘sysand.toml’ to use for configuration
  • -h, --help: Print help

sysand info license

Get or set the license of the project

Usage

sysand info license [OPTIONS]

Description

Prints the license of the given project. With --set or --clear, modifies the license. licence is an accepted alias for this subcommand.

By default the license must be a valid SPDX license expression. Pass --no-spdx alongside --set to allow an arbitrary string. See Project metadata for guidance on license format.

Options

  • --set <LICENSE>: Set the license in the form of an SPDX license identifier
  • --no-spdx: Don’t require license to be an SPDX expression
  • --clear: Remove the project’s license

Global options

  • -v, --verbose: Use verbose output
  • -q, --quiet: Do not output log messages
  • --no-config: Disable discovery of configuration files
  • --config-file <CONFIG_FILE>: Give path to ‘sysand.toml’ to use for configuration
  • -h, --help: Print help

sysand info website

Get or set the website of the project

Usage

sysand info website [OPTIONS]

Description

Prints the website of the given project. With --set or --clear, modifies the website.

The value must be a valid IRI/URI/URL.

Options

  • --set <URI>: Set the website. Must be a valid IRI/URI/URL
  • --clear: Remove the project website

Global options

  • -v, --verbose: Use verbose output
  • -q, --quiet: Do not output log messages
  • --no-config: Disable discovery of configuration files
  • --config-file <CONFIG_FILE>: Give path to ‘sysand.toml’ to use for configuration
  • -h, --help: Print help

sysand info includes-derived

Get or set whether the project includes derived properties

Usage

sysand info includes-derived [OPTIONS]

Description

Prints whether the given project includes derived properties. With --set or --clear, modifies the value.

Options

  • --set <true|false>: Set the value
  • --clear: Remove the field (unset)

Global options

  • -v, --verbose: Use verbose output
  • -q, --quiet: Do not output log messages
  • --no-config: Disable discovery of configuration files
  • --config-file <CONFIG_FILE>: Give path to ‘sysand.toml’ to use for configuration
  • -h, --help: Print help

sysand info includes-implied

Get or set whether the project includes implied properties

Usage

sysand info includes-implied [OPTIONS]

Description

Prints whether the given project includes implied properties. With --set or --clear, modifies the value.

Options

  • --set <true|false>: Set the value
  • --clear: Remove the field (unset)

Global options

  • -v, --verbose: Use verbose output
  • -q, --quiet: Do not output log messages
  • --no-config: Disable discovery of configuration files
  • --config-file <CONFIG_FILE>: Give path to ‘sysand.toml’ to use for configuration
  • -h, --help: Print help

sysand info maintainer

Get or manipulate the list of maintainers of the project

Usage

sysand info maintainer [OPTIONS]

Description

Prints the list of maintainers of the given project. With modifying options, updates the list.

Options

  • --numbered: Prints a numbered list
  • --set <MAINTAINER>: Replace the entire list with a single maintainer
  • --add <MAINTAINER>: Append a maintainer to the list
  • --remove <N>: Remove the maintainer at position N (1-based, as shown by --numbered)
  • --clear: Remove all maintainers

Global options

  • -v, --verbose: Use verbose output
  • -q, --quiet: Do not output log messages
  • --no-config: Disable discovery of configuration files
  • --config-file <CONFIG_FILE>: Give path to ‘sysand.toml’ to use for configuration
  • -h, --help: Print help

sysand info topic

Get or manipulate the list of topics of the project

Usage

sysand info topic [OPTIONS]

Description

Prints the list of topics of the given project. With modifying options, updates the list.

Options

  • --numbered: Prints a numbered list
  • --set <TOPIC>: Replace the entire list with a single topic
  • --add <TOPIC>: Append a topic to the list
  • --remove <N>: Remove the topic at position N (1-based, as shown by --numbered)
  • --clear: Remove all topics

Global options

  • -v, --verbose: Use verbose output
  • -q, --quiet: Do not output log messages
  • --no-config: Disable discovery of configuration files
  • --config-file <CONFIG_FILE>: Give path to ‘sysand.toml’ to use for configuration
  • -h, --help: Print help

sysand info metamodel

Get or set the metamodel of the project

Usage

sysand info metamodel [OPTIONS]

Description

Prints the metamodel of the given project. With modifying options, updates the metamodel.

There are two ways to set the metamodel:

Standard SysML v2 or KerML metamodel — use --set with an optional --release:

sysand info metamodel --set sysml
sysand info metamodel --set kerml --release 20250201

Custom metamodel URI — use --set-custom (mutually exclusive with --set):

sysand info metamodel --set-custom https://example.com/my-metamodel/1.0

Options

  • --set <KIND>: Set a SysML v2 or KerML metamodel. To set a custom metamodel, use --set-custom
  • --release <YYYYMMDD>: Choose the release of the SysML v2 or KerML metamodel. SysML 2.0 and KerML 1.0 have the same release dates (default: 20250201)
  • --release-custom <YYYYMMDD>: Choose a custom release of the SysML v2 or KerML metamodel
  • --set-custom <METAMODEL>: Set a custom metamodel. To set a SysML v2 or KerML metamodel, use --set
  • --clear: Remove the metamodel field

Global options

  • -v, --verbose: Use verbose output
  • -q, --quiet: Do not output log messages
  • --no-config: Disable discovery of configuration files
  • --config-file <CONFIG_FILE>: Give path to ‘sysand.toml’ to use for configuration
  • -h, --help: Print help

sysand info usage

Print project usages

Usage

sysand info usage [OPTIONS]

Description

Prints the list of usages (dependencies) of the given project.

This field is read-only via sysand info. To add or remove usages, use sysand add and sysand remove.

Options

  • --numbered: Prints a numbered list

Global options

  • -v, --verbose: Use verbose output
  • -q, --quiet: Do not output log messages
  • --no-config: Disable discovery of configuration files
  • --config-file <CONFIG_FILE>: Give path to ‘sysand.toml’ to use for configuration
  • -h, --help: Print help

sysand info index

Get project index

Usage

sysand info index [OPTIONS]

Description

Prints the list of indexed source files for the given project.

This field is read-only via sysand info. To add or remove files from the index, use sysand include and sysand exclude.

Options

  • --numbered: Prints a numbered list

Global options

  • -v, --verbose: Use verbose output
  • -q, --quiet: Do not output log messages
  • --no-config: Disable discovery of configuration files
  • --config-file <CONFIG_FILE>: Give path to ‘sysand.toml’ to use for configuration
  • -h, --help: Print help

sysand info checksum

Get project source file checksums

Usage

sysand info checksum [OPTIONS]

Description

Prints the list of source file checksums for the given project.

This field is read-only via sysand info. Checksums are updated by sysand include and removed by sysand exclude.

Options

  • --numbered: Prints a numbered list

Global options

  • -v, --verbose: Use verbose output
  • -q, --quiet: Do not output log messages
  • --no-config: Disable discovery of configuration files
  • --config-file <CONFIG_FILE>: Give path to ‘sysand.toml’ to use for configuration
  • -h, --help: Print help

sysand info created

Get project metadata manifest creation time

Usage

sysand info created

Description

Prints the creation timestamp of the given project’s metadata manifest (.meta.json).

This field is managed automatically and cannot be set or cleared.

Global options

  • -v, --verbose: Use verbose output
  • -q, --quiet: Do not output log messages
  • --no-config: Disable discovery of configuration files
  • --config-file <CONFIG_FILE>: Give path to ‘sysand.toml’ to use for configuration
  • -h, --help: Print help

sysand sources

List source files for the current project and (optionally) its dependencies

Usage

sysand sources [OPTIONS]

Description

Prints the paths to the source files (separated by newlines) for the current project and (optionally) its dependencies. Is intended to be machine readable.

By default sources for standard libraries are not included, as they are typically shipped with your language implementation.

Current project is determined as in sysand print-root and if none is found uses the current directory instead.

Options

  • --no-deps: Do not include sources for dependencies
  • --include-std: Include (installed) KerML/SysML v2 standard libraries

Global options

  • -v, --verbose: Use verbose output
  • -q, --quiet: Do not output log messages
  • --no-config: Disable discovery of configuration files
  • --config-file <CONFIG_FILE>: Give path to ‘sysand.toml’ to use for configuration
  • -h, --help: Print help

sysand print-root

Prints the root directory of the current project

Usage

sysand print-root [OPTIONS]

Description

Tries to find the current project by starting in the current directory end then iteratively going up the parent directories until a project directory is found.

A project directory is considered to be any directory containing either a .project.json or a .meta.json file.

Global options

  • -v, --verbose: Use verbose output
  • -q, --quiet: Do not output log messages
  • --no-config: Disable discovery of configuration files
  • --config-file <CONFIG_FILE>: Give path to ‘sysand.toml’ to use for configuration
  • -h, --help: Print help

Self-hosting a Project Index

Introduction

This section provides instructions on how to use Sysand CLI to host a private Sysand project index. The guide describes three ways to run the index:

  • Local Machine – running a HTTP file server on your machine
  • GitHub – using a GitHub repository
  • GitLab – using GitLab Pages

Note

This guide is only concerned about hosting the package files in the structure that Sysand CLI can understand. Hosting of a front-end website (such as beta.sysand.org) is not a part of this guide.

Warning

Sysand is in active development. The structure of indexes and sysand_env folders can and will change with future updates of Sysand. As long as Sysand is on version 0.x.y, we cannot guarantee backwards compatibility between different Sysand versions and indexes created using different Sysand versions.

Local Machine

This part of the guide focuses on running a Sysand index on your local machine for testing purposes, but the general approach applies to a more sophisticated production hosting as well. Get in touch with your IT administrator to get this running on your company’s infrastructure.

The easiest way to host a project index from which to install packages is to expose a sysand_env over HTTP, since indexes and sysand_env share the same structure that is understood by Sysand.

Create sysand_env

First, use the Sysand CLI to create a Sysand environment:

sysand env

This will create a sysand_env/ folder in your current directory.

Add Packages to the Environment

You can now install the packages you want to share into the Sysand environment. For example, if you have a MyProject.kpar file in your current directory, you can add it to the package index by:

sysand env install urn:kpar:my_project --path MyProject.kpar

This command will create an entry in the package index with the IRI of urn:kpar:my_project that other people can then use to install your package. With the --path argument, you point to the .kpar file that you want to host on the package index.

Tip

Any IRI can be freely chosen here, just don’t choose an IRI that could point to another resource, like the ones starting with http(s), file or ssh.

By default, this command also installs all usages (dependencies) of my_project. You can use the --no-deps CLI flag to only install the package without dependencies.

If you want to host multiple versions of the same package in your repository, you also need to use the --allow-multiple CLI flag in the sysand env install command.

Repeat this step for as many times as you have packages (and their versions), giving a unique IRI for each different package.

Start an HTTP server

Once you install all the required packages, you can use Python and its built-in http.server module to quickly start a simple HTTP server that will make the package index accessible over the network. To do this, run:

python3 -m http.server -d sysand_env 8080

This command executes the http.server module on port 8080, and tells the module to expose the contents of the sysand_env folder to the network.

Important

Python’s built-in http.server module is not intended for production use.

To set up a real production environment, ask your IT department for guidelines or to do it for you.

Sysand Client Setup

You should now be able to access the package index through http://localhost:8080. To test it, create a new SysML v2 project in another directory by following the User Guide.

Then, when adding a new usage to the project, use the --index argument to point to your private package index instead of the public beta.sysand.org, for example:

sysand add urn:kpar:my_project --index http://localhost:8080

Important

localhost tells Sysand to look for the package index running on your machine. For connecting to other machines replace localhost by the address of the other machine, ensuring that networking and firewalls are correctly configured.

An alternative to --index argument is defining the custom index in sysand.toml. See Indexes for details.

GitHub

This part of the guide shows how to run a Sysand index from a private GitHub repository. This allows you to host an index without needing to ask your IT department to set up a server for you, while also allowing simple access control through GitHub’s access management.

Note

Since GitHub Pages do not support authentication using personal access tokens (in contrast to GitLab Pages), this guide presents a workaround that uses access to raw file contents through raw.githubusercontent.com. This solution might not be ideal for hosting big indices, as GitHub can rate-limit access to raw.githubusercontent.com without prior notice.

Sensmetry has a public GitHub repository implementing this approach. It is licensed under the Creative Commons Zero license and can be freely forked and used in any setting.

Repository Contents

There are two important branches in the repository:

  • main branch – This is the main branch for human interactions. This branch contains the packages folder that holds the .kpar files of all the projects that need to be shared through the index.
  • index branch – This branch is not supposed to be interacted with by humans. This branch is exposed to the Sysand client as the index. It contains an auto-generated file structure and always uses git reset --hard and git push --force to avoid exploding the size of the git repository. Ideally, branch rules should be set up that would only allow the automated bot to make changes to the index branch.

Other branches can also be used, e.g. to allow reviews of the projects before publishing them. However, they should only target the main branch, and not index. Additionally, currently the GitHub Workflow is set up to run only on the main branch.

GitHub Workflow

A GitHub Workflow can be found in the .github/workflows/ci.yml file on the main branch. This workflow is triggered on every commit to the main branch, at which point it:

  1. Installs Sysand client
  2. Creates a Sysand environment, and installs all .kpar projects from the packages as described in the Add Packages to the Environment section above
  3. Resets the index branch to the initial commit using git reset --hard
  4. Takes the environment created in Step 2 and creates a git commit
  5. Pushes the new commit to the index branch with git push --force

Note

During step 2, the Workflow generates a urn for the project from the contents of the name field in .project.json of the project. Therefore, our strong suggestion is to keep the name only contain lower-case ASCII characters with no spaces. However, the Workflow can be adjusted to allow for other naming conventions.

Sysand Client Setup

You should now be able to access the package index through https://raw.githubusercontent.com/OWNER/REPO/refs/heads/index/, where OWNER and REPO is specific to where you created the project and how you named it. To test it, create a new SysML v2 project in another directory by following the User Guide.

Before you can use the index for adding usages, you need to tell Sysand how to authenticate with your index. You can do this by setting the following environment variables. See Authentication for details.

  • SYSAND_CRED_GITHUB to the value of https://raw.githubusercontent.com/OWNER/REPO/refs/heads/index/**. Do not forget to replace OWNER and REPO to your values. Note: the ** ending is important.
  • SYSAND_CRED_GITHUB_BEARER_TOKEN to the value of the GitHub Personal Access Token. We recommend using a fine-grained token scoped to this index repository only, and with only Contents read-only permissions.

Now, when adding a new usage to the project, use the --index argument to point to your private package index instead of the public beta.sysand.org, for example:

sysand add urn:kpar:my_project --index https://raw.githubusercontent.com/OWNER/REPO/refs/heads/index/

An alternative to --index argument is defining the custom index in sysand.toml. See Indexes for details.

GitLab

This part of the guide shows how to run a Sysand index from a private GitLab Pages instance. This allows you to host an index without needing to ask your IT department to set up a server for you, while also allowing simple access control through GitLab’s access management.

Sensmetry has a public GitLab repository implementing this approach. It is licensed under the Creative Commons Zero license and can be freely forked and used in any setting.

Repository Contents

The repository is quite simple, containing a main branch that holds the .kpar files of all the projects that need to be shared through the index and a CI/CD pipeline definition.

Other branches can also be used, e.g. to allow reviews of the projects before publishing them. Currently, the pipeline builds the index on all branches, but publishes the index only on the main branch.

CI/CD Pipeline

A CI/CD Pipeline can be found in the .gitlab-ci.yml file on the main branch. This pipeline is triggered on every commit to the main branch, at which point it:

  1. Installs Sysand client
  2. Creates a Sysand environment, and installs all .kpar projects from the packages as described in the Add Packages to the Environment section above
  3. Uses pages job to deploy the generated Sysand environment to GitLab Pages.

Note

During step 2, the pipeline generates a urn for the project from the contents of the name field in .project.json of the project. Therefore, our strong suggestion is to keep the name only contain lower-case ASCII characters with no spaces. However, the pipeline can be adjusted to allow for other naming conventions.

Sysand Client Setup

You should now be able to access the package index through https://GITLAB-ASSIGNED-DOMAIN.gitlab.io or your custom domain. To test it, create a new SysML v2 project in another directory by following the User Guide.

Before you can use the index for adding usages, you need to tell Sysand how to authenticate with your index. You can do this by setting the following environment variables. See Authentication for details.

  • SYSAND_CRED_GITLAB to the value of https://GITLAB-ASSIGNED-DOMAIN.gitlab.io/**. Do not forget to replace GITLAB-ASSIGNED-DOMAIN with your value. Note: the ** ending is important.
  • SYSAND_CRED_GITLAB_BEARER_TOKEN to the value of the GitLab Personal Access Token. We recommend using a token with only read-api scope.

Now, when adding a new usage to the project, use the --index argument to point to your private package index instead of the public beta.sysand.org, for example:

sysand add urn:kpar:my_project --index https://GITLAB-ASSIGNED-DOMAIN.gitlab.io

An alternative to --index argument is defining the custom index in sysand.toml. See Indexes for details.

Publishing a package to Sysand Index

This guide will instruct how to submit your package to Sysand Package Index manually. Sensmetry is currently working on automating this process.

Manual submission

  1. Produce your package

    Sysand CLI at the moment can only package textual SysML v2 or KerML files into .kpar project interchange archives. Therefore, the Sysand Package Index currently only accepts projects developed in SysML v2 or KerML textual files.

  2. Add project metadata

    Project metadata relevant here is stored in .project.json. It can either be edited using Sysand (recommended) or by using any text editor. sysand info is used to modify the information.

    • Name of the project: Make it short and sweet. Avoid having spaces in the name if possible.

      Set it with sysand info name --set <NAME>

    • Description: Couple of sentences describing what this project can be used for. Keep it succinct.

      Set it with sysand info description --set <DESCRIPTION>

    • Version: A version number of the project you’re submitting. Shall follow the Semantic Versioning schema.

      Set it with sysand info version --set <VERSION>

    • License: Which license this project is licensed under, e.g. MIT, Apache, GPL, any other. Ideally the license has an identifier from SPDX. If no license is given here, we will assume that the package is licensed under the MIT license.

      Set it with sysand info license --set <SPDX LICENSE EXPRESSION>

    • Maintainer: A list of names of main maintainers (individuals or companies), preferably with email address(es), of the project.

      Add a maintainer to the list with sysand info maintainer --add <MAINTAINER>

    • Website (optional): A URL to where people can find more information about the project. Can be a homepage, or a GitHub/GitLab repository.

      Set it with sysand info website --set <WEBSITE>

    • Topic: A list of topics relevant to the project. These will be treated as keywords. In the future, users will be able to search/filter the package index using topics.

      Add a topic to the list with sysand info topic --add <TOPIC>

    • Usage: A list of dependencies this project depends on, with links to them if the dependencies do not exist on the Sysand package index yet. By default your project will most likely depend on SysML v2 standard libraries. Important: To be able to publish your package to the index, all of its dependencies must be publicly available!

      Add usage to the list with sysand add <IRI>

  3. (Optional) Package the project into .kpar

    Once you have filled out the metadata requested above, you can use Sysand CLI to package the project into one neat .kpar file.

    More information on how to do that can be found in the Tutorial. The short version, assuming all .sysml/.kerml files are already included in the project, is to run this command inside your project:

    sysand build

    The built .kpar file will be in the output/ folder.

  4. Send the project to Sysand team

    When you have the project and the answers to the questionnaire prepared, please send them as an email to sysand@sensmetry.com. The Sysand team will review the project and the metadata, package everything into a .kpar package, and upload it to the Index.

    Do not forget to attach the required .sysml/.kerml (or .kpar) files to the email!

Important

Terms of publishing

By submitting your package to the Sysand Package Index, you confirm that:

  • You agree not to submit packages containing malicious code, inappropriate content, or content that infringes on third-party rights.
  • You (co-)own the rights to the package and have the rights to redistribute it.
  • The package does not contain any proprietary or confidential data that cannot be shared publicly.
  • You acknowledge that you are responsible for maintaining accurate package information and metadata.
  • You give the right to Sensmetry to redistribute the package publicly through the Sysand Package Index.
  • You consent to Sensmetry running basic validations on the package using the Syside tool and making the validation results public.
  • Accept that Sensmetry reserves the right to modify these terms and the service without prior notice.

Configuration

Sysand offers three ways of configuring its behavior:

  • command line options
  • environment variables
  • configuration files

Command line options override corresponding environment variables, while both take priority over (but not always override) options in configuration files.

Configuration files

Sysand will look for a sysand.toml file in the current directory or in the current project directory (see print-root command) if such has been found. Automatic discovery of configuration files can be disabled with the command line option --no-config or setting the environment variable SYSAND_NO_CONFIG to true.

The command line option --config-file (or environment variable SYSAND_CONFIG_FILE) can be used to specify the path to an additional config file.

Configurable options

Indexes

Sysand defaults to using the index beta.sysand.org but it is possible to specify additional indexes or override this default index.

URLs for additional indexes can be specified with the command line argument --index. Multiple indexes can be given by invoking the argument multiple times, or by passing a comma separated list of URLs. The corresponding environment variable is SYSAND_INDEX, which also accepts comma separated lists of URLs.

Indexes specified with command line arguments or environment variables are prioritized when resolving dependencies but do not override indexes defined in configuration files.

The command line argument --default-index (and environment variable SYSAND_DEFAULT_INDEX) functions the same as --index but will override the default index https://beta.sysand.org and any default indexes defined in configuration files.

Defining an index in a configuration file

To add an index with the URL https://index.example.org simple add the following entry to your sysand.toml:

[[index]]
url = "https://index.example.org"

To override the default index add default = true:

[[index]]
url = "https://index.example.org"
default = true

Indexes are prioritized in the order they are given, with default indexes always having lower priority compared to regular indexes.

Dependencies

Sometimes you may wish to use a project that isn’t resolvable through an available index or you want to override the dependency resolution for other reasons. Or you may just want to replace a URL usage with a URN usage for better readability. In any case you can do this by adding the appropriate IRI and sources to a project entry in the sysand.toml configuration file at the root of your project. This follows the same structure as found in the lockfile, where identifiers are given as a list of IRIs and sources are a list of sources. A project may have multiple identifiers in case it is referred to differently by different projects, and multiple sources where the additional ones after the first serve as backups in case the previous ones fail to resolve. Note that these should be sources of the exact same project as determined by its checksum, as otherwise you are likely to run into problems when syncing against a lockfile.

Below we describe how to add overriding sources directly to the configuration file, but it is also possible to do through the command line interface with the sysand add command by using one of the --from-* flags to have Sysand try to guess a project source from the path/URL, or using one of the --as-* flags if you want to specify exactly which type of project source you want.

All paths in project sources are assumed to be relative to the root of your project.

Local projects

To specify the source of a project that you have locally in a directory ./path/to/project by the identifier urn:kpar:my-project, is done by adding the following entry to your sysand.toml.

[[project]]
identifiers = [
    "urn:kpar:my-project",
]
sources = [
    { src_path = "path/to/project" },
]

This source corresponds to the --as-local-src flag.

Local editable projects

Normally when you add a project as a usage, Sysand will copy and install it, so any changes made to the original project afterwards will not affect the installed project. For local projects you also have the option to add them as “editable” usages, meaning the project won’t be copied and will instead just be referred to where it is originally located. A local project is specified as editable in sysand.toml by adding

[[project]]
identifiers = [
    "urn:kpar:my-project",
]
sources = [
    { editable = "path/to/project" },
]

This source corresponds to the --as-editable flag.

Local KPARs

If you have a project locally available as a compressed KPAR this can be identified by urn:kpar:my-kpar-project by adding

[[project]]
identifiers = [
    "urn:kpar:my-kpar-project",
]
sources = [
    { kpar_path = "path/to/project.kpar" },
]

to your sysand.toml. This source corresponds to the --as-local-kpar flag.

Remote projects

Remote project are those available through URLs, and similar to local projects the way to specify them as sources depends on which format they come in.

To specify a KPAR available at a URL as a source, add

[[project]]
identifiers = [
    "urn:kpar:remote-kpar-project",
]
sources = [
    { remote_kpar = "https://www.example.com/path/to/project.kpar" },
]

to your sysand.toml. This source corresponds to the --as-remote-kpar flag.

For projects that are not packaged you can either use

[[project]]
identifiers = [
    "urn:kpar:remote-project",
]
sources = [
    { remote_src = "https://www.example.com/path/to/project" },
]

or, if the project is hosted on a Git forge like GitHub, GitLab etc. use

[[project]]
identifiers = [
    "urn:kpar:remote-git-project",
]
sources = [
    { remote_git = "https://github.com/my_user/project.git" },
]

These sources corresponds to the --as-remote-src and --as-remote-git flags respectively.

Note

Currently there is no way to specify a particular git reference like e.g. a branch, tag or commit. It is also currently not possible to specify a project path in a repository.