CLI¶
The rfgen command-line interface, built on Typer with Hydra integration for config composition.
Top-level¶
rfgen [--help] <command> [<args>...]
Command |
Purpose |
|---|---|
|
Run the generation pipeline end to end |
|
Add or refresh annotations on an existing dataset |
|
Validate a config without generating |
|
Inspect a generated dataset (counts, distributions, samples) |
|
List shipped scenario presets |
|
Print a preset’s resolved config |
|
List registered emitter families and classes |
|
List registered channel backends |
|
Print the installed rfgen version |
|
Probe installed-wheel and optional capabilities |
|
Validate one persisted execution-evidence record |
rfgen doctor¶
rfgen doctor [--json] [--require EXTRA]... [--probe BACKEND]...
[--timeout SECONDS]
The default probes verify distribution metadata, entry-point discovery, and bundled presets without importing numerical backends. Requested missing extras exit 3; requested failed or timed-out probes exit 4. JSON and text output are rendered from the same immutable report.
rfgen evidence validate¶
rfgen evidence validate --kind KIND --instance PATH
[--repository PATH] [--json]
rfgen evidence validate --bundle PATH
[--selector-inventory PATH]
[--repository PATH] [--json]
The validator verifies the packaged schema’s raw and RFC 8785 canonical
digests before parsing evidence, then applies self-hash and cross-record
semantics. --instance accepts exactly one JSON object and requires --kind.
Its case-sensitive value is exactly one of ModuleAcceptanceGateV1,
ModuleStatusV1, WorkstreamExecutionManifestV1, ChapterGateReportV1,
ScientificValidationHandoffV1, or ScientificValidationResultV1; the
supplied kind is injected only when the object has no kind field. --bundle
accepts a non-empty JSON array of heterogeneous objects. Every bundle member
must carry its own discriminating kind, and --kind is forbidden with
--bundle. Bundles validate manifest-to-gate, science handoff-to-result,
status-history, and chapter-gate links together rather than treating each
object as an independent success.
Chapter-gate selector provenance is intentionally not discovered by this CLI.
For a chapter represented in a bundle, supply one strict JSON
--selector-inventory document shaped as
{"chapter_id":"...","selectors":[{"row_id":"...","sources":["entry-point","packaged-config"]}]}.
The command validates each document as frozen SelectorInventoryV1 and passes
it to the validator as a deployment input. A chapter-report bundle without a
matching inventory returns semantic exit 5; malformed inventory JSON returns
invocation exit 2, while a JSON document that fails the strict typed shape
returns instance-schema exit 4. This prevents a submitted report from
declaring capabilities for itself.
Exit codes distinguish invocation (2), schema bundle (3), instance schema (4), semantic or Git validation (5), and redacted internal errors (6).
rfgen generate¶
rfgen generate [HYDRA_OVERRIDES...]
[--config-name=NAME] [--config-dir=DIR]
[--multirun | -m]
[--dry-run]
[--output PATH]
[--num-samples N] [--shard-size N] [--seed N]
Flag |
Default |
Description |
|---|---|---|
|
|
Hydra config file (without |
|
current directory |
Hydra config root |
|
off |
Expand comma-separated leaf overrides and dispatch each combination |
|
off |
Validate + plan only; produce no samples |
|
|
Override output directory |
|
|
Override sample count |
|
|
Override shard size |
|
|
Override RNG seed |
Hydra override syntax applies to every config field:
# Swap a config group
rfgen generate channel=sionna_rt_urban
# Override a leaf field
rfgen generate scene.density.max_emitters=50 run.num_samples=100000
# Compose a preset with overrides
rfgen generate +preset=dense_urban_2_4ghz run.num_samples=1000
rfgen annotate¶
Run the annotation pipeline standalone over an already-generated store.
rfgen annotate [HYDRA_OVERRIDES...]
[--config-name NAME] [--config-dir DIR]
The command composes the Phase 2 annotation mapping and dispatches its
validated jobs through the rfgen.commands registry. The bundled
annotation.yaml uses the synchronous local_loop orchestrator; managed
providers use a typed orchestrator_config.resources block.
rfgen validate¶
rfgen validate [CONFIG] [--config-dir DIR] [--config-name NAME]
[--override ITEM] [--check-backends]
Resolves the config, runs all Pydantic validators, and exits with code 0 when
valid or 3 on validation failure. --check-backends additionally resolves the
configured geometry backend through rfgen.backend_capabilities and imports
its complete runtime capability set. Without the flag, validation remains a
pure schema check and does not import optional backends. Failures emit
deterministic redacted JSON.
✓ emitter_zoo (4 families, 12 classes)
✓ channel: sionna_rt
✗ scene.density.max_emitters: 5000 exceeds practical limit (1000)
✓ label.joint
✓ annotator.full_suite
rfgen inspect¶
rfgen inspect STORE_URI [--backend NAME] [--sample-size N]
Examples:
rfgen inspect ./out/run-20260601 --sample-size 3
--sample-size defaults to 3 and accepts 0 through 100. Output is one JSON
object containing report aggregate audit fields and records, a bounded
metadata-only sample. Inspection opens the store read-only and never reads raw
IQ through the metadata iterator.
rfgen list-presets / show-preset¶
rfgen list-presets
# dense_urban_2_4ghz Dense 2.4 GHz ISM, 50 emitters, mixed comms+IoT
# contested_ew_lband L-band radar + jamming, multi-RX
# rural_ads_b Sparse ADS-B over wide-area channel
# device_fingerprint_lora_25 25 LoRa devices, fingerprint-focused
# multimodal_drone_sim Drone telemetry + downlink + spectrum
rfgen show-preset dense_urban_2_4ghz
# (prints fully-resolved YAML)
rfgen list-emitters / list-channels¶
Report the registered plugin surface:
rfgen list-emitters
rfgen list-channels
Both commands emit one JSON object per registered plugin. Emitter rows contain
name, family, classes, and extra; channel rows contain name,
transformation, group, and extra.
Exit codes¶
Code |
Meaning |
|---|---|
0 |
Success |
1 |
Configuration error |
2 |
Runtime command failure |
3 |
Validation failure |
130 |
Keyboard interrupt |