CLI Commands

Command	Description
check	Validate models for semantic errors and warnings
format	Format SysML v2 models according to a consistent style
rule	Look up Syside validation rules
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.

• Validate files matching a glob pattern

  syside check "models/**/*.sysml"
  

  Path arguments can be files, directories, or glob patterns (*, **, ?, {a,b}, [a-z]), mixed freely. Every syside command discovers files with the same rules.

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.

Rule Command

Prints the explanation for a given validation rule. Many check diagnostics carry a rule name (e.g. error (type-error)) that can be looked up with this command. Each rule’s documentation contains the languages the rule applies to, the specification passage it enforces, and annotated examples with fixes.

The full rule list is available at Validation Rules.

Basic Usage

• List all rules available in Syside:

  syside rule list
  

• Explain one or more rules by name:

  syside rule type-error
  

The explanation is printed as Markdown.

Available Options

Option	Description
-h, --help	Display the help message with all available flags and short descriptions
-a, --all	Explain all rules. Cannot be combined with rule names
-f, --format <VALUE>	Output format: json or text (default)

Viz Command Labs

Generates SysML v2 diagrams from models using Modeler CLI’s built-in visualization engine. See the Diagram Generation guide for workflows and examples.

Diagram generation can be further configured using the syside.toml file. See Configure Modeler CLI for the full settings reference.

Note

Diagram generation settings can be defined in multiple places. The order of precedence is listed below (highest wins):

1. Options passed on the command line

2. SysML attributes defined on the view (view command only). See Diagram Views

3. A configuration file: any TOML file passed with -c / --config, or a syside.toml discovered automatically

4. Built-in defaults

Element Command

Generates a diagram for model elements selected by qualified name, without requiring view definitions in the model.

Basic Usage

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

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

• --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; the file extension selects the format (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 the shell. For example, names with spaces should be wrapped in double quotes:

syside viz element models/ -n "MyPackage::'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, --name <NAME>	Qualified name of a root element to render (e.g. MyPackage::MyPartDef). Repeatable to render several roots into one diagram (default: the whole model)
-d, --depth <DEPTH>	How many levels of descendants to render. -1 means infinite depth (default: -1)
-r, --render <STYLE>	Render style: nested or tree. as_nested_diagram / asNestedDiagram and as_tree_diagram / asTreeDiagram are also accepted (default: viz.layout.render_style.<kind>, or nested)
-v, --view <VIEW>	SysML v2 view kind: general, interconnection, action_flow, state_transition or sequence (default: viz.layout.view.default, or general)
-t, --theme <THEME>	Diagram theme: light, dark, light_mono or dark_mono (default: viz.style.theme, or light)
-z, --zoom-level <LEVEL>	Zoom level for rendering. Applicable only to PNG and JPEG output (default: viz.render.zoom_level, or 3.0)
-o, --output-file <FILE>	Path to save the image. Format is determined by the extension. Supported formats: svg, png or jpeg (default: element.svg)
-c, --config <FILE>	Path to a configuration file (see Configure Modeler CLI)
-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

• Render one part definition to a PNG file:

  syside viz element drone-mission/ -n "DroneMission::Components::Drone" -o Drone.svg
  

  

• Render a subtree as a two-level decomposition tree:

  syside viz element drone-mission/ --render tree -n "DroneMission::Structure::MedicalQuadcopter::medkit" -d 2 -o Medkit_tree.svg
  

  

View Command

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

See the Diagram Views page for defining views and controlling how they render.

Basic Usage

syside viz view <paths...>

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

By default, this renders all views found in the model into the ./output directory. Each view is written as <fileName>.<format>, where fileName is the view’s fileName attribute. If the attribute is absent, the file is named diagram-<view name>.

Note

Anonymous (unnamed) views are skipped with a warning.

Available Options

Option	Description
-h, --help	Display the help message with all available flags and short descriptions
-n, --name <NAME>	Render only views at or under this qualified name (e.g. MyPackage::Diagrams, or a specific view). Repeatable (default: all views)
-d, --depth <DEPTH>	How many levels of descendants to render. -1 means infinite depth. Overrides the depth attribute (default: -1)
-r, --render <STYLE>	Render style: nested or tree. as_nested_diagram / asNestedDiagram and as_tree_diagram / asTreeDiagram are also accepted. Overrides the render keyword (default: viz.layout.render_style.<kind>, or nested)
-t, --theme <THEME>	Diagram theme: light, dark, light_mono or dark_mono (default: viz.style.theme, or light)
-z, --zoom-level <LEVEL>	Zoom level for rendering. Applicable only to PNG and JPEG output. Overrides the zoomLevel attribute (default: viz.render.zoom_level, or 3.0)
-f, --format <FORMAT>	Output format: svg, png or jpeg. Overrides the fileType attribute (default: svg)
-o, --output-dir <DIR>	Directory to write rendered diagrams into (default: ./output)
--expose <MODE>	How view filters interact with exposed elements: subtree, promoted or flat (see expose modes). Overrides the exposeMode attribute (default: viz.expose.mode, or subtree)
-c, --config <FILE>	Path to a configuration file (see Configure Modeler CLI)
-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

• Render all views as PNG files into a diagrams directory:

  syside viz view drone-mission/ -f png -o diagrams
  

• Render a single view by qualified name. The output file is named by the view’s fileName attribute:

  syside viz view drone-mission/ -f png -o diagrams -n "DroneMissionDiagrams::power_distribution"
  

  

Exit Codes

Viz element and view subcommands exit with the following codes:

Code	Meaning
0	Success
1	Failure: errors in the model, no matching element or views, a missing input path, an unsupported output extension, or an internal error
2	Invalid [viz] configuration setting or value

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 "MyPackage::'My Table View'" models/

Alternatively, use simple names without spaces or special characters.