CLI Reference

Every subcommand and flag of adsmd, checked against adsmd --help and the help text of each subcommand. For an end-to-end walk-through see the Tutorial; for what each rule checks see the Rule Catalog.

Synopsis

adsmd [COMMAND]
adsmd --help
adsmd --version

Command	Purpose
validate	Run all rules against a plant project; report as terminal text, JSON, SARIF or HTML.
manifest	Print the parsed plant project as JSON.
schema	Print the JSON Schema of the manifest.
xref	List every place a symbol appears in the manifest.
rules	List every rule (id, name, description).
stats	Print a summary of a plant project (counts per file family).
diff	Compare the name sets of two plant projects.
completions	Print a shell-completion script for bash, zsh, fish, powershell or elvish.
help	Print the general help or the help of a subcommand.

A <PLANT_DIR> is recognised as a plant project when it contains ZiniADS.txt, or when it contains both Input/Scheduler/ and Input/System/.

Exit codes

Code	Meaning
0	Success. For validate: no diagnostic reached the exit threshold (see --exit-on).
1	validate with --exit-on warning or --exit-on info: the worst finding that counts is below error. xref: no match. diff: the projects differ. Any command: the output could not be written or serialized.
2	validate: at least one error diagnostic. Also returned by the argument parser for an unknown flag, a missing argument or conflicting flags.
64	No subcommand given; invalid value for --severity, --rule or --exit-on; invalid .adsmd.toml.
65	<PLANT_DIR> is not a directory or is not recognised as a plant project.

validate

adsmd validate [OPTIONS] <PLANT_DIR>

Flag	Description
--json	Print the diagnostics as JSON on stdout. Conflicts with --sarif and --html.
--sarif	Print a SARIF 2.1.0 log on stdout. Conflicts with --json and --html.
--html[=<PATH>]	Write a self-contained HTML report. --html alone writes to stdout; --html=path/report.html writes to that file and prints a confirmation on stderr. Conflicts with --json and --sarif.
--severity <LEVEL>	Keep only diagnostics at <LEVEL> or above. Levels: error, warning (or warn), info; case-insensitive.
--rule <LIST>	Keep only the listed rules. Comma-separated ids (R1,R29) and inclusive ranges (R7-R12); the leading R is optional. R0 (parse errors) is always kept.
--exit-on <LEVEL>	Exit threshold: error, warning (or warn), info, never. See below.

Without an output flag the report is terminal text: one block per diagnostic (rule id, message, file:line:col, source snippet, help line) followed by a summary line such as adsmd: 1 error(s), 1 warning(s), 166 info(s).

Order of processing. All parsers and all rules always run. Then .adsmd.toml rule settings are applied, then --rule, then --severity. The remaining diagnostics are sorted by file, line, column and rule id, and the summary and the exit code are computed from that list. A diagnostic removed by .adsmd.toml, --rule or --severity therefore does not count toward the exit code.

Exit threshold.

--exit-on	Exit code
not given, or error	2 if any error is present, otherwise 0
warning	2 if any error, 1 if the worst finding is a warning, otherwise 0
info	2 if any error, 1 if any other finding is present, otherwise 0
never	always 0

Per-project config. validate looks for .adsmd.toml in the plant project directory and then in each parent directory, and uses the first one it finds. Its [rules] table switches rules off or changes their severity; see Integrating adsmd.

JSON output has this shape:

{
  "manifest_version": "1.0.0",
  "summary": { "errors": N, "warnings": N, "infos": N, "exit_code": N },
  "diagnostics": [ { "rule_id": 1, "severity": "error", "message": "...",
                     "primary_span": { "file": "...", "line": L, "col": C,
                                       "byte_offset": B, "byte_len": B },
                     "related": [ { "span": { ... }, "label": "..." } ],
                     "fix_hint": "..." }, ... ]
}

The related and fix_hint keys are omitted when a diagnostic has no related spans or no hint.

SARIF output is a SARIF 2.1.0 log with one tool (driver adsmd) and one results array. Severities map to the SARIF levels error, warning and note, and a fix hint becomes a fixes[].description. The rules that fired are listed under runs[0].tool.driver.rules with the id ADSMD<NNNN> (ADSMD0000-PARSE for R0) and a helpUri that points at the matching anchor of the rule catalog in the GitHub repository.

manifest

adsmd manifest <PLANT_DIR>

Prints the typed plant-project manifest as pretty JSON on stdout without running rules. A file that fails to parse is absent from the manifest; in that case a line with the number of parse errors is printed on stderr, and the exit code is still 0. Use validate to see the parse errors.

schema

adsmd schema

Prints the JSON Schema (draft-07, title PlantProject) that describes every field of the manifest. The schema is generated from the Rust types with schemars, so their documentation comments appear as descriptions.

xref

adsmd xref <PLANT_DIR> <SYMBOL>

Lists every place <SYMBOL> appears in the typed manifest, one hit per line, tab-separated:

<file>:<line>:<col>   [<context>]   <source line>

The symbol is compared literally with:

• channel symbols in all seven sections of RELAP5_channels.txt;
• ControlPanel.txt display names, channel symbols, X_* and IC_* symbols of controls, alarm names, the names that alarms reference, and support-system display names;
• SPDS names and the parameters they reference;
• action_symbol of Initiating_Event.txt rows;
• x_symbol and display_name of SystemReliability.txt rows;
• EOP and step ids of coded steps and of ZProcedure_*.txt headers;
• curve names and input names of Calculation_Aid.txt.

The context tag names the manifest section that matched (ControlPanel.parameters, Initiating_Event.action_symbol, and so on). The exit code is 0 with at least one hit and 1 with none.

rules

adsmd rules

Prints the built-in rule list, one rule per line: R<id> <short-name> <description>. The ids are the values accepted by validate --rule and by .adsmd.toml.

stats

adsmd stats <PLANT_DIR>

Prints a summary of a plant project: presence of ZiniADS.txt, ZCtrlPar.txt and the role configs, row counts per file family, KB and RM counts, procedure counts and deck card totals. No rules are run. When a file fails to parse, a line with the number of parse errors is printed on stderr.

diff

adsmd diff <PLANT_A> <PLANT_B>

Compares name sets between two plant projects, section by section:

• the symbols of all seven channel sections;
• ControlPanel parameters, component states, the three alarm sections and support-system displays;
• SPDS names, initiating-event action symbols, SystemReliability.txtx_symbol values;
• coded steps (<EOP>/<Step>) and step file names.

For each section that differs, names only in <PLANT_A> are printed with - and names only in <PLANT_B> with +. Values and row contents are not compared. The exit code is 0 when no section differs and 1 otherwise.

completions

adsmd completions <SHELL>

Prints a completion script for <SHELL> on stdout. Supported shells: bash, zsh, fish, powershell, elvish.

adsmd completions zsh > _adsmd

Move the generated file to the place your shell loads completions from (for zsh, a directory on $fpath). The scripts complete subcommands, flags and the shell names accepted by completions.