Configure Modeler CLI

Modeler CLI uses the same syside.toml configuration as Modeler. The configuration file can be provided explicitly via --config <FILE> or inferred through Config file discovery.

Config file discovery

A single syside.toml serves an entire project: every command run in or below its directory finds the file automatically. The CLI discovers and merges configuration files exactly as the extension does, so Configure Modeler is the authoritative account of the global, project, and user files and of how paths in them resolve.

Two things are specific to the CLI:

  • --config <FILE> takes precedence over every discovered file, and disables discovery entirely.

  • Without --config, the search runs upward from the current directory, up to and including the first directory containing .git or sysand-lock.toml.

Shared settings

The check and format commands behave exactly as Syside Modeler and read the same settings (e.g., [format] and [lint]). See Settings in syside.toml for details.

Visualization settings

All visualization settings live under [viz]. Command-line flags override configuration values. See viz command for flag descriptions and which setting each flag overrides.

An unknown setting or a value of the wrong type falls back to its default with a warning.

Some settings are set separately for each view kind. <kind> in a setting name stands for one of the following: general, interconnection, action_flow, state_transition, or sequence.

Group

Setting

Default

Meaning

[viz.style]

theme

light

Base color theme

group.<name>

Custom color groups

[viz.layout]

render_style.<kind>

nested

Layout style per view kind

view.default

general

View kind for viz element

[viz.expose]

mode

subtree

Filtered-element mapping strategy

[viz.compartments]

max_entries

-1

Per-compartment row cap

show_inherited_rows

true

Inherited compartment rows

show_annotation_rows

true

Annotation compartment rows

[viz.labels]

show_fork_join_labels

true

Labels on fork and join bars

show_decide_merge_labels

true

Labels on decision and merge diamonds

[viz.filters.<kind>]

show_node_heritage_edges

true

Specialization edges to node ancestors

show_port_heritage_edges

false

Specialization edges to port ancestors

show_inherited_nodes

true

Inherited-member nodes

show_attributes_as

Attribute rendering

show_connection_elaborations

true

Connections with contents as nodes

[viz.render]

zoom_level

3.0

Raster scale multiplier

max_raster_memory_mb

256

Memory ceiling per raster image

Themes

Diagrams can be styled using four built-in themes: light, dark, light_mono, and dark_mono. Each option can be selected via viz.style.theme setting or the -t/--theme flag.

Custom colors

Element colors can be further customized using style groups. Group colors apply on top of the selected theme and always win. Each [viz.style.group.<name>] entry colors the elements it selects, either by element type or by the metadata they carry, e.g.

[viz.style.group.part_usage]
members      = ["PartUsage"]
fill_header  = "#88b7e3ff"
fill_body    = "#f7f9ffff"
text_keyword = "#1f4373ff"

[viz.style.group.flight_critical]
members      = ["#FlightCritical"]
fill_header  = "#e08080ff"
stroke       = "#7a1010ff"
stroke_edge  = "#7a1010ff"

Rules:

  • members is required and non-empty. An entry is either a SysML metaclass name (PartUsage, PartDefinition, ActionUsage, RequirementDefinition, etc.) or a # followed by a metadata definition name (see Select by metadata). A metaclass selects its own elements and those of every metaclass specializing it, so Usage selects every part, action and other usage

  • Each group sets one or more color settings. Every setting paints one drawn form, so an element drawn as a box, a line, or a boundary element (e.g. port or parameter) takes only the settings for that form:

    Form

    Setting

    Colors

    Node

    fill_header

    Node header background

    Node

    fill_body

    Node body background

    Node

    stroke

    Node border and compartment separators

    Node

    text_primary

    Node name and compartment rows

    Node

    text_keyword

    Node header keywords, compartment and annotation titles

    Edge

    stroke_edge

    Edge lines, end markers, n-ary legs

    Edge

    text_edge

    Edge label text

    Port

    fill_port

    Boundary element background

    Port

    stroke_port

    Boundary element outline and direction arrow

    Port

    text_port

    Boundary element label text

  • When several groups select the same element, the closest match decides each color setting it sets (see Group precedence)

  • Group names are free-form and only serve readability

  • Groups cannot be nested inside each other

Colors use hexadecimal notation: #rrggbb or #rrggbbaa (where aa is transparency).

Settings follow the drawn form: a port drawn as a boundary element takes the port settings, and the same port drawn as a node takes the node settings.

Select by metadata New in v0.11.0

A # prefix in members selects every element that carries the named metadata, in any of the forms the language offers:

#Safety part def Tagged;
part body { @Safety; }
part keyword { metadata Safety; }

The name after # is the metadata definition’s name (or short name), as written in the model:

  • #Safety matches every definition named Safety, in any package

  • #Fmea::Safety matches the one in Fmea

  • #'hazard class' keeps the quotes a name with spaces needs

Selection follows the language rules for metadata. Metadata is not inherited, so a part typed by a tagged definition, or specializing a tagged one, does not carry the tag and is not selected. Metadata typed by a specialization of Safety is Safety metadata as well, so #Safety selects it.

members may mix the two selector kinds; the group then colors the union.

Select by metadata attribute New in v0.11.0

conditions limits a # entry to elements whose metadata attributes hold the given values. Two groups on the same metadata, one with conditions and one without, match equally well, so the later group wins the settings both set:

[viz.style.group.risk]
members      = ["#Risk"]
fill_header  = "#f3cc7aff"

[viz.style.group.risk_high]
members      = ["#Risk"]
conditions   = { technicalRisk = "high" }
fill_header  = "#c0392bff"
fill_body    = "#fbe9e7ff"

A part tagged @Risk { technicalRisk = RiskLevelEnum::high; } takes the second group, any other @Risk part the first.

  • Several conditions must all hold

  • A string matches a string literal, or an enumeration literal by its name, bare or qualified ("high" and "RiskLevelEnum::high" both match RiskLevelEnum::high)

  • The value must be a literal written in the tag itself. A computed value or the default from the metadata definition does not match

  • conditions applies to # entries only; a group that also lists metaclass names is rejected

conditions follows view filters: a group with conditions = { technicalRisk = "high" } selects the same elements a filter keeping (as Risk).technicalRisk == RiskLevelEnum::high does.

Group precedence

When several groups select the same element, the closest match decides each setting, whatever the declaration order. A metadata tag is closer than a metaclass, and a metaclass is closer than the ones it specializes, so PartUsage beats Usage:

[viz.style.group.parts]
members     = ["PartUsage", "PartDefinition"]
fill_header = "#88b7e3ff"

[viz.style.group.actions]
members     = ["ActionUsage", "ActionDefinition"]
fill_header = "#80d6a7ff"

[viz.style.group.everything_else]
members     = ["Usage", "Definition"]
fill_header = "#d9d9dcff"
stroke      = "#2c2c2eff"

Parts take fill_header from parts, actions from actions, and every other usage and definition from everything_else. All of them take stroke from everything_else, the only group that sets it. Declaring the broad group last does not let it win fill_header: PartUsage is a nearer match for a part than Usage is.

Which group wins is decided per element:

  • A group that selects by metadata (#Safety) beats a group that selects by metaclass (PartUsage), wherever the two are declared

  • Among groups of one kind, the nearer match wins. PartUsage beats Usage for a part, and with metadata def Critical :> Safety;, #Critical beats #Safety for an element tagged @Critical

  • Groups that match equally well apply in declaration order, later wins

  • Each color setting is decided on its own, so a group that sets only stroke never takes fill_header away from another group

  • conditions decide whether a group matches at all. They do not make it more specific

Changed in version 0.11.0: Members now match through specialization, so Usage selects every part, action and other usage, and the closest matching group decides each setting. Previously a member matched only its exact metaclass, and the last declared group decided.

Settings reference

viz.style.theme

Base color theme for all diagrams.

Values: light | dark | light_mono | dark_mono

Default: light

[viz.style]
theme = "dark"

viz.layout.render_style.<kind>

Default layout style, set separately for each view kind.

For viz view, a view’s render keyword and the -r flag take precedence over this setting.

Values: nested | tree

Default: nested

[viz.layout.render_style]
general = "tree"

viz.layout.view.default

View kind used by viz element when --view is not passed.

Values: general | interconnection | action_flow | state_transition | sequence

Default: general

[viz.layout.view]
default = "interconnection"

viz.expose.mode

How view filters interact with exposed elements. See expose modes for the semantics.

Values: subtree | promoted | flat

Default: subtree

[viz.expose]
mode = "promoted"

viz.compartments.max_entries

Per-compartment row cap: -1 shows all rows, 0 hides feature compartments, N shows the first N rows. Annotation compartments are unaffected by this setting.

Values: -1 | 0 | N

Default: -1

[viz.compartments]
max_entries = 5

viz.compartments.show_inherited_rows

Hides inherited (^) compartment rows when set to false.

Values: true | false

Default: true

[viz.compartments]
show_inherited_rows = false

viz.compartments.show_annotation_rows

Hides annotation (documentation and metadata) compartment rows when set to false.

Values: true | false

Default: true

[viz.compartments]
show_annotation_rows = false

viz.labels.show_fork_join_labels

Hides fork and join bar name labels when set to false.

Values: true | false

Default: true

[viz.labels]
show_fork_join_labels = false

viz.labels.show_decide_merge_labels

Hides decision and merge element name labels when set to false.

Values: true | false

Default: true

[viz.labels]
show_decide_merge_labels = false

viz.filters.<kind>.show_node_heritage_edges

Draws specialization edges to node ancestors. Set separately for each view kind.

Values: true | false

Default: true

[viz.filters.general]
show_node_heritage_edges = false

viz.filters.<kind>.show_port_heritage_edges

Draws specialization edges to port ancestors. Set separately for each view kind.

Values: true | false

Default: false

[viz.filters.interconnection]
show_port_heritage_edges = true

viz.filters.<kind>.show_inherited_nodes

Shows inherited member nodes. Set separately for each view kind.

Values: true | false

Default: true

[viz.filters.general]
show_inherited_nodes = false

viz.filters.<kind>.show_attributes_as

Defines how attribute usages are rendered. By default, attributes are rendered as compartments in the nested layout and as nodes in the tree layout. Set separately for each view kind.

Values: nodes | compartments | hidden

Default: unset

[viz.filters.state_transition]
show_attributes_as = "hidden"

viz.filters.<kind>.show_connection_elaborations

New in v0.11.0

A connection that owns more than its ends, such as an attribute or a nested connection, is drawn as an edge plus a node for that content, joined by a dashed line. The node is the connection’s elaboration. Set to false to draw the connection as an edge. Set separately for each view kind.

Values: true | false

Default: true

[viz.filters.interconnection]
show_connection_elaborations = false

viz.render.zoom_level

Sets raster scale multiplier. Applies to PNG and JPEG output only.

Values: number greater than 0

Default: 3.0

[viz.render]
zoom_level = 1.5

viz.render.max_raster_memory_mb

Sets memory ceiling per rasterized image (MB). Oversized diagrams are automatically downscaled to fit.

Values: number greater than 0

Default: 256

[viz.render]
max_raster_memory_mb = 512