Viz command

Generates SysML v2 diagrams from models. Generate diagrams from CLI covers the workflows and examples.

Diagram generation can be further configured using the syside.toml file. See Diagram settings 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 Configure 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 / .kerml 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 the extension)
-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 Configure diagram views for defining views and controlling how they render.

Basic usage

syside viz view <paths...>

• <paths...> - one or more .sysml / .kerml 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 the extension)
-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 due to errors in the model, files that fail to load, or an internal error
2	Command-line usage error, such as an unknown option or a missing argument
3	Configuration error, configuration file cannot be read
4	Nothing to draw. At least one requested diagram matched no elements, so no file was written for it

Changed in version 0.11.0: A diagram with nothing to draw exits with 4. Before, it exited with 0 and wrote an empty file.

An invalid [viz] setting no longer exits with 2; it falls back to its default with a warning (see Diagram settings).