CLI Reference¶
The sonda binary has six verbs: run, list, show, new, test, and completions.
run executes a scenario YAML file. list and show browse a catalog directory of scenarios and composable packs. new creates a starter file. test runs a scenario and verifies its expect: alert expectations. completions prints a shell completion script.
Earlier releases used per-signal subcommands (metrics, logs, histogram, summary). These were removed in 1.9. Every signal type is now declared inside the scenario YAML, then run with sonda run.
Global options¶
| Flag | Short | Description |
|---|---|---|
--catalog <DIR> |
-- | Directory holding scenario and pack YAML files. Required when resolving @name references with run / show, and required for list. No env-var fallback and no home-directory scan. |
--quiet |
-q |
Suppress start/stop banners and live progress. Errors still print to stderr. Mutually exclusive with --verbose. |
--verbose |
-v |
Print the resolved scenario config at startup, then run normally. Mutually exclusive with --quiet. |
--dry-run |
-- | Parse and validate the scenario, print the resolved config, then exit without emitting events. |
--format <FORMAT> |
-- | Output format for --dry-run: text (default) or json. Only meaningful with --dry-run run. |
--help |
-h |
Print help and exit. |
--version |
-V |
Print the version and exit. |
Global flags go before the subcommand:
sonda --catalog ~/my-scenarios -q run @cpu-spike
sonda --catalog ~/my-scenarios --dry-run --format json run @cpu-spike
Several subcommands and flags from earlier releases were removed in 1.9. Clap rejects them with unrecognized subcommand. The removed surface:
- Subcommands:
metrics,logs,histogram,summary,scenarios,packs,catalog,import,init. - Flags:
--scenario-path,--pack-path. - Env vars:
SONDA_SCENARIO_PATH,SONDA_PACK_PATH.
sonda run¶
Run a scenario from a YAML file or a @name catalog reference.
| Argument / Flag | Description |
|---|---|
<SCENARIO> |
Filesystem path to a scenario YAML file (./my.yaml, examples/cpu.yaml) or @name for a catalog entry (requires --catalog). |
--catalog <DIR> |
Required when <SCENARIO> starts with @. Also used to resolve pack: <name> references inside the file. |
--dry-run |
Compile and validate the scenario, print the resolved config, then exit. |
--format text\|json |
Dry-run output format. Default text. |
--duration <D> |
Override defaults.duration. Accepts 30s, 5m, 1h. |
--rate <R> |
Override defaults.rate (events per second). |
--sink <TYPE> |
Override the sink type (stdout, file, tcp, udp, http_push, loki, ...). |
--endpoint <URL> |
Override the sink endpoint. |
--encoder <TYPE> |
Override the encoder type. |
-o <PATH> |
Shortcut for --sink file --endpoint <PATH>. Conflicts with --sink. |
--label k=v |
Add a static label. Repeatable. |
--on-sink-error warn\|fail |
Override defaults.on_sink_error. |
--dry-run reads the data files your scenario references
Validation runs the same pipeline run does, and some rules are facts about the data rather than the YAML — a csv_replay derives its rate from the capture's own timestamps. So a dry-run opens the CSV. If you validate in CI on a machine that has the scenario but not the capture, --dry-run will fail there. That is the check working: a config pointing at data that is not present is a finding, not a false alarm.
Run a file¶
Sonda prints a start banner, runs the scenario, and prints a stop banner with totals.
Run a catalog entry¶
The @cpu-spike reference resolves to a YAML file in ~/sonda-catalog/ whose header has kind: runnable and either name: cpu-spike or a filename matching cpu-spike.yaml.
Override at the command line¶
CLI flags take precedence over defaults: inside the file. Use them for a one-off rate change or to point the same scenario at a different sink:
sonda run examples/cpu-spike.yaml \
--rate 500 \
--duration 10s \
--sink http_push --endpoint http://victoriametrics:8428/api/v1/import/prometheus
Dry-run¶
--dry-run compiles the scenario, prints the resolved configuration, and exits. Use it to validate a file before a long run:
{
"file": "@cpu-spike",
"version": 2,
"scenarios": [
{
"index": 1,
"name": "cpu_usage_percent",
"signal": "metrics",
"rate": 10.0,
"duration": "30s",
"generator": "spike_event (baseline: 20, spike: 95, duration: 10s)",
"encoder": "prometheus_text",
"sink": "stdout",
"labels": {},
"phase_offset": null,
"clock_group": null,
"clock_group_is_auto": false
}
]
}
sonda list¶
List catalog entries from a directory. Output includes both runnable scenarios and composable packs.
| Flag | Description |
|---|---|
--catalog <DIR> |
Required. Directory to list. |
--kind runnable\|composable |
Filter by entry kind. Default: both. |
--tag <TAG> |
Only include entries whose tags: array contains this value. |
--json |
Emit a stable JSON array on stdout instead of the default tab-separated table. |
The default output is a tab-separated table with four columns: KIND, NAME, TAGS (comma-joined), and DESCRIPTION. Pipe it through column -t -s$'\t' for aligned reading.
KIND NAME TAGS DESCRIPTION
runnable cpu-spike cpu,infrastructure CPU spike to 95% for 30 seconds
runnable memory-leak memory,leak Slow memory leak from baseline to ceiling
composable prom-text-stdout defaults Shared prometheus_text + stdout defaults
Filter to runnable entries tagged cpu:
--json emits a stable array on stdout. Each element has name, kind, description, tags, and the resolved source path. Use it as the contract when scripting catalog discovery.
Files without a recognized kind: header are skipped silently. A file the process cannot open, and a file with an unparseable YAML body, each print a warning to stderr and are also skipped. The listing continues — one bad file never costs you the rest of the catalog.
sonda show¶
Print the raw source YAML for a catalog entry, exactly as stored on disk.
| Argument / Flag | Description |
|---|---|
<@NAME> |
Catalog entry name. The leading @ is optional. show cpu-spike and show @cpu-spike both work. |
--catalog <DIR> |
Required. Directory containing the entry. |
Works for both kind: runnable and kind: composable entries. The output is the file contents byte-for-byte. For runnable entries, it round-trips through sonda --dry-run run:
sonda --catalog ~/sonda-catalog show @cpu-spike > /tmp/snap.yaml
sonda --dry-run run /tmp/snap.yaml
sonda new¶
Create a new scenario YAML. Four modes are available. Pick the one that matches how much you already know about the scenario you want.
| Flag | Description |
|---|---|
| (no flags) | Interactive dialoguer flow. Walks through signal type, generator, rate, duration, sink type, and output path. Requires a TTY on stdin. |
--template |
Print a minimal valid YAML to stdout and exit. No prompts. |
--from <CSV> |
Seed the file from a CSV file. Pattern detection runs on each numeric column and chooses an operational alias (steady, spike_event, leak, saturation, flap) per column. |
--from-prometheus <URL> |
Capture a live PromQL range query and replay it verbatim — no pattern detection. See the capture flags below. Conflicts with --template and --from. |
-o <PATH> |
Write the result to a file instead of stdout. Parent directories are created if missing. |
Capture flags¶
Every flag in this table requires --from-prometheus, and --from-prometheus
requires --query, --step and --out. Full guide:
From a live Prometheus.
| Flag | Description |
|---|---|
--query <PROMQL> |
The range query to capture. Sent to the server as written. |
--range <DURATION> |
Capture the window ending now (1h, 30m). Alternative to --start/--end. |
--start <INSTANT> / --end <INSTANT> |
Explicit bounds, as unix seconds or RFC 3339. Both or neither. |
--step <DURATION> |
Sample step of the query, and the replay grid. |
--out <PATH> |
Where to write the captured CSV. The emitted scenario references this path. |
--metric-name <NAME> |
Name for series the query left without one — PromQL aggregations drop __name__. Never overwrites a name the query kept. |
--timescale <FACTOR> |
Replay speed. 4 replays an hour in fifteen minutes, moving rate, duration and gap windows together. |
--header <NAME:VALUE> |
Extra request header, repeatable. An explicit Authorization: overrides SONDA_PROM_TOKEN, with a note on stderr. |
| Environment variable | Description |
|---|---|
SONDA_PROM_TOKEN |
Bearer token for the capture. Read from the environment so it stays out of shell history and process listings. |
Minimal template¶
version: 2
kind: runnable
defaults:
rate: 1
duration: 60s
encoder:
type: prometheus_text
sink:
type: stdout
scenarios:
- id: example
signal_type: metrics
name: example_metric
generator:
type: constant
value: 1.0
Write it straight to a file:
Seed from a CSV¶
Each numeric column in the CSV gets its own scenarios: entry. The generator alias is chosen by pattern detection (steady, spike_event, leak, saturation, flap). You then edit the output and tune the parameters instead of starting from a blank file.
Interactive flow¶
The prompts cover signal type, generator, rate, duration, sink, and output destination. Cancel with Ctrl+C at any point. Nothing is written until you confirm the output path.
sonda test¶
Run a scenario and verify its top-level expect: alert expectations against
a Prometheus-compatible query API. See
Alert testing for the
expect: block format.
| Flag | Description |
|---|---|
--prometheus-url <URL> |
Base URL of the Prometheus-compatible API evaluating the alert rules (e.g. http://localhost:9090) — verifies that the rule fires. Also read from SONDA_PROMETHEUS_URL. |
--alertmanager-url <URL> |
Base URL of the Alertmanager receiving the alerts (e.g. http://localhost:9093) — verifies that the notification arrived. Also read from SONDA_ALERTMANAGER_URL. |
--interval <DUR> |
Poll interval for alert-state checks. Default 5s. |
--query-timeout <DUR> |
Overall timeout for each alert-state query (connect + read), so a stalled endpoint fails fast instead of hanging. Default 10s. |
--query-step <DUR> |
Grid resolution for the post-hoc range queries that produce the verdict timelines. Match your rule evaluation interval. Default 5s. --prometheus-url only. |
Exactly one of --prometheus-url / --alertmanager-url is required (except
with --dry-run). Passing both is an error: they verify different hops of
the alerting path, so there is no sensible way to merge their verdicts.
The scenario runs exactly as sonda run would (no overrides). Firing
deadlines are measured from scenario start; resolution deadlines from
scenario end. A scenario without an expect: block is rejected. With
--dry-run, the scenario and its expectations are validated and printed
without emitting events or contacting Prometheus.
Verdicts are read from the datastore, not from the polling loop: live
polling (at --interval) only decides when each check has settled, then a
range query reconstructs what actually happened from the stored ALERTS
samples at --query-step resolution. Reported transition times are sample
times — independent of how often sonda test polled. If the range API is
unavailable, the verdict falls back to the live poll timeline with a
warning.
Against --alertmanager-url the verdict is read from live polling alone.
Alertmanager keeps no queryable history — there is no range API and no
time() endpoint — so there is nothing to reconstruct after the fact.
Transition times therefore carry --interval precision, sharpened by each
alert's own startsAt stamp (about one second of clock resolution, measured
from Alertmanager's Date header) and never pushed beyond what polling
observed. The report says so on every run; do not read these numbers as the
sample-accurate times the Prometheus path reports.
Two more differences on the Alertmanager path: it has no pending state (an
alert inside its rule's for: window has not been sent yet, so it is simply
absent), and an alert that Alertmanager has suppressed — silenced or
inhibited — still counts as firing, with a warning. A silence stops the
notification, not the alert.
Before the scenario starts, a preflight confirms the endpoint answers a query for every expectation. Only the first expectation is retried (3 attempts, for a backend still starting up in CI); the rest are probed once each, so preflight against a dead endpoint fails within about three query timeouts regardless of how many expectations the scenario declares.
sonda completions¶
Prints a shell completion script to stdout. Supported shells: bash, zsh,
fish, powershell, elvish.
The script is generated from the same argument parser the binary runs on, so
it never falls behind: a flag added to sonda test is completable in the same
release, with no completion list to update separately.
Install it wherever your shell looks for completions. For bash:
For zsh, write it to a directory on your $fpath:
For fish:
An unsupported shell name exits 2 and writes nothing to stdout, so a
mistyped shell cannot silently install an empty completion file.
Exit codes¶
| Code | Meaning |
|---|---|
0 |
Success. For sonda test: every alert expectation held. |
1 |
Runtime error (scenario failed, sink unreachable, validation rejected the YAML), or a sonda test expectation failed. |
2 |
Clap parse error (unknown flag, unrecognized subcommand, missing required argument). |
Status output¶
Sonda prints colored lifecycle banners to stderr while a scenario runs. Banners go to stderr and data goes to stdout. You can redirect stdout to a file or pipe it without mixing in banner text.
Start and stop banners¶
▶ cpu_usage_percent signal_type: metrics | rate: 10/s | encoder: prometheus_text | sink: stdout | duration: 30s
...
■ cpu_usage_percent completed in 30.0s | events: 300 | bytes: 12.3 KB | errors: 0
Live progress¶
Between the start and stop banners, Sonda updates a progress line every 200ms on TTYs and every 5s on non-TTYs:
Colors are automatic. Sonda respects NO_COLOR and disables ANSI when stderr is not a terminal.
Verbosity¶
--quiet suppresses banners and progress. Errors still print. --verbose prints the resolved scenario config at startup, then runs normally. The two flags are mutually exclusive.