Getting started

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

Installation
Tutorial

Some useful resources related to Sysand:

Sysand Package Index
GitHub repository
Sysand community forum
Reach out to sysand@sensmetry.com if you have any questions

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:

Windows (both x86_64 and ARM64)
macOS (both Intel and ARM64 (a.k.a. Apple Silicon))
Linux (both x86_64 and ARM64)

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

Move the downloaded .exe file to %LOCALAPPDATA%\Programs\Sysand\sysand.exe
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

Open PowerShell
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"

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`)

Open Terminal
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.

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

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`)

Open a terminal
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.

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

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
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.

Fields of `.project.json`

`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 either a KPAR file or to a “directory” containing .project.json/.meta.json.
file: can point to either a KPAR file or to a directory containing the project.
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 ssh syntax to be accepted by sysand. For example:

git@github.com:myuser/myrepo.git

translated into standard syntax becomes

ssh://git@github.com:22/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.
urn:kpar: this is by convention used by all projects in the Sysand index, but otherwise has no special meaning

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:

HTTP(S) using the basic access authentication scheme
HTTP(S) using (fixed) bearer tokens (used by, for example, private GitLab pages)

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 maching <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`

init
add
remove
include
exclude
build
lock
env
- install
- uninstall
- list
- sources
sync
info
sources
print-root

`sysand init`

Create new project in current directory

Keyboard shortcuts

Sysand User Guide