Skip to content

CLI reference

ntpstats <command> --help shows every option. Common input options, accepted by every command that reads a log (info, stability, dynamic, plot, network, filter, report, timeerror, audit, events, convert, noise, spectrum, hat, holdover, poll):

Option Meaning
-f/--format force a format instead of auto-detection; profile:NAME or profile:FILE.toml for instrument exports
--negate flip the offset sign (for sources that log local − reference)
--peer ADDR / --all-peers pick one peer/source (substring match) or analyse all
--start, --end time window (POSIX seconds or ISO 8601 UTC)
--outliers K drop samples beyond K·MAD of the detrended median
--tau0 S sample interval of single-column files; also the stability grid
--columns SPEC map the columns of a CSV/TSV export without a profile, e.g. time=Time:iso,te=TIE,units=ns (column mapping)
Command Purpose
info summary statistics (percentiles, trend, gaps, auxiliary columns)
timeerror (te) max|TE|, cTE, dTE_L/dTE_H, max|TEL|, MTIE/TDEV of dTE_L; --limits, --mask (exit code 3 on failure), --input-is-te, --units (PTP & time error)
convert write a log as a Stable32 phase/frequency file, plain CSV, Parquet, an OMNeT++ vector file or ns-3 time value text (--to, --no-timetags)
stability (adev) ADEV/OADEV/MDEV/TDEV/HDEV/TOTDEV/MTOT/TTOT/HTOT/Theo1/TheoBR/TheoH/MTIE/TIErms with CIs; --mask FILE (exit code 3 on failure), --exact, --raw-totals, --csv, --json
dynamic sliding-window stability matrix (time × τ)
network delay floor, queueing, asymmetry indicator, floor packet percentage
filter Kalman / RTS smoother / min-delay filter, output CSV
compare A B error of A against reference B: bias, RMS, TDEV and MTIE of the error
validate REF a disciplined clock against an independent reference (campaign): clock error, the daemon's maximum error over each update interval, each server's correctness interval and every estimator on the real exchanges; exit code 3 if the daemon's bound fails
plot static report figure (matplotlib)
report self-contained HTML report; --time-error adds time-error cards and a TE/TEL chart
simulate simulate NTP or PTP exchanges with ground truth (--preset, e.g. internet, ptp-lan, ptp-tc); --benchmark
bench estimators × scenarios × seeds against ground truth; --html, --csv, --list; trace:FILE replays a capture or log
sawtooth remove the GNSS PPS quantization sawtooth from a time-interval-counter log with a u-blox receiver's qErr (UBX-TIM-TP), or from a gpsd PPS log with its own qErr; prints TDEV before and after (Research data)
trace per-direction delays of a capture or log (floors, PDV, loss), --csv to replay it (Trace replay)
chain simulate a PTP grandmaster and N boundary clocks; time error per hop and at the end against a class and budget; exit code 3 on failure
query one-shot measurement: NTPv4, --nts, --pool N (NTS pool), --interleaved (RFC 9769), --ntpv5, --probe-v5, -4/-6 (Protocols)
roughtime signed coarse time from several Roughtime servers, chained nonces, causal check; --report writes a malfeasance report, --verify-report, --check-local; exit code 3 on malfeasance
monitor periodic SNTP/NTS/NTPv5 measurements to CSV (polite polling); --metrics-port serves OpenMetrics, --otlp pushes to OpenTelemetry (Monitoring)
watch sample the local chrony (chronyc -c tracking), ntpd (ntpq -c rv), ntpd-rs (ntp-ctl), ptp4l (pmc, with every port's state), ptpcheck, gpsd (PPS), a PHC against the system clock (phc), an OCP Time Card (timecard), AWS ClockBound (clockbound) or Meta fbclock (fbclock) (sources); --metrics-port as for monitor
audit UTC traceability evidence: per-sample error bound with stated assumptions, windows, coverage; HTML/JSON with input hashes; exit code 3 on failure (Assurance)
events phase steps, spikes, frequency changes, delay-floor (route) changes and leap smears
prom fetch a Prometheus range query (ntpd-rs, chrony_exporter, …) to a JSON file every command reads
noise fit h_α (white/flicker PM, white/flicker/random-walk FM, optional drift) with bootstrap intervals and corner τ; --scenario writes a simulator clock, --inet an INET oscillator (Metrology)
spectrum (psd) phase or frequency PSD (Welch or sine multitaper, gap-aware, log bins), --carrier for L(f)
hat individual stability of 3+ sources from their differences: Groslambert covariance, three- or N-cornered hat
holdover predicted TIE after loss of reference, time to violate --limits, --backtest calibration, --min-holdover (exit code 3)
poll predicted error just before the next poll for each candidate poll interval; --target gives the longest interval within it (exit code 3 if none) (Metrology)
plugins installed plugins (parsers, estimators, detectors, masks, profiles) and load errors (Writing a plugin)
dataset summary of the open interop dataset (data/interop/): availability, median offset and delay, protocol support per server; --trend follows each server over the runs (offset relative to the run's consensus, delay, availability) and flags servers that shifted, appeared or disappeared (--strict: exit code 3)
fleet many hosts at once (files, one directory per host, or an exporter query): ranked by the nearest of --max-offset, --max-jitter, --max-bound, --max-age and --mask; --json, --csv, --strict (exit code 3); --rules writes Prometheus alert rules with the same limits (Fleet view)
columns propose a column mapping for a CSV/TSV export and --save it as a profile (column mapping)
cv GNSS time transfer between two CGGTTS files: common view or all in view (Research data)
bounds validate clock-error bounds (ClockBound, fbclock, CSV) against a reference; exit code 3 on violations
ui start the local web UI