CLI Commands

Command	Description
check	Validate models for semantic errors and warnings
format	Format SysML v2 models according to a consistent style
viz Labs	Generate diagrams from SysML v2 models
table Labs	Generate CSV exports of grid views

Check command

Validates models for semantic errors and warnings.

Basic Usage

• Validate specific files

  syside check /path/to/analyzed_model.sysml /path/to/analyzed_model_2.sysml
  

• Validate all files in current directory recursively

  syside check
  

  Note

  When using syside check without explicitly listing out the files, Syside ignores hidden files and files from hidden directories (starting with ., e.g. .venv or .git). To analyze files from these directories, list them explicitly.

Output

If Syside does not find any errors or warnings, there will be no output. If Syside does find anything, the output will look similar to this:

/path/to/analyzed_model.sysml:5:28: error (type-error): 'Non-Conforming Types 1'::a does not conform to ScalarValues::String
   5 |     attribute b : String = a;
     |                            ^
/path/to/analyzed_model.sysml:12:30: error (type-error): ScalarValues::Integer does not conform to ScalarValues::Positive
   12 |     attribute b : Positive = -42;
      |                              ^^^
/path/to/analyzed_model.sysml:30:27: error (type-error): Collect::A does not conform to Collect::B
   30 |     attribute b : B [*] = (1..10)->collect { in attribute x : Positive; new A(x) };
      |                           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
/path/to/analyzed_model.sysml:38:34: error (type-error): ScalarValues::Integer does not conform to ScalarValues::Positive
   38 |     attribute b : Positive [*] = (-1..10)->select { true };
      |                                  ^^^^^^^^^^^^^^^^^^^^^^^^^

The output contains the source file path, line number, character number, diagnostic code, message, and code snippet.

Available Options

Option	Description
-h, --help	Display the help message with all available flags and short descriptions
-d, --diagnose <VALUE>	Choose which files to validate: project (default, does not validate external libraries or standard library), external (also validates external libraries), all (also validates standard library), none (skip validation)
--warnings-as-errors	Treat warnings as errors, exiting with a non-zero code if any warning is found
-q, --quiet	Suppress main output
-s, --stats	Print all analyzed files and the number of diagnostics found in each
-t, --time	Print how long analysis took per file. Combine with --stats
-c, --colour <VALUE>	Colorize output: auto (default), yes, no
-o, --output <OUTPUT>	Write --stats / --time results to a file
--config <FILE>	Path to a syside.toml configuration file
-j <THREADS>	Concurrency level, 1 to 8 (default: 4)
-i, --include <PATTERN>	Additional paths to include as external libraries
-e, --exclude <PATTERN>	Paths or glob patterns to exclude from analysis
--sysand-dir <DIRECTORY>	Path to a .sysand directory. Defaults to <root>/.sysand, or .sysand in the current directory if no project root is found
--std <DIRECTORY>	Path to the sysml.library standard library directory. If omitted, Syside uses its bundled standard library
--crash-reports <ACTION>	Automatic crash report handling: ignore (default) or upload. More information at What Data We Collect.

Usage Examples

Run validation in CI/CD pipeline:

syside check

Format command

Formats SysML v2 models according to a consistent style. Useful when working in a team and using version control systems to prevent whitespace-only changes in history.

Basic Usage

• Format specific files

  syside format /path/to/formatted_model.sysml /path/to/formatted_model_2.sysml
  

• Format all files in current directory recursively

  syside format
  

  Note

  When using syside format without explicitly listing out the files, Syside ignores hidden files and files from hidden directories (starting with ., e.g. .venv or .git). To format files from these directories, list them explicitly.

Output

After running the format command, you should see output similar to:

$ syside format
/path/to/formatted_model.sysml: formatted
1 file reformatted, 0 files left unchanged

The output shows the path of the file(s) that were reformatted, as well as the number of files that did not need reformatting.

Check Mode

The syside format --check command can act as a quality gate without editing the files:

• If none of the files need reformatting, Syside outputs <num> file[s] already formatted and exits with code 0 (success)

• If at least one file needs reformatting, Syside exits with code 1 (failure) and outputs:

  /path/to/formatted_model.sysml: would be formatted
  1 file would be reformatted, 0 files already formatted
  

• If syntax errors are found, Syside exits with code 2 (failure)

Note

For semantic validation, use syside check command. The format command only checks syntax errors.

Available Options

Option	Description
-h, --help	Display the help message with all available flags and short descriptions
-c, --check	Check whether files need reformatting without editing them
-q, --quiet	Suppress main output
--line-width <WIDTH>	Maximum line length the formatter will target
--tabs	Indent using tabs instead of spaces
--tab-width <WIDTH>	Number of spaces per indentation level. Only applies if not using --tabs (default: 4)
--config <FILE>	Path to a syside.toml configuration file
-j <THREADS>	Concurrency level, 1 to 8 (default: 4)
-e, --exclude <PATTERN>	Paths or glob patterns to exclude from formatting
--crash-reports <ACTION>	Automatic crash report handling: ignore (default) or upload. More information at What Data We Collect.

Usage Examples

Use in Git pre-commit hooks to prevent commits with bad formatting:

#!/bin/bash
# .git/hooks/pre-commit

syside format --check

For more information about Git hooks, see Git documentation.

Viz command Labs

The viz commands render SysML v2 diagrams using Sensmetry’s built-in visualization engine. No external display server or additional system packages are required, so the commands run unchanged on headless servers and in CI.

Element command

Generates diagrams for individual model elements by qualified name, without requiring view definitions in the model.

Basic Usage

Pass one or more model files or directories and select the element to render with --qualified-name:

syside viz element <paths...> --qualified-name <name> --output-file <file>

• <paths...> - one or more .sysml files or directories (searched recursively)

• --qualified-name <name> - qualified name of the element to visualize. Repeatable to render several roots into one diagram. If omitted, the whole model is rendered

• --output-file <file> - path to save the image; format is inferred from extension (default: element.svg)

Note

In SysML v2, element names can contain spaces and special characters (e.g. 'Flight Controller v2' or 'Motor "Type A"'). When passing qualified names that contain such names, make sure to quote or escape them appropriately for your shell. For example, names with spaces should be wrapped in double quotes:

syside viz element drone-model/ -n "DroneModel::'Flight Controller v2'"

Alternatively, use simple names without spaces or special characters.

Available Options

Option	Description
-h, --help	Display the help message with all available flags and short descriptions
-n, --qualified-name <QNAME>	Qualified name of a root element to render (e.g. MyPackage::MyPartDef). Repeatable to render several roots into one diagram. If omitted, the whole model is rendered
-d, --depth <DEPTH>	How many levels of descendants to render. -1 means infinite depth (default: -1)
-r, --rendering <TYPE>	Rendering type: nested (default) or tree. Also accepts asNestedDiagram and asTreeDiagram (matching SysML v2 rendering names). Overrides syside.toml [layout.render_style]
-v, --view <VIEW>	SysML v2 view kind: general (default), interconnection, action_flow, state_transition or sequence. Overrides syside.toml [layout.view].default
-t, --theme <THEME>	Diagram theme: light (default), dark, light_mono or dark_mono. Overrides syside.toml [style].theme
-z, --zoom-level <LEVEL>	Zoom level for rendering. Applicable only to PNG and JPEG output. Overrides syside.toml [render].zoom_level (default: 3.0)
-o, --output-file <FILE>	Path to save the image. Format is determined by extension. Supported formats: svg, png, jpeg. Default: element.svg
--config <FILE>	Path to a syside.toml configuration file
-i, --include <PATH>	Additional file, directory, or glob pattern to include. Repeatable
-e, --exclude <PATTERN>	Paths or glob patterns to exclude from file discovery. Repeatable

Usage Examples

The following examples use the drone model from the reference files section.

DroneModel.sysml

package DroneModel {
    doc
    /* This example illustrates how to define views that can be visualized
     * using `syside viz view` command. Please see the documentation in
     * file `DroneModelViews.sysml`.
     */

    private import ScalarValues::*;

    part def Drone {
        part battery : Battery;
        part motors : Motor [4..6];
        part controller : FlightController;
        part droneFrame : DroneFrame;
    }

    part def Battery {
        attribute capacity : Real;
        attribute voltage : Real;
        attribute mass : Real;
    }

    part def Motor {
        attribute maxSpeed : Real;
        attribute power : Real;
        attribute mass : Real;
    }

    part def FlightController {
        attribute processorSpeed : Real;
        attribute mass : Real;
    }

    part def DroneFrame {
        attribute mass : Real;
        attribute material : String;
    }

    part def DroneSystem {
        part myDrone : Drone {
            part :>> motors [4] : Motor;
        }
        part someoneElsesDrone : Drone {
            part :>> motors [6] : Motor;
        }
    }

}

• Render DroneSystem with one level of depth:

  syside viz element drone-model/ -n "DroneModel::DroneSystem" --depth=1 -o DroneSystem.png
  

  

• Render the full Drone definition with all descendants:

  syside viz element drone-model/ -n "DroneModel::Drone" -o DroneFull.png
  

  

• Same diagram as SVG:

  syside viz element drone-model/ -n "DroneModel::Drone" -o DroneFull.svg
  

• Render as a tree layout instead of nested:

  syside viz element drone-model/ -n "DroneModel::DroneSystem" --rendering asTreeDiagram -o DroneSystem_Tree.png
  

  

View command

Renders diagrams from SysML v2 view definitions in the model. This is the recommended approach for repeatable, version-controlled diagram generation.

See Diagram Views for details on view definitions, available attributes and filter expressions (including common pitfalls).

Basic Usage

syside viz view <paths...>

By default, this renders all view definitions found in the model.

Note

This command renders diagram-producing views only. Grid views (table and matrix views) are handled by syside table export. Passing a grid view to --qualified-name results in an error.

Available Options

Option	Description
-h, --help	Display the help message with all available flags and short descriptions
-n, --qualified-name <QNAME>	Render only views at or under this qualified name (e.g. MyPackage::Diagrams, or a specific view). Repeatable. Defaults to all views in the model
-d, --depth <DEPTH>	Override each view’s traversal depth. -1 means infinite depth (default: -1)
-r, --rendering <TYPE>	Override each view’s render style: nested (default) or tree. Also accepts asNestedDiagram and asTreeDiagram. Overrides syside.toml [layout.render_style]
-t, --theme <THEME>	Diagram theme: light (default), dark, light_mono or dark_mono. Overrides syside.toml [style].theme
-z, --zoom-level <LEVEL>	Zoom level for rendering. Applicable only to PNG and JPEG output. Overrides syside.toml [render].zoom_level (default: 3.0)
-f, --format <FORMAT>	Override each view’s output format: svg, png or jpeg
-o, --output-dir <DIR>	Directory to write rendered diagrams into (default: ./output)
--expose <MODE>	How view filters interact with exposed elements (overrides syside.toml [expose].mode): subtree (default) drops filtered elements and their subtrees; promoted drops filtered elements but shows orphan descendants at the view frame; flat renders every exposed element as a flat sibling of the view frame
--config <FILE>	Path to a syside.toml configuration file
-i, --include <PATH>	Additional file, directory, or glob pattern to include. Repeatable
-e, --exclude <PATTERN>	Paths or glob patterns to exclude from file discovery. Repeatable

Usage Examples

The following examples extend the drone model with view definitions. See reference files for the full model.

DroneModelViews.sysml

package DroneModelViews {
     private import Views::asTreeDiagram;

    doc
    /* View definitions for the drone model. Each view lists elements
     * to render via `expose` statements and controls rendering options
     * through string attributes.
     */

    part def DroneSystemViews {
        view myNestedView {
            expose DroneModel::DroneSystem::myDrone::**;
            filter @ SysML::PartUsage;
        }

        view myTreeView {
            expose DroneModel::DroneSystem::myDrone::**;
            expose DroneModel::DroneSystem::someoneElsesDrone::**;
            filter @ SysML::PartUsage;

            attribute depth = 3;
            attribute fileName = "tree";
            render asTreeDiagram;
        }

        view myTreeView_Zoom2 {
            expose DroneModel::DroneSystem::myDrone::**;
            expose DroneModel::DroneSystem::someoneElsesDrone::**;
            filter @ SysML::PartUsage;

            // depth defaults to 1
            attribute depth = 2;

            // fileName defaults to "diagram-{viewName}.{fileType}"
            attribute fileName = "tree-zoom";

            // fileType defaults to "SVG"
            attribute fileType = "PNG";


            // zoomLevel defaults to "3.0"
            attribute zoomLevel = 2.0;

            // omitting render defaults to nested diagram
            render asTreeDiagram;
        }
    }
}

• Render all views in the model:

  syside viz view drone-model/ --output-dir views_all
  

  

• Render a specific view by qualified name:

  syside viz view drone-model/ --qualified-name "DroneModelViews::DroneSystemViews::myNestedView" --output-dir views_myNestedView
  

  

CI/CD Integration

Generate diagrams in a CI pipeline:

# Render all views
syside viz view models/ --output-dir artifacts/diagrams

# Render a specific element
syside viz element models/ --qualified-name "MySystem::TopLevel" \
    --output-file artifacts/diagrams/top-level.svg

---

Reference Files

Download Drone Model (ZIP)

Table command Labs

Export command

Export grid views defined in the SysML v2 model as CSV files.

Basic Usage

Pass one or more model files or directories to export all defined grid views into the output/ directory:

syside table export <paths...>

• <paths...> - one or more .sysml / .kerml files or directories (searched recursively)

Note

This command exports grid views (table and matrix views) only. Other view definitions are handled by syside viz view. Passing a non-grid view to --qualified-name results in an error.

Available Options

Option	Description
-h, --help	Display the help message with all available flags and short descriptions
-c, --config <CONFIG>	Path to a syside.toml configuration file. If not specified, the config is discovered by walking upward from the current directory. Config values for include and exclude are used as fallbacks when the corresponding CLI flags are not provided
-i, --include <INCLUDE>	Additional paths to include (e.g. external libraries). These are additional root paths merged with positional arguments for file discovery.
-e, --exclude <EXCLUDE>	Paths or glob patterns to exclude from file discovery. Matching files are removed from the result.
-n, --qualified-name <QUALIFIED_NAME>	Qualified names of the views to export. Defaults to all table and matrix views in the model
-o, --output-dir <OUTPUT_DIR>	Save the CSV files to the given directory. Defaults to ./output
--bom	Prepend a Byte Order Mark (BOM) to the CSV file to ensure Microsoft Excel correctly detects the UTF-8 encoding and displays special characters properly.

Note

In SysML v2, element names can contain spaces and special characters (e.g. 'Flight Controller v2' or 'Motor "Type A"'). When passing qualified names that contain such names, make sure to quote or escape them appropriately for your shell. For example, names with spaces should be wrapped in double quotes:

syside table export -n "DroneModel::'My Table View'" drone-model/

Alternatively, use simple names without spaces or special characters.