Skip to content

Command line tools

Sen comes with a command line application (called sen) to help you perform some actions following the approach taken by git.

The best way to familiarize yourself with all the commands and the available options is to do --help, starting with sen --help.

Welcome to sen

Usage: sen [OPTIONS] [SUBCOMMAND]

Options:
  -h,--help    Print this help message and exit
  --version    Display program version information and exit

Subcommands:
  run          Run a sen kernel
  generate     Generate code (mainly used by build systems)
  archive      Inspect archives
  package      Create or manipulate sen packages
  file-to-array
               Simple utility to convert a file to a C++ array
  term         Shortcut to run the sen term stand-alone
  shell        Shortcut to run the sen shell stand-alone
  explorer     Shortcut to run the sen explorer stand-alone
  web-explorer Shortcut to run the sen web-explorer stand-alone
  replay       Shortcut to run the sen replay stand-alone
  rshell       Shortcut to connect to a remote sen shell

For help on specific commands run 'sen <command> --help'

You can also get help about the specific sub-commands.

For example:

sen command line examples
# open a sen explorer window
sen explorer

# open a sen terminal on the current terminal
sen term

# open the older sen shell, which will be deprecated in 0.8.0
sen shell

# connect to a remote sen application on localhost:8094
sen rshell localhost:8094

# starts a replay of an archive
sen replay my_archive

# runs a sen kernel from a configuration file
sen run my_config.yaml

Run

sen run
Run a sen kernel

Usage: sen run [OPTIONS] [config]

Positionals:
  config TEXT:PATH(existing)       Configuration file

Options:
  -h,--help                        Print this help message and exit
  --preset TEXT:{shell,term,replay,explorer,web-explorer}
                                   Preset name
  --no-browser                     With --preset web-explorer: don't auto-open the URL in a browser
  --stopped                        With --preset replay: start paused
  --start-stop Excludes: --print-network-footprint
                                   Stop execution after all components are running
  --print-config Excludes: --print-network-footprint
                                   Print the configuration that will be used


Network footprint:
  --print-network-footprint Excludes: --start-stop --print-config
                                   Print the offline footprint and exit
  --bus TEXT Needs: --print-network-footprint
                                   Include a session.bus; repeat to include more
  --bus-file TEXT:FILE Needs: --print-network-footprint
                                   Read one session.bus per line; # starts a comment
  --format TEXT:{text,json} [text]  Needs: --print-network-footprint
                                   Set output format to readable text or json

The configuration file uses YAML. Its sections, every key the kernel understands, environment-variable substitution and the include merging rules are documented in The configuration file, which is the reference for the format.

A short example, so this page stands on its own:

a minimal configuration
load:
  - name: term
    group: 2
    open: [ local.counters ]

build:
  - name: counterComponent
    group: 3
    freqHz: 2
    imports: [ my_counter ]
    objects:
      - name: myCounter
        class: my_counter.CounterImpl
        bus: local.counters
        step: 5

Offline network footprint

Use --print-network-footprint to inspect the network addresses and ports that one process is expected to use without running the application. Sen configures and preloads the components, builds the report and exits before starting the application. The configuration must load the Ether component, which provides the report.

sen run config.yaml --print-network-footprint

The report includes the non-local buses declared in the process configuration. Since Sen doesn't start the application when generating the offline report, it cannot discover buses that the application would create at runtime. To include one of these buses, specify its session.bus address using --bus <session.bus>:

sen run config.yaml --print-network-footprint --bus session.one --bus session.two

As an alternative, you can declare the buses in a file and pass it with --bus-file. The file accepts one session.bus per line and # starts a comment. --bus-file can also be repeated to add more files.

buses.txt
# Buses
session.one
session.two  # Inline comment

sen run config.yaml --print-network-footprint --bus-file buses.txt

Sen combines the buses found in the configuration with those supplied through --bus or --bus-file and removes duplicates.

By default, Sen displays the report in a format designed to be read in the terminal. You can select a JSON output with --format json option and save it:

sen run config.yaml --print-network-footprint --format json > footprint.json

When JSON output is selected, Sen writes only the JSON document to standard output, which is the stream redirected by > footprint.json in the example above. Diagnostic and error messages are written to standard error instead, so they do not make the saved JSON invalid.

Runtime network footprint

The offline report is built before the application starts, so it cannot know the buses the application creates while running, nor the ports the operating system hands out for ephemeral bindings. Ask a running process instead. getRuntimeNetworkFootprint() on its kernel object returns the buses it has open and the ports it has bound. Use it to check a deployed process against what its configuration asked for.

Code generator

sen generate is a thin command-line front-end over the sen::gen library, which implements the underlying generators.

sen generate
sen code generator

Usage: sen generate [OPTIONS] SUBCOMMAND

Options:
  -h,--help                        Print this help message and exit
  --expect-failure                 Expect a failure in the generation process (for testing purposes)

Subcommands:
  cpp                              Generate C++ code
  uml                              Generate UML diagrams
  py                               Generate Python dataclasses
  mkdocs                           Generate MkDocs documentation
  html                             Generate a browsable reference for the data model
  json                             Generate JSON schemas
  ts                               Generate per-input TypeScript modules + a barrel from STL inputs
  typst                            Generate a typesettable reference for the data model

For help on specific commands run 'sen generate <command> --help'

C++

sen generate cpp
Generate C++ code
Usage: sen generate cpp [OPTIONS] SUBCOMMAND

Options:
  -h,--help                        Print this help message and exit
  -r,--recursive BOOLEAN           Recursively generate imported packages
  --public-symbols                 Make generated classes public

Subcommands:
  stl                              Process STL files
  fom                              Process HLA FOM files
  exports                          Generate the export symbols file for a sen STL package

C++ from STL

sen generate cpp stl
Process STL files
Usage: sen generate cpp stl [OPTIONS] stl_files...

Positionals:
  stl_files TEXT:FILE ... REQUIRED STL files

Options:
  -h,--help                        Print this help message and exit
  -i,--import TEXT ...             Paths where other STL files can be found
  --depfile TEXT                   Write the files read to this make-style depfile
  -b,--base-path,--base_path TEXT  Base path for including generated files
  -s,--settings TEXT:FILE          Code generation settings file

C++ from HLA FOMs

sen generate cpp fom
Process HLA FOM files
Usage: sen generate cpp fom [OPTIONS]

Options:
  -h,--help                        Print this help message and exit
  -m,--mappings TEXT:FILE ...      XML defining custom mappings between sen and HLA
  -d,--directories TEXT:DIR ... REQUIRED
                                   Directories containing FOM XML files
  -e,--extensions TEXT:PATH(existing) ...
                                   XML files, or directories of them, adding members to types the FOM declares
  -s,--settings TEXT:FILE          Code generation settings file

C++ exports

sen generate cpp exports
Generate the export symbols file for a sen STL package
Usage: sen generate cpp exports [OPTIONS]

Options:
  -h,--help                        Print this help message and exit
  -p,--package TEXT                Name of the package to create the exports for
  -f,--file TEXT ...               Name of the STL file containing types
  -d,--depends TEXT ...            Names of the packages we depend on
  -i,--implements TEXT ...         Names of types implemented in this package

UML

Works the same way as C++, but with slightly different options.

sen generate uml
Generate UML diagrams
Usage: sen generate uml [OPTIONS] SUBCOMMAND

Options:
  -h,--help                        Print this help message and exit

Subcommands:
  stl                              Process STL files
  fom                              Process HLA FOM files

UML from STL

sen generate uml stl
Process STL files
Usage: sen generate uml stl [OPTIONS] stl_files...

Positionals:
  stl_files TEXT:FILE ... REQUIRED STL files

Options:
  -h,--help                        Print this help message and exit
  -i,--import TEXT ...             Paths where other STL files can be found
  --depfile TEXT                   Write the files read to this make-style depfile
  -b,--base-path,--base_path TEXT  Base path for including generated files
  -s,--settings TEXT:FILE          Code generation settings file
  -o,--output TEXT                 Output PlantUML file
  --only-classes Excludes: --only-types --no-enumerators
                                   Only generate class diagrams
  --only-types Excludes: --only-classes
                                   Only generate diagrams for basic types
  --no-enumerators Excludes: --only-classes
                                   Do not generate enumerations

UML from HLA FOMs

sen generate uml fom
Process HLA FOM files
Usage: sen generate uml fom [OPTIONS]

Options:
  -h,--help                        Print this help message and exit
  -m,--mappings TEXT:FILE ...      XML defining custom mappings between sen and HLA
  -d,--directories TEXT:DIR ... REQUIRED
                                   Directories containing FOM XML files
  -e,--extensions TEXT:PATH(existing) ...
                                   XML files, or directories of them, adding members to types the FOM declares
  -s,--settings TEXT:FILE          Code generation settings file
  -o,--output TEXT                 Output PlantUML file
  --only-classes Excludes: --only-types --no-enumerators
                                   Only generate class diagrams
  --only-types Excludes: --only-classes
                                   Only generate diagrams for basic types
  --no-enumerators Excludes: --only-classes
                                   Do not generate enumerations

MKDocs markdown

Works the same way as C++, but with slightly different options.

sen generate mkdocs
Generate MkDocs documentation
Usage: sen generate mkdocs [OPTIONS] SUBCOMMAND

Options:
  -h,--help                        Print this help message and exit

Subcommands:
  stl                              Process STL files
  fom                              Process HLA FOM files

MKDocs from STL

sen generate mkdocs stl
Process STL files
Usage: sen generate mkdocs stl [OPTIONS] stl_files...

Positionals:
  stl_files TEXT:FILE ... REQUIRED STL files

Options:
  -h,--help                        Print this help message and exit
  -i,--import TEXT ...             Paths where other STL files can be found
  --depfile TEXT                   Write the files read to this make-style depfile
  -b,--base-path,--base_path TEXT  Base path for including generated files
  -s,--settings TEXT:FILE          Code generation settings file
  -o,--output TEXT                 Output file
  -t,--title TEXT                  Document title

MKDocs from HLA FOMs

sen generate mkdocs fom
Process HLA FOM files
Usage: sen generate mkdocs fom [OPTIONS]

Options:
  -h,--help                        Print this help message and exit
  -m,--mappings TEXT:FILE ...      XML defining custom mappings between sen and HLA
  -d,--directories TEXT:DIR ... REQUIRED
                                   Directories containing FOM XML files
  -e,--extensions TEXT:PATH(existing) ...
                                   XML files, or directories of them, adding members to types the FOM declares
  -s,--settings TEXT:FILE          Code generation settings file
  -o,--output TEXT                 Output file
  -t,--title TEXT                  Document title

HTML reference

Renders the data model as a small web application: a tree, a search, and a page per type. It needs no server and no network, so the output opens straight from a file.

sen generate html
Generate a browsable reference for the data model
Usage: sen generate html [OPTIONS] SUBCOMMAND

Options:
  -h,--help                        Print this help message and exit

Subcommands:
  stl                              Process STL files
  fom                              Process HLA FOM files

HTML from STL

sen generate html stl
Process STL files
Usage: sen generate html stl [OPTIONS] stl_files...

Positionals:
  stl_files TEXT:FILE ... REQUIRED STL files

Options:
  -h,--help                        Print this help message and exit
  -i,--import TEXT ...             Paths where other STL files can be found
  --depfile TEXT                   Write the files read to this make-style depfile
  -b,--base-path,--base_path TEXT  Base path for including generated files
  -s,--settings TEXT:FILE          Code generation settings file
  -o,--output TEXT REQUIRED        Directory to write the reference into
  -t,--title TEXT                  Name of the model, shown on screen

HTML from HLA FOMs

sen generate html fom
Process HLA FOM files
Usage: sen generate html fom [OPTIONS]

Options:
  -h,--help                        Print this help message and exit
  -m,--mappings TEXT:FILE ...      XML defining custom mappings between sen and HLA
  -d,--directories TEXT:DIR ... REQUIRED
                                   Directories containing FOM XML files
  -e,--extensions TEXT:PATH(existing) ...
                                   XML files, or directories of them, adding members to types the FOM declares
  -s,--settings TEXT:FILE          Code generation settings file
  -o,--output TEXT REQUIRED        Directory to write the reference into
  -t,--title TEXT                  Name of the model, shown on screen

Typeset reference (PDF)

Renders the data model as a Typst document, in the shape of an interface control document: an overview, a class hierarchy, a table per type and an index. It writes Typst source rather than a PDF, so producing one is a separate step with the Typst compiler.

What the document contains, and what it looks like, is set by the options rather than inferred from the model.

sen generate typst
Generate a typesettable reference for the data model
Usage: sen generate typst [OPTIONS] SUBCOMMAND

Options:
  -h,--help                        Print this help message and exit

Subcommands:
  stl                              Process STL files
  fom                              Process HLA FOM files

Typst from STL

sen generate typst stl
Process STL files
Usage: sen generate typst stl [OPTIONS] stl_files...

Positionals:
  stl_files TEXT:FILE ... REQUIRED STL files

Options:
  -h,--help                        Print this help message and exit
  -i,--import TEXT ...             Paths where other STL files can be found
  --depfile TEXT                   Write the files read to this make-style depfile
  -b,--base-path,--base_path TEXT  Base path for including generated files
  -s,--settings TEXT:FILE          Code generation settings file
  -o,--output TEXT REQUIRED        Directory to write the document into
  -t,--title TEXT                  Name of the model, shown on the running header
  --include-package TEXT ...       Only document this package; repeatable
  --exclude-package TEXT ...       Leave this package out; repeatable
  --no-overview{false}             Drop the model overview
  --no-hierarchy{false}            Drop the class hierarchy
  --no-summaries{false}            Drop the per-package summary lists
  --no-index{false}                Drop the index of every type
  --no-used-by{false}              Drop the list of what refers to each type
  --no-flag-legend{false}          Drop the explanation of the property flags
  --no-built-ins{false}            Drop the list of the language's built-in types
  --front-matter TEXT:FILE         Typst file to include before the reference, as a title page
  --before-reference TEXT:FILE     Typst file to include after the front matter
  --after-reference TEXT:FILE      Typst file to include after the reference
  --style TEXT:FILE                Typst file defining the look, replacing the one shipped

Typst from HLA FOMs

sen generate typst fom
Process HLA FOM files
Usage: sen generate typst fom [OPTIONS]

Options:
  -h,--help                        Print this help message and exit
  -m,--mappings TEXT:FILE ...      XML defining custom mappings between sen and HLA
  -d,--directories TEXT:DIR ... REQUIRED
                                   Directories containing FOM XML files
  -e,--extensions TEXT:PATH(existing) ...
                                   XML files, or directories of them, adding members to types the FOM declares
  -s,--settings TEXT:FILE          Code generation settings file
  -o,--output TEXT REQUIRED        Directory to write the document into
  -t,--title TEXT                  Name of the model, shown on the running header
  --include-package TEXT ...       Only document this package; repeatable
  --exclude-package TEXT ...       Leave this package out; repeatable
  --no-overview{false}             Drop the model overview
  --no-hierarchy{false}            Drop the class hierarchy
  --no-summaries{false}            Drop the per-package summary lists
  --no-index{false}                Drop the index of every type
  --no-used-by{false}              Drop the list of what refers to each type
  --no-flag-legend{false}          Drop the explanation of the property flags
  --no-built-ins{false}            Drop the list of the language's built-in types
  --front-matter TEXT:FILE         Typst file to include before the reference, as a title page
  --before-reference TEXT:FILE     Typst file to include after the front matter
  --after-reference TEXT:FILE      Typst file to include after the reference
  --style TEXT:FILE                Typst file defining the look, replacing the one shipped

JSON schemas

Generates json schemas from a Sen data model.

JSON schemas for Sen components from STL

Process STL files
Usage: sen generate json component stl [OPTIONS] stl_files...

Positionals:
  stl_files TEXT:FILE ... REQUIRED STL files

Options:
  -h,--help                        Print this help message and exit
  -i,--import TEXT ...             Paths where other STL files can be found
  --depfile TEXT                   Write the files read to this make-style depfile
  -b,--base-path,--base_path TEXT  Base path for including generated files
  -s,--settings TEXT:FILE          Code generation settings file
  -o,--output TEXT                 Output file
  -n,--name TEXT                   Name of the component

JSON schemas for Sen components from HLA FOMs

Process HLA FOM files
Usage: sen generate json component fom [OPTIONS]

Options:
  -h,--help                        Print this help message and exit
  -m,--mappings TEXT:FILE ...      XML defining custom mappings between sen and HLA
  -d,--directories TEXT:DIR ... REQUIRED
                                   Directories containing FOM XML files
  -e,--extensions TEXT:PATH(existing) ...
                                   XML files, or directories of them, adding members to types the FOM declares
  -s,--settings TEXT:FILE          Code generation settings file
  -o,--output TEXT                 Output file
  -n,--name TEXT                   Name of the component

JSON schemas for Sen packages from STL

Process STL files
Usage: sen generate json package stl [OPTIONS] stl_files...

Positionals:
  stl_files TEXT:FILE ... REQUIRED STL files

Options:
  -h,--help                        Print this help message and exit
  -i,--import TEXT ...             Paths where other STL files can be found
  --depfile TEXT                   Write the files read to this make-style depfile
  -b,--base-path,--base_path TEXT  Base path for including generated files
  -s,--settings TEXT:FILE          Code generation settings file
  -o,--output TEXT                 Output file
  -c,--class TEXT ...              Classes implemented by the user

JSON schemas for Sen packages from HLA FOMs

Process HLA FOM files
Usage: sen generate json package fom [OPTIONS]

Options:
  -h,--help                        Print this help message and exit
  -m,--mappings TEXT:FILE ...      XML defining custom mappings between sen and HLA
  -d,--directories TEXT:DIR ... REQUIRED
                                   Directories containing FOM XML files
  -e,--extensions TEXT:PATH(existing) ...
                                   XML files, or directories of them, adding members to types the FOM declares
  -s,--settings TEXT:FILE          Code generation settings file
  -o,--output TEXT                 Output file
  -c,--class TEXT ...              Classes implemented by the user

Combine multiple JSON schemas to create a kernel configuration schema

Generate JSON schemas for sen configurations
Usage: sen generate json schema [OPTIONS] schema_files...

Positionals:
  schema_files TEXT:FILE ... REQUIRED
                                   JSON schema files

Options:
  -h,--help                        Print this help message and exit
  -o,--output TEXT                 Output file

Python

sen generate py
Generate Python dataclasses
Usage: sen generate py [OPTIONS] SUBCOMMAND

Options:
  -h,--help                        Print this help message and exit

Subcommands:
  stl                              Process STL files
  fom                              Process HLA FOM files

Python from STL

sen generate py stl
Process STL files
Usage: sen generate py stl [OPTIONS] stl_files...

Positionals:
  stl_files TEXT:FILE ... REQUIRED STL files

Options:
  -h,--help                        Print this help message and exit
  -i,--import TEXT ...             Paths where other STL files can be found
  --depfile TEXT                   Write the files read to this make-style depfile
  -b,--base-path,--base_path TEXT  Base path for including generated files
  -s,--settings TEXT:FILE          Code generation settings file

Python from HLA FOMs

sen generate py fom
Process HLA FOM files
Usage: sen generate py fom [OPTIONS]

Options:
  -h,--help                        Print this help message and exit
  -m,--mappings TEXT:FILE ...      XML defining custom mappings between sen and HLA
  -d,--directories TEXT:DIR ... REQUIRED
                                   Directories containing FOM XML files
  -e,--extensions TEXT:PATH(existing) ...
                                   XML files, or directories of them, adding members to types the FOM declares
  -s,--settings TEXT:FILE          Code generation settings file

TypeScript

TypeScript generation reads STL only; there is no FOM subcommand today.

sen generate ts
Generate per-input TypeScript modules + a barrel from STL inputs
Usage: sen generate ts [OPTIONS] SUBCOMMAND

Options:
  -h,--help                        Print this help message and exit

Subcommands:
  stl                              Process STL files

TypeScript from STL

sen generate ts stl
Process STL files
Usage: sen generate ts stl [OPTIONS] stl_files...

Positionals:
  stl_files TEXT:FILE ... REQUIRED STL files

Options:
  -h,--help                        Print this help message and exit
  -i,--import TEXT ...             Paths where other STL files can be found
  --depfile TEXT                   Write the files read to this make-style depfile
  -b,--base-path,--base_path TEXT  Base path for including generated files
  -s,--settings TEXT:FILE          Code generation settings file
  -d,--out-dir TEXT REQUIRED       Output directory for the generated .ts files

Archiving utility

Helps you interact with archives. "Archive" and "recording" are the same thing here: the recorder writes a recording, and sen archive is the command that inspects one.

sen archive
Recording inspection and manipulation utility

Usage: sen archive [OPTIONS] [SUBCOMMAND]

Options:
  -h,--help Print this help message and exit

Subcommands:
  info      Print basic information about an archive
  indexed   Print basic info about the indexed objects
  merge     combine multiple archives into one

For help on specific commands run 'sen archive <command> --help'

Basic information

sen archive info
Print basic information about an archive
Usage: sen archive info [OPTIONS] archive_path

Positionals:
  archive_path TEXT:DIR REQUIRED
            Archive path

Options:
  -h,--help Print this help message and exit

Indexed objects

sen archive indexed
Print basic info about the indexed objects
Usage: sen archive indexed [OPTIONS] archive_path

Positionals:
  archive_path TEXT:DIR REQUIRED
            Archive path

Options:
  -h,--help Print this help message and exit

Recording merger

sen archive merge
combine multiple archives into one
Usage: sen archive merge [OPTIONS] input_paths...

Positionals:
  input_paths TEXT:DIR ... REQUIRED
            Recording path

Options:
  -h,--help Print this help message and exit
  -o,--output TEXT
            Output recording path
  --mode TEXT:{normal,zero,offset}
            Merge mode
  --offset FLOAT ...
            offset for each input recording (in seconds)
  --force   Replace a recording archive already present at the output path

Packaging utility

sen package
Create or manipulate sen packages

Usage: sen package [OPTIONS] [SUBCOMMAND]

Options:
  -h,--help                        Print this help message and exit

Subcommands:
  init                             Start a package working area
  init-component                   Start a component working area

Package skeleton creation

sen package init
Start a package working area
Usage: sen package init [OPTIONS] path

Positionals:
  path TEXT REQUIRED               Path

Options:
  -h,--help                        Print this help message and exit
  --class TEXT REQUIRED            Name of a class

Component skeleton creation

sen package init-component
Start a component working area
Usage: sen package init-component [OPTIONS] path

Positionals:
  path TEXT REQUIRED               Path

Options:
  -h,--help                        Print this help message and exit
  --with-config Excludes: --full   Include STL and template for configuration
  --full Excludes: --with-config   Include configuration and implementation of all methods

File to array utility

sen file-to-array
Simple utility to convert a file to a C++ array
Usage: sen file-to-array [OPTIONS]

Options:
  -h,--help    Print this help message and exit
  -i TEXT:FILE REQUIRED
               File to read
  -o TEXT REQUIRED
               File to write
  -v TEXT REQUIRED
               Name of the variable that will hold the data