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
snt hub -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

Compare saved environments with snt dip compare. It prints a summary and up to 50 differences by default. Exit status is 0 when equal in the selected scope, 1 when different, and 2 for invalid input or an error.

snt dip compare before.diph5 after.diph5
snt dip compare before.diph5 after.diph5 --scope full --max-details 20

--max-array-examples N controls the number of flat array indices shown for each changed array. See DIPH5 comparison for scope semantics.

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.

To use a DIPfile project in the browser, package its local text dependencies into one static JSON asset:

snt dip package --project DIPfile --output project.bundle.json

The packager evaluates the project with the native parser, includes files it opens (including .dipt tables), and reports missing or out-of-directory files. See WebAssembly and JavaScript for parseBundle and validateBundle.

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.

Describing and previewing parameters

For the full review cycle, see Inspect, propose, preview, review.

The read-only semantic commands return versioned JSON. describe reports one evaluated path, while list selects values by path and explicit tags:

snt dip describe --project DIPfile --path simulation.steps --format json
snt dip list --project DIPfile --query '?simulation.' --limit 50 --format json
snt dip list --project DIPfile --tag-all runtime --format json
snt dip override-contract --project DIPfile --path simulation.steps --format json
snt dip schemas --project DIPfile --format json

Use --input for a DIPL file or a DIPH5 snapshot. Values in the JSON response have a DIPL text encoding. Values exceeding --max-value-elements or the 4096-byte text cap are omitted, and tables have no single value. list omits value content by default and reports whether its result was truncated. Missing defaults and dependency graphs are marked unavailable instead of being inferred. Add --record-graph to describe or list to capture dependencies while parsing a DIPfile or DIPL input. A DIPH5 snapshot uses its saved graph state.

schemas returns the snt-schema-hierarchy/1 contract: reusable member trees, ordered application sites, and each evaluated value’s applied and contributing schema IDs. Schema IDs are registered names within this project. It preserves collection item paths such as items[key]. For a DIPH5 input, definitions_available and applications_complete are false; retained schema associations are still listed, while unknown origins and inheritance flags are null. This command does not modify the model.

override-contract classifies an override target as existing_value, existing_item, new_item, or unavailable. It reports applicable constraints and a reason for unavailable targets. A new collection item needs a schema on its collection; append a list item with items[] or create a map item with items[key]. This is a static guide: use preview to check the proposed value and dependent calculations.

For a populated example, run this from the repository root:

snt dip describe --input examples/dip/SemanticDescription/parameters.dip \
    --path simulation.speed --record-graph --format json

It reports the evaluated speed, units, descriptive metadata, tags, enforced condition, source location, and reads of simulation.distance and simulation.duration. Metadata fields absent from the DIPL input remain empty; the tool does not invent publication details or a default value.

preview evaluates the original model and a separate candidate with ordered overrides. It reports validation diagnostics and an effective-value diff without writing project files or generated outputs:

snt dip preview --project DIPfile --override-file candidate.dip --format json
snt dip preview --input parameters.dip --override 'simulation.steps = 200' \
    --max-details 20 --format json

An invalid candidate is a JSON result with candidate_valid: false and diff.available: false. The command exits successfully when it can return that result; command-line usage errors return a nonzero status. Preview accepts DIPfile, .dip, and .dipl inputs, while description and listing also accept DIPH5 snapshots.

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
snt dip parse --project DIPfile --record-graph --relative-source-paths \
    --save project.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. --record-graph records evaluation dependencies while parsing DIPL input; the graph is stored by --save. It cannot be used with --load. --relative-source-paths stores source-manifest paths relative to the saved DIPH5 file and requires --save. This is useful when a project and its snapshot are distributed together.

To inspect many values without evaluating the original DIPL project for each query, save one evaluated snapshot and list from it:

snt dip parse --project DIPfile --save evaluated.diph5
snt dip list --input evaluated.diph5 --query '?' --format json

The snapshot contains evaluated state, not a reevaluable copy of the DIPL program. Recreate it after changing project inputs or overrides; the CLI does not automatically check snapshot freshness.

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. Reports from DIPL inputs record evaluation dependencies automatically. The Parameter guide links effective values to full reference entries, and the Schemas section lists the parameters each schema supplied. A loaded DIPH5 report includes calculation relationships only if its snapshot contains a recorded graph; otherwise the report states that they are unavailable. 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.

Pinned code examples with SNT Hub

SNT Hub connects a project in the published Hub catalogue to a local, pinned workspace. You can inspect its source and DIPL model, prepare native inputs from an example, and use optional build or local run recipes when the project provides them. setup prepares files; it does not build or run the solver.

Quick path

mkdir study && cd study
snt hub list              # Find a project ID
snt hub fetch PROJECT     # Create a pinned workspace here
snt hub examples          # Find an example ID and its capability
snt hub info              # Check the pinned origin and revisions
snt hub setup EXAMPLE     # Prepare runs/EXAMPLE

Replace PROJECT with an ID from list and EXAMPLE with a name from examples. A complete example produces the inputs required by its recipe. Other examples require --inputs-only; see Prepare an example below.

Discover and pin a project

snt hub list reads the live catalogue on each invocation; it needs network access and does not use a local cache. fetch also needs Git and network access. It writes into the current directory unless you pass --dir PATH. You can pin a particular catalogue revision with --revision HUB_SHA; use the full SHA currently advertised by the catalogue.

A fetched workspace contains:

• source/ — the pinned original project source.

• dipl/ — editable DIPL model and adapter files.

• .snthub/lock.json — the Hub and source revisions and their origin.

fetch refuses existing workspace files. If the workspace already matches the requested project and revision, it reuses it without replacing local edits. Run snt hub info to inspect its lock before using the adapter with your data. examples, info, setup, build, and run find the workspace by searching upward for .snthub/lock.json. Use --workspace DIR with any of them to select a workspace explicitly.

Prepare an example

snt hub examples lists each recipe with a capability:

• complete — snt hub setup EXAMPLE prepares the recipe’s required assets, native input files, and an environment.diph5 snapshot.

• native-inputs-only or requires-external-data — pass --inputs-only explicitly. The prepared files still need additional inputs before they can run.

Setup writes to runs/EXAMPLE by default. Use --output DIR for a different directory inside the workspace. It refuses an existing destination and publishes the directory only after the adapter succeeds. Python 3 with venv and pip is needed when setup, build, or run first provisions the workspace’s adapter runtime.

To change values for one prepared run, write bare DIPL override assignments to a file. The paths must exist in the selected DIPL model; these names only illustrate the syntax:

simulation.steps = 100
solver.tolerance = 1e-6

Then pass that file to setup, without a $override wrapper:

snt hub setup EXAMPLE --override-file tuning.dip \
    --output ./runs/tuned_example

The adapter evaluates the override with DIPL. An accepted file is copied to input-overrides.dip and its SHA-256 is recorded in setup-lock.json. A complete recipe with a fixed data generator may allow only approved targets. Rejected targets do not publish the requested directory.

Build and run when supported

snt hub build and snt hub run are available only if the pinned project declares the corresponding reviewed capability. A project may offer either one independently. Undeclared capabilities are reported before an adapter runtime is created; use the project’s upstream instructions if it has no Hub build recipe. Build profiles are defined by the project.

snt hub build --setup runs/EXAMPLE --profile local
cd runs/EXAMPLE
snt hub run
# Or select an existing executable:
snt hub run --executable /path/to/solver

Pass --setup DIR to build or run when working outside the prepared run directory. A build recipe that requires a setup checks its setup-lock.json. It may accept an inputs-only setup if that setup contains the required build configuration. A successful build writes build/PROFILE and build-lock.json with the source revision, optional setup-lock digest, adapter build details, and executable SHA-256.

run requires a complete setup. It checks a matching build lock, or hashes the executable named with --executable. It records the executable identity and exit status in the setup directory’s run-lock.json, even if the solver fails. A second run in the same directory is refused until a rerun policy is defined. The project adapter chooses the build and solver commands; SNT does not infer them from the project name.

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.

The optional snt view <artifact> command opens the graphical Parameter Viewer. Its guide covers building the viewer, browsing live projects and DIPH5 snapshots, opening source locations, and reloading after an edit.

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