Grind

© 2026 Obsvra. This document describes SpiceGrinder and is provided to help you evaluate and use it. It is not a license to reproduce, adapt, or use this material to build a competing product or service. Full terms: the SpiceGrinder EULA.

NAME

Grind — load a SpiceGrinder model and emit observations

SYNOPSIS

java -cp spicegrinder.jar com.obsvra.spicegrinder.tools.Grind [options] model.xml|model.json

On a jpackage install, the same tool ships as a native launcher alongside the GUI:

grind [options] model.xml|model.json

DESCRIPTION

Grind is the headless runtime: it loads a model file, drives its root node (or a named node inside it, see --node) for a fixed or unbounded number of observations, and writes the result as CSV, TSV, or plain text — to stdout by default, or to a file.

Exactly one model file must be given as the final positional argument.

OPTIONS

Option	Meaning
`--count N`	Number of observations to emit. Omit to run until interrupted (Ctrl+C).
`--out PATH`	Write output to a file instead of stdout. `-` also means stdout.
`--format FMT`	`csv` \| `tsv` \| `plain` (default `csv`).
`--header`	Write a simple header row (`dim0,dim1,...`) — csv/tsv only.
`--node NAME`	Generate from a named registry node instead of the model root.
`--seed N`	Force the RNG seed for this process (highest precedence — see SEED PRECEDENCE).
`--no-seed`	Ignore the model’s own embedded seed and force a fresh random one (see SEED PRECEDENCE). No effect if `--seed` is also given — `--seed` always wins, and a note is printed to stderr saying so.
`--audit`	Enable the audit/heartbeat instrumentation stream for this run.
`--performance`	Enable the performance instrumentation stream for this run.
`--diagnostic`	Enable the diagnostic instrumentation stream for this run.
`--seat`	Tag this run’s `instance.kind` as a human-driven seat, overriding the default.
`--runtime`	Tag this run’s `instance.kind` as an unattended/automated instance.
`--quiet`	Suppress the progress banner lines normally written to stderr.
`-h`, `--help`	Print usage and exit.
`--version`	Print the version (e.g. `1.0.0 Alpha 1 (Build 1)`) and exit.

SEED PRECEDENCE

Highest to lowest: --seed on this invocation > --no-seed (forces a fresh random seed, skipping the model’s own embedded seed if it has one) > the model spec’s own embedded seed attribute > a freshly generated seed. Whichever one actually ran is always applied to the process RNG and always logged — to stderr (unless --quiet) and to the run-summary instrumentation event if --audit/--performance is active. “No seed given” never means “not reproducible” — check the logged value.

--no-seed exists for the case where a model has its own embedded seed but you want a genuinely fresh, non-reproducing run without having to generate and pass your own --seed value. It mirrors the Service API’s noSeed request field (Service-API-Reference.md), same precedence shape.

INSTRUMENTATION

--audit/--performance/--diagnostic are additive opt-ins layered on top of whatever ~/.spicegrinder/instrumentation.properties (or -Dspicegrinder.instrumentation.*) already enabled — they turn a stream on for this run; they never turn one off. Nothing is ever sent over the network; all instrumentation is local-only NDJSON under: ~/.spicegrinder/logs/{audit,performance,diagnostic}.ndjson

instance.kind buckets each logged event as seat (a modeler/developer at a terminal) or runtime (an unattended/automated invocation), for filtering in a log pipeline. Default: whether stdin/stdout is an interactive terminal (System.console() != null → seat, otherwise runtime). --seat/--runtime override that default and also override anything already set via the properties file, same precedence shape as --seed.

SIGNALS

Ctrl+C during an unbounded run (--count omitted) or a long bounded run finishes flushing already-generated output — and the run-summary/instance-stop instrumentation events — before the process actually exits. No abrupt kill mid-write.

EXIT STATUS

Code	Meaning
0	Ran to completion (or was cleanly interrupted with Ctrl+C) and wrote output.
1	Model file not found, `--node` name not found in the registry, or an error during load/generation.
2	Bad arguments — missing required value, unrecognized option, or not exactly one model file given.

EXAMPLES

Generate 100 observations from a model’s root, as CSV, to stdout:

java -cp spicegrinder.jar com.obsvra.spicegrinder.tools.Grind --count 100 model.xml

Run unbounded (until Ctrl+C), TSV, with a header row, to a file:

grind --format tsv --header --out draws.tsv model.xml

Reproduce a prior run exactly:

grind --count 1000 --seed 42 model.xml

Get a genuinely fresh run from a model that has its own embedded seed baked in:

grind --count 1000 --no-seed model.xml

Generate from a specific internal node rather than the model’s root, with an audit trail:

grind --node ClaimSeverity --audit --count 500 model.xml