Install Modeler CLI

This guide will help you install Syside Modeler CLI. It covers system requirements, installation steps, license activation, and updating.

Minimum Requirements

To run and use Syside Modeler CLI, you need:

  • Valid Modeler license (available on Sensmetry.com or directly at syside@sensmetry.com)

  • Java 21 runtime

  • System requirements: compatible with Windows, macOS, and Linux

Install Java 21

Proceed to Download CLI if you already have Java 21 installed.

  1. Download and extract Eclipse Temurin JRE 21:

  2. Add the extracted bin directory to your PATH.

  3. Verify with java -version. If you run into issues, see modeler_cli_troubleshooting.

  1. Install JDK 21 or download and extract Eclipse Temurin JRE 21:

  2. If you downloaded Eclipse Temurin, add the extracted bin directory to your PATH.

  3. Verify with java -version. If you run into issues, see modeler_cli_troubleshooting.

  1. Install JDK 21 or download and extract Eclipse Temurin JRE 21:

    • Debian/Ubuntu:

      sudo apt-get install -y openjdk-21-jdk

    • Fedora:

      sudo dnf install java-21-openjdk

    • Eclipse Temurin JRE 21:

  2. If you downloaded Eclipse Temurin, add the extracted bin directory to your PATH.

  3. Verify with java -version. If you run into issues, see modeler_cli_troubleshooting.

How to add to PATH

Option A: via GUI

  1. Open “Environment Variables” (search in Start menu)

  2. Under “User variables”, select “Path” and click “Edit”

  3. Click “New” and add the new path

  4. Click “OK” to save

Option B: via PowerShell

$currentPath = [Environment]::GetEnvironmentVariable("Path", "User")
$newPath = "<path-to-add>"
if ($currentPath -notlike "*$newPath*") {
   [Environment]::SetEnvironmentVariable("Path", "$currentPath;$newPath", "User")
}

Note

Restart your terminal after making PATH changes.

Add this line to ~/.zshrc:

export PATH="<path-to-add>:$PATH"

Then reload your shell configuration:

source ~/.zshrc

Add this line to your shell configuration file (e.g. ~/.bashrc, ~/.zshrc, or equivalent for your shell):

export PATH="<path-to-add>:$PATH"

Then reload your shell configuration or restart your terminal.

source ~/.bashrc

Download CLI

Download Syside Modeler CLI for your platform:

Install CLI

Option A: Manual Installation

  1. Extract the .zip file to %LOCALAPPDATA%\Programs\Syside

  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\Syside

    4. Click “OK” to save

Option B: PowerShell Installation

Run these commands in PowerShell:

# Create directory and extract
mkdir "$env:LOCALAPPDATA\Programs\Syside" -Force
tar -xf syside-0.8.1-x86_64-windows.zip -C "$env:LOCALAPPDATA\Programs\Syside"

# Add to PATH
$currentPath = [Environment]::GetEnvironmentVariable("Path", "User")
$newPath = "$env:LOCALAPPDATA\Programs\Syside"
if ($currentPath -notlike "*$newPath*") {
   [Environment]::SetEnvironmentVariable("Path", "$currentPath;$newPath", "User")
}

Note

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

Version History

  • v0.8.2: Syside bundle was renamed from SysIDE.app to Syside.app.

  1. Open the downloaded .dmg file and drag Syside.app to ~/Applications/

  2. Create a symlink to run syside from anywhere:

    mkdir -p ~/.local/bin
ln -s ~/Applications/Syside.app/Contents/MacOS/syside ~/.local/bin/syside

  3. Add ~/.local/bin to your PATH by adding this line to ~/.zshrc:

    export PATH="$HOME/.local/bin:$PATH"

  4. Reload your shell configuration:

    source ~/.zshrc

  1. Extract the downloaded .tar.xz file to ~/.local:

    mkdir -p ~/.local
tar -xJf syside-<version>-x86_64-linux-glibc.tar.xz --directory ~/.local

  2. Add ~/.local/bin to your PATH by adding this line to ~/.bashrc:

    export PATH="$HOME/.local/bin:$PATH"

  3. Reload your shell configuration:

    source ~/.bashrc

Modeler CLI can be used on all platforms supporting Docker, including ARM-based Macs.

  1. Download the Linux .tar.gz file from Download CLI and place it next to the Dockerfile

  2. Create a Dockerfile:

    FROM debian:trixie-slim

RUN apt-get update -qq && \
    apt-get install -y xvfb openjdk-21-jdk && \
    apt-get clean

ADD syside-x86_64-unknown-linux-gnu.tar.gz /usr/local/lib/syside

RUN ln -s /usr/local/lib/syside/syside /usr/local/bin/syside

    Note

    Replace syside-x86_64-unknown-linux-gnu.tar.gz with the actual file name you downloaded.

  3. Build and run:

    docker build -t syside .
docker run --rm --platform linux/amd64 -it -v $(pwd):/app -w /app syside /bin/bash

    The --platform linux/amd64 flag ensures the container runs correctly on ARM-based hosts (e.g. Apple Silicon Macs). It is safe to include on x64 hosts as well.

Note

Inside the container, prepend xvfb-run -a to all syside viz commands. This creates a virtual display that the Tom Sawyer visualization engine requires to render diagrams.

Verify Installation

Once Syside Modeler CLI is installed, quickly verify it is working as expected.

  1. Open a terminal

  2. Run the following command:

    syside --version

    You should see output similar to: 0.8.1 (4bb41581f62d5fe422a57c1c381aa42cb41203b3)

Activate License

If you have already activated your license through Syside Modeler or Syside Automator, your license key is stored in your system keyring and will be used automatically. Otherwise, set the license key using one of the methods described below.

Warning

License keys are sensitive information, keep them private and secure. Exposure may result in unauthorized use or license revocation.

For local development, you can store the license key in a .env file:

  1. Create a new file named .env in the root of your project directory

  2. Add your license key to the file:

    SYSIDE_LICENSE_KEY=<your-license-key>

Tip

If you are using git for version control, make sure to add .env to your .gitignore file and never commit the .env file to your repository.

For GitLab users, you can also use repository-wide push rules to prevent uploading secrets. See GitLab documentation for details.

Set the SYSIDE_LICENSE_KEY environment variable by running the following command:

  1. Windows (PowerShell):

    $env:SYSIDE_LICENSE_KEY = "<your-license-key>"

  2. macOS / Linux (terminal):

    export SYSIDE_LICENSE_KEY=<your-license-key>

Store your license key in the Operating System’s secret storage:

  • Windows: Windows Credential Store

  • macOS: Keychain credential store

  • Linux: depends on your desktop environment (KDE Wallet on Kubuntu, Passwords and Keys on Ubuntu)

Note

Storing in the secret storage is not supported on systems without the desktop environment such as Docker containers and WSL.

Using the secret storage keeps the key secure and available across all your Python projects without storing it in code or configuration files.

  1. Using Modeler (Recommended):

    1. Open Visual Studio Code or your preferred VSCodium-based editor

    2. Open the Command Palette Ctrl/Cmd-Shift-P

    3. Type Syside Modeler: Add Syside license key to keyring

      • If you’ve already activated a license in Modeler, it will be stored automatically

      • Otherwise, you’ll be prompted to enter your license key

  2. Using Python’s keyring library

    >>> import keyring
>>> keyring.set_password("license-key.syside", "license-key", "<your-license-key>")

Once stored, syside will automatically retrieve the license from your keyring. No additional configuration needed.

Scope: The license key is stored per-user and works across all virtual environments and projects on your machine. Other users on the same computer will need to store their own license keys.

Activate License in CI/CD

Note

Using Modeler CLI in CI/CD requires a Deployment License Key (available under the Business plan).

The deployment license key starts with CI- to make it easier to distinguish.

Most CI/CD providers have secure secret storage for environment variables. Use your provider’s secret management instead of .env files to store your deployment key as SYSIDE_LICENSE_KEY.

Add SYSIDE_LICENSE_KEY as a masked CI/CD variable in your project settings (see GitLab CI/CD variables documentation).

Add SYSIDE_LICENSE_KEY as a repository secret in your repository settings (see GitHub secrets documentation).

Update CLI

Syside Modeler CLI does not have a built-in updater. To update to a new version:

  1. Download the latest version from Download CLI section above

  2. Repeat the Install CLI steps to install the new version

  3. Verify the update:

    syside --version

Tip

Your license activation will be preserved during the update.

Troubleshooting

Missing jvm.dll on Windows

Set JAVA_HOME to your Java installation directory:

  1. Run java -XshowSettings:properties -version and note the java.home value

  2. Open “Environment Variables” (search in Start menu)

  3. Add a new user variable JAVA_HOME with the value from step 1

  4. Also ensure %JAVA_HOME%\bin is in your PATH

Alternatively, via PowerShell:

[Environment]::SetEnvironmentVariable("JAVA_HOME", "<java-home>", "User")

Note

On some systems, you may need to set JAVA_HOME as a system variable instead of a user variable.