Command-line reference

The package installs one console command, longeron. The nine subcommands map onto the Python API one-to-one, so anything the command line does, a script can do.

Subcommand	Does	Python equivalent
parse	syntax-check .sysml/.kerml sources	parse_file()
lint	validate a model and print diagnostics	validate()
export	serialize a model to JSON, SysML, KerML, or API JSON	to_json(), …
calc	invoke a calc def as a function	Interpreter.call
check	instantiate a part def and check its constraints	Interpreter.instantiate + check
run	execute an action def	Interpreter.run_action
simulate	simulate a state def	Interpreter.simulate
evidence	verify SourceEvidence citations, or set up LFS storage	verify(), init_lfs()
serve	serve a workspace over the Systems Modeling API	serve()

Model inputs and shared options

Every subcommand except parse takes a model input as its first argument. The input takes one of three forms:

• a .sysml file, which is parsed and built;

• a .json export, which is imported losslessly;

• a directory, from which every *.sysml file is loaded and merged (see Workspaces & caching).

The same subcommands share two options:

Option	Effect
--no-cache	Bypass the model cache and parse from source.
--stdlib	Add the vendored standard library to the loaded model, so library types resolve during execution.

Every subcommand also accepts --traceback (see Errors and exit codes).

--stdlib mutates the loaded model. lint does not need it: the validator consults the standard library through its resolver by default (see Validation), and library-package internals are never the subject of diagnostics, so --stdlib does not change what lint reports.

name=value arguments

calc, check, and run accept trailing name=value arguments. Each value is parsed as JSON when possible, and kept as a string otherwise. For example, capacity=5200 binds the number 5200, tested=true binds True, and label=alpha binds the string "alpha".

Errors and exit codes

Expected failures – a missing or unreadable file, a syntax error, an unknown qualified name, a malformed .json input, a missing optional extra – print a single error: ... line to stderr and exit 1, without a Python traceback:

$ longeron calc examples/deepscout Rotorcraft::Nope
error: Rotorcraft has no member 'Nope'

Pass --traceback (any subcommand) to re-raise the underlying exception with its full traceback. Genuinely unexpected errors – bugs – always show their traceback.

Code	Meaning
0	Success. For check: no constraint failed. For lint: no error-severity diagnostic.
1	lint found errors (with --strict, resolution warnings count as errors), check found a failed constraint, parse found no matching files in a directory or any file failed to parse, or an expected failure was reported (error: ... on stderr).
2	Command-line usage error (reported by argparse).
N	evidence verify exits with the count of drifted and lost citations.

longeron parse

parse syntax-checks a source file, or every source file under a directory, without building a model:

$ longeron parse examples/deepscout/aircraft.sysml
OK: examples/deepscout/aircraft.sysml parses as sysml

Option	Effect
--kerml	Force the KerML grammar. On a directory, check **/*.kerml instead of **/*.sysml.
--tree	Print the raw ANTLR parse tree for a single file.

The grammar is chosen from the file suffix unless --kerml forces it. In directory mode every file is reported – failures print as FAIL: lines with their syntax errors and do not stop the sweep; the exit code is 1 when any file failed.

Syntax errors are reported compactly: ANTLR’s expected-token dumps are rewritten (unexpected ';' (expected an expression) instead of a 20-token set listing), and each error echoes the offending source line with a ^ caret under the column. The verbatim ANTLR message stays available on SyntaxIssue.raw_message for grammar work.

KerML support is parse-and-validate only. The builder, and therefore every other subcommand, consumes SysML sources (see Grammar conformance).

longeron lint

lint validates a model and prints one line per diagnostic, then a summary line:

$ longeron lint demo.sysml
demo.sysml:3:5: error[duplicate-name] Demo::Wheel: name 'Wheel' is already used by another member of Demo
demo.sysml:5:9: warning[unresolved-reference] Demo::Vehicle::mass: typed by 'Reall' does not resolve
1 error(s), 1 warning(s)

The file:line:column prefix comes from parsing; models rebuilt from a .json export or from a warm model cache entry carry no source positions, so their diagnostics print without the prefix. Pass --no-cache to re-parse and get positions back.

Option	Effect
--strict	Strict mode: unresolved references and the other resolution failures become errors, and a bare import (no visibility prefix) warns (bare-import). See the two strict modes.
--strict-imports	Additionally warn (stdlib-implicit-name) when a bare standard-library name is used without an import.
--evidence-coverage	Additionally warn (unevidenced-value) on stated attribute values with no SourceEvidence citation. evidence-drift needs no flag. See the evidence guide.
--no-stdlib	Do not resolve names against the standard library. Every library reference then warns.

The Validation guide documents every diagnostic code, its severity, and how name resolution works.

longeron export

export serializes a model and writes it to stdout, or to --output:

$ longeron export examples/deepscout --format sysml       # regenerated text
$ longeron export model.json --format sysml               # JSON in, SysML out
$ longeron export models/ --format json -o merged.json    # directory, merged

Option	Effect
--format {json,sysml,kerml,api}	Output format (default json). api emits OMG Systems Modeling API records and needs the ecore extra.
--no-derived	With --format api: omit the derived source/target relationship endpoint arrays (emitted by default; pilot-API consumers need them for navigation).
-o, --output PATH	Write to a file instead of stdout.

JSON round-trips are lossless. SysML output re-parses to the same model. KerML is a one-way projection. See the interchange reference.

longeron calc

calc invokes a calc def as a function and prints the result:

$ longeron calc examples/deepscout DeepScout::HoverTime capacity=5200
23.28358208955224

The positional name is the qualified name of the calc. Trailing name=value pairs bind its in parameters.

longeron check

check instantiates a part def, prints the instance as JSON, and then checks every constraint and requirement against it:

$ longeron check examples/deepscout Rotorcraft::QuadCopter payloadMass=0.9
{ ... the instance, as JSON ... }
[FAIL] assert takeoffMassLimit: totalMass <= maxTakeoffMass
[PASS] assert canHover: 4.0 * thrustPerRotor > totalMass * 9.81
$ echo $?
1

Each verdict line reads [PASS], [FAIL], or [SKIP] (a requirement whose assumptions do not hold is skipped). Trailing name=value pairs override attribute values, which makes check a one-line what-if tool. If any constraint fails, the command exits 1.

longeron run

run executes an action def and prints the step trace, the outputs, and any sent payloads:

$ longeron run examples/deepscout DeepScout::PlanBattery distanceKm=20
  assign requiredWh := 7.4
  ...
outputs: {"requiredWh": 7.4, ...}

Option	Effect
--events NAMES	Comma-separated event names, delivered to accept steps in order.

Trailing name=value pairs bind the action’s in parameters.

longeron simulate

simulate starts a state def, feeds it events, and prints the transition trace:

$ longeron simulate examples/deepscout DeepScout::FlightStates --events launch,airborne
  idle --launch--> takingOff
  takingOff --airborne--> flying
final state: flying

Option	Effect
--events NAMES	Comma-separated event names, sent in order.

Events the machine cannot consume are reported on an ignored events: line. The --events list carries event names only. To advance the simulation clock for accept after/accept at triggers, use the Python API, where a plain number in the events list advances the clock (simulate()).

longeron evidence

evidence carries the provenance workflow of the evidence guide, as two sub-commands.

evidence verify loads a model (the shared model-input forms and --no-cache/--stdlib apply), re-checks every SourceEvidence citation, and prints one verdict per citation:

$ longeron evidence verify examples/deepscout
status  element                               document                                   detail
------  ------------------------------------  -----------------------------------------  ------
intact  ScoutParts::F450Kit::Propeller::mass  https://www.apcprop.com/product/10x4-5mr/
1 citation(s): 0 drifted or lost

The exit code is the count of drifted and lost citations, so a CI step can gate on it directly.

Option	Effect
--no-fetch	Stay offline: URL documents verify against the local evidence cache only. An uncached URL document reports unreachable.

evidence init writes the git-LFS stanza for the evidence/ directory into .gitattributes (storage pattern 1: owned documents commit as LFS objects). It preserves existing .gitattributes content and is idempotent.

$ longeron evidence init
wrote .gitattributes

Option	Effect
path	Repository root; defaults to ..

longeron serve

serve exposes a workspace as a git-backed OMG Systems Modeling API server (requires pip install "longeron[server]"):

$ longeron serve path/to/models --port 9000
INFO:     Uvicorn running on http://127.0.0.1:9000 (Press CTRL+C to quit)

Option	Effect
path	Directory (or single .sysml file) to serve; defaults to ..
--host ADDR	Bind address. Defaults to 127.0.0.1: the server is local-first and does no authentication.
--port N	Port; defaults to 9000 (the pilot-server convention).

Unlike the other subcommands, serve takes no --no-cache/--stdlib options: it always loads through the model cache, and it blocks until interrupted. See API server & client for the resource model, the git-commit mapping, and the /x/ extension endpoints.