CLI Command-line interface

The snt executable evaluates PUEL expressions, converts quantities, and parses DIPL definitions from a terminal or shell script. It uses the same C++ implementation as the language bindings.

Getting started

For a source build, enable ENABLE_EXEC_APPS and ENABLE_EXEC_APPS_SNT, together with the PUQ, DIP, and API modules. These options are enabled by default. The executable is written to build/bin/snt and installed into the installation prefix’s bin directory. See Installation for build and installation steps.

Once the executable is on your PATH, inspect the available commands:

snt -h
snt puq -h
snt dip -h
snt report -h

Quantities and units

The PUQ commands evaluate expressions, convert units, inspect quantities, and list available unit definitions. Quote expressions so the shell passes them as a single argument:

snt puq eval "23*cm + 3*m"
snt puq convert "2.5*m" "cm"
snt puq info "23*kg*m2/s2"
snt puq list deriv

For conversions between unit systems, specify the input system with -s and output system with -S. Some conversions also require the physical quantity, supplied with -Q:

snt puq convert "12*statA" "A" -s ESU -S SI -Q "I"

DIPL parameters

Use dip parse with --input file to load a file or --input string to supply definitions directly. --print displays nodes with names and units, and --request selects a node:

snt dip parse --input file parameters.dip --print
snt dip parse --input string "answer int = 42" --request answer --print

Repeat --input to combine sources before evaluating a request.

For a reusable set of units, named sources, DIPL files, and inline DIPL, place the declarations in a DIPfile project:

snt dip parse --project DIPfile --request simulation.steps --print

--project supplies the model and resolves paths relative to the DIPfile. It can be combined with --input override_string or --input override_file to tune its values.

Values for shell scripts

The --value option prints exactly one defined, unitless scalar without its name or string quotes. It requires --request and cannot be combined with --print. Optionally use --type to require bool, integer, float, or string without implicit conversion:

answer=$(snt dip parse --input string "answer int = 42" \
    --request answer --value --type integer)
printf '%s\n' "$answer"

In this mode, invalid requests write an error to standard error and return a nonzero exit status. Arrays, values with units, and undefined values are rejected. For reading such scalar settings during CMake configuration, see CMake integration.

Registering schemas

Schema inputs take a name and either body text or a file containing the body, without a $schema wrapper:

snt dip parse -i schema_string settings 'value int = 42' \
    -i string 'physics : settings' -r physics.value --value
snt dip parse -i schema_file settings settings.dipl \
    -i string 'physics : settings' --print

As with other individual inputs, these cannot be combined with --project or --load.

Overriding values

Pass an unwrapped override body using override_string:

snt dip parse -i file parameters.dip \
    -i override_string 'simulation.steps = 1024' --print

Duplicate targets fail, including duplicates in $override regions in files. Project inputs accept override text alongside the manifest:

snt dip parse --project DIPfile \
    -i override_string 'simulation.steps = 1024' --print

The project and override inputs may be supplied in either order.

Use -i override_file overrides.dip to read an unwrapped override body from a file.

Environment persistence

Use --save to write the full evaluated environment to a DIPH5 file. Use --load instead of --input to query saved parameters without reevaluating their DIPL sources:

snt dip parse --input string "simulation.steps int = 100" --save parameters.diph5
snt dip parse --load parameters.diph5 --print
snt dip parse --load parameters.diph5 --request simulation.steps --value --type integer
snt dip parse --load parameters.diph5 --save copy.diph5

--load cannot be combined with any --input. --save overwrites an existing file and does not require --print or --value. It saves the entire environment even when --request or --tags restricts printed output. If output validation fails, the destination is not written. File errors are reported on standard error with a nonzero exit status. See DIP environment persistence for the format and its limitations.

Generating static parameters

Use --generate <format> <file> to export the complete evaluated environment as language-native source or a data file. It works after parsing DIPL input or loading a DIPH5 environment:

snt dip parse --input file parameters.dip --generate cpp parameters.hpp
snt dip parse --load parameters.diph5 --generate julia parameters.jl
snt dip parse --input file parameters.dip --generate json parameters.json

Supported format names are cpp, c, fortran, rust, julia, json, and yaml. --generate can accompany --save. Requests and tags only affect text printed by the command, not the generated environment. See Static parameter generation for the native representations and format-specific behavior.

Generating reports

snt report writes a report of evaluated values and units, descriptions, parameter paths, source identities, custom unit definitions, schema information, override status, and available publication metadata. Function names are listed when registered; executable function bodies are not included. Built-in PUQ unit catalogues are not duplicated in the report. Output paths are sorted for repeatable reports. The default format is tex; it requires no external tools:

snt report --project DIPfile --output report.tex
snt report --load run.diph5 --output report.tex
snt report --input file parameters.dip --output report.tex

Brief++ also renders the same report as Markdown (md), reStructuredText (rst), HTML (html), Typst (typ), plain text (txt), or a briefpp/1 document tree (json):

snt report --project DIPfile --format html --output report.html
snt report --project DIPfile --format md --output report.md
snt report --load run.diph5 --format json --output report.json

These formats need no external tools. Markdown tables use Brief++’s MyST-style directives. Report JSON describes the document; use snt dip parse --generate json for static parameter export JSON.

The command accepts the same --input kinds as snt dip parse. A project may be combined with override_string or override_file inputs. A DIPH5 --load cannot be combined with other inputs. For loaded snapshots, the report contains only provenance retained in DIPH5. Empty groups and collections without value descendants are not present in a DIPH5 snapshot and therefore cannot appear in a report generated from it.

Use --intro introduction.tex to insert trusted LaTeX after the report contents page. The file is read as a fragment, without a document preamble. Its text is included in both TeX and PDF reports. Other formats reject --intro.

--format pdf compiles the same generated TeX with pdflatex. Select a compatible executable with --tex-compiler when needed:

snt report --project DIPfile --format pdf --output report.pdf
snt report --load run.diph5 --format pdf --output report.pdf \
    --tex-compiler /path/to/pdflatex

PDF output requires a locally installed TeX compiler. If it is unavailable or compilation fails, the command reports an error and does not create the output PDF. The TeX compiler is never installed by snt report. For reports containing Unicode characters unsupported by pdflatex, use --tex-compiler lualatex when that compiler is installed. Use --title, --author, --date, and --report-version for the cover. To regenerate the bundled CreateReport example PDF from the repository root:

build/bin/snt report --project examples/dip/CreateReport/DIPfile \
    --intro examples/dip/CreateReport/introduction.tex \
    --title "Mock Heat Flow Study" --author "Example Research Team" \
    --date "2026-09-28" --report-version "1.0 demo" \
    --format pdf --output examples/dip/CreateReport/report.pdf

The default cover title is DIP parameter report; an empty author appears as Not specified. The date defaults to the local generation date and the version to the SNT build version. Set date and version explicitly for a reproducible cover. The CreateReport example shows the layout and provides a PDF to inspect.

Server, dmap, and viewer commands

The main executable also hosts the REST server and dimension-map generator:

snt server --help
snt server --port 8081
snt server --project model=/srv/model/DIPfile
snt dmap --help

Build server support with ENABLE_SNT_SERVER=ON and dimension-map generation with ENABLE_SNT_DMAP=ON. Server support requires cpp-httplib; builds without it can set ENABLE_SNT_SERVER=OFF. See REST API server for routes and options.

snt dmap is a developer tool for precomputing PUQ unit dimensions. Run it from the source repository root only when updating unit definitions: it overwrites src/snt/puq/systems/dmaps/dmap_*.h. Review the generated diff before committing. Its -e option replaces those headers with empty placeholders.

snt view reserves the entry point for a future parameter viewer. With ENABLE_SNT_VIEW=ON, snt view --help describes the placeholder and invoking it reports that the viewer is not implemented. No GUI dependencies are required yet.

All three features belong to the snt target and require ENABLE_EXEC_APPS_SNT.