CLI Reference
This page is auto-generated from rtl-buddy --help output.
Run uv run python scripts/gen_cli_reference.py from the repo root to regenerate it.
rtl-buddy
Usage: rtl-buddy [OPTIONS] COMMAND [ARGS]...
╭─ Options ────────────────────────────────────────────────────────────────────────────╮
│ --debug -D Print rtl_buddy debug │
│ details to console │
│ --verbose -v Print execution │
│ details to console │
│ --machine Emit machine-oriented │
│ logs and plain console │
│ output │
│ --color --no-color Logs without ANSI │
│ color codes │
│ [default: color] │
│ --builder-mode -M TEXT Override default │
│ builder_mode │
│ --builder -B TEXT Override platform │
│ default builder │
│ --extra-sim-timeout INTEGER RANGE [x>=0] Seconds to add to │
│ every test's │
│ sim_timeout, │
│ overriding the │
│ builder's │
│ extra-sim-timeout │
│ --early-stop -E [pre|comp|sim|post] Run step to stop early │
│ at │
│ --version Prints version │
│ --install-completion Install completion for │
│ the current shell. │
│ --show-completion Show completion for │
│ the current shell, to │
│ copy it or customize │
│ the installation. │
│ --help Show this message and │
│ exit. │
╰──────────────────────────────────────────────────────────────────────────────────────╯
╭─ Commands ───────────────────────────────────────────────────────────────────────────╮
│ test run a simple test │
│ randtest repeat a test with multiple random seeds │
│ regression run rtl regression │
│ filelist generate filelists using models.yaml │
│ hier render module hierarchy via rtl-buddy-view │
│ hier-query query the module hierarchy via rtl-buddy-view (find-module, │
│ subtree, instances-of, port-connections, source-snippet); JSON on │
│ stdout │
│ mcp serve the design knowledge graph and hierarchy queries over the │
│ Model Context Protocol (stdio); needs the 'mcp' extra │
│ wave open waveform viewer for a test │
│ wave-fpv open SymbiYosys counterexample VCD for a failed FPV verification │
│ nvim-install install/update the unified rtl-buddy-nvim editor plugin (hub + │
│ wave annotation) │
│ wave-install-nvim alias for nvim-install │
│ synth run synthesis │
│ synth-regression run synthesis regression │
│ pnr run place-and-route │
│ power run power analysis │
│ power-regression run power analysis regression │
│ fpga run FPGA implementation (synth + place + route) │
│ fpga-regression run FPGA implementation regression │
│ saif convert FST/VCD trace to SAIF v2.0 │
│ lint run style lint (verible) │
│ lint-regression run style lint regression │
│ fpv run formal property verification │
│ fpv-regression run FPV regression │
│ tool-check check installed tool dependencies and subcommand readiness │
│ graph build the design knowledge graph │
│ cov query coverage artefacts already on disk │
│ axi-profile profile AXI interconnect performance via rtl-buddy-axi-profiler │
│ verible verible commands │
│ mut mutation testing │
│ hub manage the rtl-buddy-hub daemon │
│ skill manage the rtl_buddy agent skill │
│ docs browse bundled documentation │
│ spec spec traceability commands │
│ xplr design-space exploration experiment ledger (agent-facing) │
╰──────────────────────────────────────────────────────────────────────────────────────╯
test
Usage: rtl-buddy test [OPTIONS] [TEST_NAME]...
run a simple test
╭─ Arguments ──────────────────────────────────────────────────────────────────────────╮
│ test_name [TEST_NAME]... names of tests [default: (run all tests)] │
╰──────────────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────────────╮
│ --test-config -c TEXT test_config.yaml to use │
│ [default: tests.yaml] │
│ --list list tests in the selected │
│ test-config and exit │
│ --filter TEXT case-sensitive Python regex matched │
│ against configured test names │
│ --coverage-merge merge coverage across selected │
│ tests; uses raw merge for │
│ summary/html and info-process for │
│ Coverview │
│ --coverage-merge-raw use raw Verilator merge for merged │
│ summary/html/Coverview │
│ --coverage-merge-info-process use info-process merge for merged │
│ summary/Coverview; HTML merge is not │
│ supported │
│ --coverage-html generate merged LCOV HTML output in │
│ coverage_merge.html │
│ --coverage-coverview generate Coverview zip output from │
│ coverage info │
│ --coverage-dir-summary TEXT append coverage summary lines for │
│ repo-relative directory prefixes; │
│ may be repeated │
│ --coverage-dir-summary-file TEXT file containing repo-relative │
│ directory prefixes, one per line │
│ --rnd-new -n use a randomly generated seed │
│ instead of root config seed │
│ --rnd-last -l reuse last generated seed │
│ --share-build reuse one compiled simv across tests │
│ with identical compile inputs │
│ (Verilator builders only) │
│ --rebuild recompile even when a valid build │
│ already exists (implies nothing │
│ about --share-build) │
│ --reg-level INTEGER regression level to stop at │
│ --start-level INTEGER regression level to start at │
│ --dispatch TEXT execution backend for the test run │
│ (local, local-parallel, slurm); │
│ opt-in per run — │
│ cfg-dispatch.backend does not │
│ redirect rb test │
│ [default: (local)] │
│ --jobs -j INTEGER concurrent jobs for --dispatch │
│ local-parallel │
│ [default: (cfg-dispatch jobs, else │
│ min(4, cpu count))] │
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────────────╯
randtest
Usage: rtl-buddy randtest [OPTIONS] TEST_NAME [RND_CNT]
repeat a test with multiple random seeds
╭─ Arguments ──────────────────────────────────────────────────────────────────────────╮
│ * test_name TEXT name of test [default: (run all tests)] [required] │
│ rnd_cnt [RND_CNT] number of random iterations to test [default: 2] │
╰──────────────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────────────╮
│ --test-config -c TEXT test_config.yaml to use [default: tests.yaml] │
│ --rnd-rpt -r INTEGER repeat iteration number from previous run │
│ --rebuild recompile even when a valid build already exists │
│ (implies nothing about --share-build) │
│ --dispatch TEXT execution backend for the seed fan-out (local, │
│ local-parallel, slurm) │
│ [default: (cfg-dispatch backend, else local)] │
│ --jobs -j INTEGER concurrent jobs for --dispatch local-parallel │
│ [default: (cfg-dispatch jobs, else min(4, cpu │
│ count))] │
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────────────╯
regression
Usage: rtl-buddy regression [OPTIONS]
run rtl regression
╭─ Options ────────────────────────────────────────────────────────────────────────────╮
│ --reg-config -c TEXT path to regressions.yaml │
│ [default: (Use ./regression.yaml if │
│ present, otherwise root_config.yaml │
│ reg-cfg-path)] │
│ --reg-level -l INTEGER regression level to stop at │
│ [default: 0] │
│ --start-level -s INTEGER regression level to start at │
│ [default: 0] │
│ --coverage-merge merge coverage across regression │
│ tests; uses raw merge for │
│ summary/html and info-process for │
│ Coverview │
│ --coverage-merge-raw use raw Verilator merge for merged │
│ summary/html/Coverview │
│ --coverage-merge-info-process use info-process merge for merged │
│ summary/Coverview; HTML merge is not │
│ supported │
│ --coverage-html generate merged LCOV HTML output in │
│ coverage_merge.html │
│ --coverage-coverview generate Coverview zip output from │
│ coverage info │
│ --coverage-per-test package one Coverview dataset per │
│ test in regression mode │
│ --coverage-dir-summary TEXT append coverage summary lines for │
│ repo-relative directory prefixes; │
│ may be repeated │
│ --coverage-dir-summary-file TEXT file containing repo-relative │
│ directory prefixes, one per line │
│ --share-build reuse one compiled simv across tests │
│ with identical compile inputs │
│ (Verilator builders only) │
│ --rebuild recompile even when a valid build │
│ already exists (implies nothing │
│ about --share-build) │
│ --dispatch TEXT execution backend for test runs │
│ (local, local-parallel, slurm) │
│ [default: (cfg-dispatch backend, │
│ else local)] │
│ --jobs -j INTEGER concurrent jobs for --dispatch │
│ local-parallel │
│ [default: (cfg-dispatch jobs, else │
│ min(4, cpu count))] │
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────────────╯
filelist
Usage: rtl-buddy filelist [OPTIONS] MODEL_NAME [OUTPUT_PATH]
generate filelists using models.yaml
╭─ Arguments ──────────────────────────────────────────────────────────────────────────╮
│ * model_name TEXT name of model [required] │
│ output_path [OUTPUT_PATH] Output filename [default: run.f] │
╰──────────────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────────────╮
│ --model-config -c TEXT model_config.yaml to use [default: models.yaml] │
│ --unroll -u Recursively unroll -F in filelists │
│ --flatten -f Remove path to a file, leaving just the filename │
│ --strip -s Remove option part of a line │
│ --deduplicate -d Remove duplicates │
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────────────╯
hier
Usage: rtl-buddy hier [OPTIONS] NAME
render module hierarchy via rtl-buddy-view
╭─ Arguments ──────────────────────────────────────────────────────────────────────────╮
│ * name TEXT with --view dut (default): model name from models.yaml; with │
│ --view tb: test name from tests.yaml (the test pins both the │
│ model + the testbench top) │
│ [required] │
╰──────────────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────────────╮
│ --model-config -c TEXT models.yaml to use [default: models.yaml] │
│ --test-config TEXT tests.yaml to use (--view tb) [default: tests.yaml] │
│ --view TEXT what to render: 'dut' (default) renders the model │
│ hierarchy rooted at --top; 'tb' renders the │
│ testbench hierarchy with the DUT called out as a │
│ subtree. With --view tb the positional argument is │
│ a test name. │
│ [default: dut] │
│ --format TEXT output format: tree, dot, mermaid, json │
│ [default: tree] │
│ --output -o TEXT write renderer output to file instead of stdout │
│ --frontend TEXT parser frontend (verible|slang) │
│ --rdc-annotations TEXT reset-domain map JSON from `analysis-tool │
│ --emit-reset-domain-map` │
│ --clock-legend dot format only: emit a side legend of clock colors │
│ --block-diagram dot format only: render sibling dataflow as a block │
│ diagram (cluster nesting + net-labeled edges) │
│ instead of the hierarchy dump; requires │
│ rtl-buddy-sch >= 0.8.0 │
│ --tool TEXT path to the rtl-buddy-view binary │
│ [default: rtl-buddy-view] │
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────────────╯
hier-query
Usage: rtl-buddy hier-query [OPTIONS] NAME VERB ARG
query the module hierarchy via rtl-buddy-view (find-module, subtree, instances-of,
port-connections, source-snippet); JSON on stdout
╭─ Arguments ──────────────────────────────────────────────────────────────────────────╮
│ * name TEXT model name from models.yaml [required] │
│ * verb TEXT query verb: find-module, subtree, instances-of, │
│ port-connections, or source-snippet │
│ [required] │
│ * arg TEXT verb argument: a module name (find-module, instances-of) or a │
│ dot-separated instance path rooted at the model (subtree, │
│ port-connections, source-snippet) │
│ [required] │
╰──────────────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────────────╮
│ --model-config -c TEXT models.yaml to use │
│ [default: models.yaml] │
│ --frontend TEXT parser frontend (verible|slang) │
│ --format TEXT subtree only: json (default) or │
│ tree │
│ --context INTEGER source-snippet only: context lines │
│ on each side │
│ --line-numbers --no-line-numbers source-snippet only: prefix lines │
│ with source line numbers (default │
│ on) │
│ [default: line-numbers] │
│ --tool TEXT path to the rtl-buddy-view binary │
│ [default: rtl-buddy-view] │
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────────────╯
mcp
Usage: rtl-buddy mcp [OPTIONS]
serve the design knowledge graph and hierarchy queries over the Model Context Protocol
(stdio); needs the 'mcp' extra
╭─ Options ────────────────────────────────────────────────────────────────────────────╮
│ --graph TEXT graph.json to serve (default <project │
│ root>/artefacts/graph) │
│ --overlay TEXT results-overlay.json to join │
│ --root TEXT project root to serve; default is discovered from cwd, │
│ which is what an agent host's spawn gives you │
│ --design-dir TEXT directory searched for models.yaml │
│ --frontend TEXT viewer parser frontend (verible|slang) │
│ --tool TEXT path to the rtl-buddy-view binary │
│ [default: rtl-buddy-view] │
│ --list-tools print the tool schemas and exit instead of serving │
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────────────╯
wave
Usage: rtl-buddy wave [OPTIONS] TEST_NAME
open waveform viewer for a test
╭─ Arguments ──────────────────────────────────────────────────────────────────────────╮
│ * test_name TEXT name of test to open waveform for [required] │
╰──────────────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────────────╮
│ --test-config -c TEXT tests.yaml to use [default: tests.yaml] │
│ --surfer TEXT cfg-surfer entry name (default: the active │
│ platform's cfg-platforms surfer routing, else │
│ surfer-default) │
│ --resim force re-run of debug sim even if FST exists │
│ --focused-signal annotate only the signal selected via Go to │
│ declaration; default annotates all signals in scope │
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────────────╯
wave-fpv
Usage: rtl-buddy wave-fpv [OPTIONS] VERIF_NAME
open SymbiYosys counterexample VCD for a failed FPV verification
╭─ Arguments ──────────────────────────────────────────────────────────────────────────╮
│ * verif_name TEXT name of FPV verification to open CEX for [required] │
╰──────────────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────────────╮
│ --fpv-config -c TEXT fpv.yaml to use [default: fpv.yaml] │
│ --surfer TEXT cfg-surfer entry name (default: the active platform's │
│ cfg-platforms surfer routing, else surfer-default) │
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────────────╯
nvim-install
Usage: rtl-buddy nvim-install [OPTIONS]
install/update the unified rtl-buddy-nvim editor plugin (hub + wave annotation)
╭─ Options ────────────────────────────────────────────────────────────────────────────╮
│ --force remove any existing install and re-clone │
│ --update sync an existing install to the pinned revision │
│ --ref TEXT override the pinned rtl-buddy-nvim git ref (tag/branch) │
│ --source TEXT override the rtl-buddy-nvim repo URL or local path (for │
│ offline/dev installs) │
│ --no-lsp omit the verible-verilog-ls autostart from the managed setup │
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────────────╯
synth
Usage: rtl-buddy synth [OPTIONS] [SYNTH_NAME]
run synthesis
╭─ Arguments ──────────────────────────────────────────────────────────────────────────╮
│ synth_name [SYNTH_NAME] name of synthesis to run │
│ [default: (run all syntheses)] │
╰──────────────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────────────╮
│ --synth-config -c TEXT synth.yaml to use [default: synth.yaml] │
│ --list list syntheses in the selected config and exit │
│ --effort TEXT override synthesis effort (must match │
│ cfg-synth-efforts entry) │
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────────────╯
synth-regression
Usage: rtl-buddy synth-regression [OPTIONS]
run synthesis regression
╭─ Options ────────────────────────────────────────────────────────────────────────────╮
│ --reg-config -c TEXT path to synth_regression.yaml │
│ [default: (Use ./synth_regression.yaml if present, │
│ otherwise root_config.yaml synth-reg-cfg-path)] │
│ --reg-level -l INTEGER synthesis regression level to stop at [default: 0] │
│ --effort TEXT override synthesis effort (must match │
│ cfg-synth-efforts entry) │
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────────────╯
pnr
Usage: rtl-buddy pnr [OPTIONS] [PNR_NAME]
run place-and-route
╭─ Arguments ──────────────────────────────────────────────────────────────────────────╮
│ pnr_name [PNR_NAME] name of pnr run │
│ [default: (run all entries in the suite)] │
╰──────────────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────────────╮
│ --pnr-config -c TEXT pnr.yaml to use [default: pnr.yaml] │
│ --list list pnr runs in the selected config and exit │
│ --reg-level -l INTEGER run only entries with reglvl at or below this value │
│ [default: 0] │
│ --gds stream out GDS via KLayout after a successful P&R │
│ --png render a PNG of the routed GDS via KLayout (implies │
│ --gds) │
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────────────╯
power
Usage: rtl-buddy power [OPTIONS] [POWER_NAME]
run power analysis
╭─ Arguments ──────────────────────────────────────────────────────────────────────────╮
│ power_name [POWER_NAME] name of power run │
│ [default: (run all entries in the suite)] │
╰──────────────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────────────╮
│ --power-config -c TEXT power.yaml to use [default: power.yaml] │
│ --list list power runs in the selected config and exit │
│ --reg-level -l INTEGER run only entries with reglvl at or below this value │
│ [default: 0] │
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────────────╯
power-regression
Usage: rtl-buddy power-regression [OPTIONS]
run power analysis regression
╭─ Options ────────────────────────────────────────────────────────────────────────────╮
│ --reg-config -c TEXT path to power_regression.yaml │
│ [default: (Use ./power_regression.yaml if present, │
│ otherwise root_config.yaml power-reg-cfg-path)] │
│ --reg-level -l INTEGER power regression level to stop at [default: 0] │
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────────────╯
fpga
Usage: rtl-buddy fpga [OPTIONS] [FPGA_NAME]
run FPGA implementation (synth + place + route)
╭─ Arguments ──────────────────────────────────────────────────────────────────────────╮
│ fpga_name [FPGA_NAME] name of fpga run │
│ [default: (run all entries in the suite)] │
╰──────────────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────────────╮
│ --fpga-config -c TEXT fpga.yaml to use [default: fpga.yaml] │
│ --list list fpga runs in the selected config and exit │
│ --reg-level -l INTEGER run only entries with reglvl at or below this value │
│ [default: 0] │
│ --bitstream generate a bitstream after route (write_bitstream); │
│ off by default — a smoke/timing run doesn't need │
│ bitgen │
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────────────╯
fpga-regression
Usage: rtl-buddy fpga-regression [OPTIONS]
run FPGA implementation regression
╭─ Options ────────────────────────────────────────────────────────────────────────────╮
│ --reg-config -c TEXT path to fpga_regression.yaml │
│ [default: (Use ./fpga_regression.yaml if present, │
│ otherwise root_config.yaml fpga-reg-cfg-path)] │
│ --reg-level -l INTEGER FPGA regression level to stop at [default: 0] │
│ --bitstream generate bitstreams after route (write_bitstream); │
│ off by default — a smoke/timing regression doesn't │
│ need bitgen │
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────────────╯
saif
Usage: rtl-buddy saif [OPTIONS] TRACE OUTPUT
convert FST/VCD trace to SAIF v2.0
╭─ Arguments ──────────────────────────────────────────────────────────────────────────╮
│ * trace TEXT path to input FST or VCD trace [required] │
│ * output TEXT path to write SAIF v2.0 file [required] │
╰──────────────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────────────╮
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────────────╯
lint
Usage: rtl-buddy lint [OPTIONS] [LINT_NAME]
run style lint (verible)
╭─ Arguments ──────────────────────────────────────────────────────────────────────────╮
│ lint_name [LINT_NAME] name of lint check to run [default: (run all checks)] │
╰──────────────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────────────╮
│ --lint-config -c TEXT lint.yaml to use [default: lint.yaml] │
│ --list list checks in the selected config and exit │
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────────────╯
lint-regression
Usage: rtl-buddy lint-regression [OPTIONS]
run style lint regression
╭─ Options ────────────────────────────────────────────────────────────────────────────╮
│ --reg-config -c TEXT path to lint_regression.yaml │
│ [default: (Use ./lint_regression.yaml if present, │
│ otherwise root_config.yaml lint-reg-cfg-path)] │
│ --reg-level -l INTEGER lint regression level to stop at [default: 0] │
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────────────╯
fpv
Usage: rtl-buddy fpv [OPTIONS] [FPV_NAME]
run formal property verification
╭─ Arguments ──────────────────────────────────────────────────────────────────────────╮
│ fpv_name [FPV_NAME] name of FPV verification to run │
│ [default: (run all verifications)] │
╰──────────────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────────────╮
│ --fpv-config -c TEXT fpv.yaml to use [default: fpv.yaml] │
│ --list list verifications in the selected config and exit │
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────────────╯
fpv-regression
Usage: rtl-buddy fpv-regression [OPTIONS]
run FPV regression
╭─ Options ────────────────────────────────────────────────────────────────────────────╮
│ --reg-config -c TEXT path to fpv_regression.yaml │
│ [default: (Use ./fpv_regression.yaml if present, │
│ otherwise root_config.yaml fpv-reg-cfg-path)] │
│ --reg-level -l INTEGER FPV regression level to stop at [default: 0] │
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────────────╯
tool-check
Usage: rtl-buddy tool-check [OPTIONS]
check installed tool dependencies and subcommand readiness
╭─ Options ────────────────────────────────────────────────────────────────────────────╮
│ --format TEXT text | json [default: text] │
│ --required-for TEXT check only what `rb │
│ <subcommand>` needs │
│ --explain TEXT show install instructions for a │
│ single tool and exit │
│ --strict exit non-zero if any required │
│ tool is missing/outdated │
│ --include-optional --no-include-optional include optional tools │
│ (default: yes) │
│ [default: include-optional] │
│ --probe-versions --no-probe-versions run `<tool> --version` to │
│ capture installed version │
│ (default: yes) │
│ [default: probe-versions] │
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────────────╯
graph
Usage: rtl-buddy graph [OPTIONS] COMMAND [ARGS]...
build the design knowledge graph
╭─ Options ────────────────────────────────────────────────────────────────────────────╮
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────────────╯
╭─ Commands ───────────────────────────────────────────────────────────────────────────╮
│ build extract every tier and merge them into artefacts/graph/graph.json │
│ results refresh artefacts/graph/results-overlay.json — last status, seed and │
│ artefact paths per test node; graph.json is not touched │
│ query keyword search over graph.json with neighbourhood expansion and the results │
│ overlay joined in │
│ path shortest chain of edges between two graph nodes │
│ explain one node's attributes, every edge on it, and its last result │
╰──────────────────────────────────────────────────────────────────────────────────────╯
graph build
Usage: rtl-buddy graph build [OPTIONS]
extract every tier and merge them into artefacts/graph/graph.json
╭─ Options ────────────────────────────────────────────────────────────────────────────╮
│ --model TEXT model name to export in │
│ the design tier; │
│ repeatable. Default: │
│ every model declared │
│ under --design-dir │
│ --regression -c TEXT regression.yaml whose │
│ suites pin the models to │
│ export (mutually │
│ exclusive with --model) │
│ --spec-dir TEXT directory searched for │
│ specs.yaml │
│ --verif-dir TEXT directory searched for │
│ tests.yaml │
│ --design-dir TEXT directory searched for │
│ models.yaml │
│ --out-dir -o TEXT output directory │
│ (default: <project │
│ root>/artefacts/graph) │
│ --frontend TEXT viewer parser frontend │
│ (verible|slang) │
│ --design --no-design run the rtl-buddy-view │
│ design tier (default on) │
│ [default: design] │
│ --tb --no-tb also export each │
│ testbench's own │
│ hierarchy, rooted at its │
│ toplevel: (default on; │
│ --no-tb is DUT-only) │
│ [default: tb] │
│ --flow-tops --no-flow-tops also export each │
│ formal/synth/cdc run's │
│ top over the flow's own │
│ filelist when it is not │
│ the model top (default │
│ on) │
│ [default: flow-tops] │
│ --bind --no-bind run the post-merge │
│ binding stage that ties │
│ cocotb tests to the DUT │
│ hierarchy (default on) │
│ [default: bind] │
│ --extract --no-extract run the binding tier │
│ when the extractor │
│ (rtl-buddy-graph-extrac… │
│ is installed │
│ [default: extract] │
│ --extract-cross-check --no-extract-cross-che… cross-check the internal │
│ merge against the │
│ extractor's │
│ `merge-graphs` when it │
│ is installed │
│ [default: │
│ extract-cross-check] │
│ --force rebuild even when no │
│ input changed │
│ --strict exit non-zero on any │
│ per-item failure, not │
│ just a dead tier │
│ --tool TEXT path to the │
│ rtl-buddy-view binary │
│ [default: │
│ rtl-buddy-view] │
│ --help Show this message and │
│ exit. │
╰──────────────────────────────────────────────────────────────────────────────────────╯
graph results
Usage: rtl-buddy graph results [OPTIONS]
refresh artefacts/graph/results-overlay.json — last status, seed and artefact paths
per test node; graph.json is not touched
╭─ Options ────────────────────────────────────────────────────────────────────────────╮
│ --verif-dir TEXT directory searched for tests.yaml │
│ --out-dir -o TEXT output directory (default: <project │
│ root>/artefacts/graph) │
│ --graph TEXT graph.json to cross-check ids against (default: │
│ <out-dir>/graph.json); read, never written │
│ --strict exit non-zero when an envelope could not be read, a │
│ test node has no result, or a result matches no node │
│ --coverage TEXT coverage source to join onto the graph's ids: 'auto' │
│ (cov_dir/manifest.json, then the per-test coverage.dat │
│ databases this scan finds), 'model' (the manifest │
│ only), 'none', or a path to a merged LCOV .info file; │
│ nothing is re-run │
│ [default: auto] │
│ --no-coverage skip the coverage join (same as --coverage none) │
│ --cov-dir TEXT coverage artefact directory to join from (default: the │
│ newest cov_dir/ under the project) │
│ --cov-manifest TEXT coverage manifest.json to join from, instead of │
│ discovery │
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────────────╯
graph query
Usage: rtl-buddy graph query [OPTIONS] QUESTION
keyword search over graph.json with neighbourhood expansion and the results overlay
joined in
╭─ Arguments ──────────────────────────────────────────────────────────────────────────╮
│ * question TEXT what to look for — an identifier or a plain question, e.g. │
│ "A-COV-1" or "which tests exercise blk_a" │
│ [required] │
╰──────────────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────────────╮
│ --type TEXT restrict to one node type (module, test, │
│ coverage_item, ...) │
│ --tier TEXT restrict to one tier │
│ (design|config|binding) │
│ --limit INTEGER maximum matches to report [default: 10] │
│ --depth INTEGER hops of neighbourhood expansion around │
│ each match (0 disables; maximum 3) │
│ [default: 1] │
│ --max-neighbors INTEGER neighbours reported per match; anything │
│ beyond is counted in neighbors_truncated │
│ rather than dropped silently │
│ [default: 25] │
│ --results --no-results join the regression-results overlay onto │
│ every node │
│ [default: results] │
│ --expand full node summaries for every neighbour │
│ instead of the lean id/label/type │
│ references │
│ --graph TEXT graph.json to query (default <project │
│ root>/artefacts/graph) │
│ --overlay TEXT results-overlay.json to join (default: │
│ beside graph.json) │
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────────────╯
graph path
Usage: rtl-buddy graph path [OPTIONS] SOURCE TARGET
shortest chain of edges between two graph nodes
╭─ Arguments ──────────────────────────────────────────────────────────────────────────╮
│ * source TEXT start node id, or a bare unambiguous name [required] │
│ * target TEXT end node id, or a bare unambiguous name [required] │
╰──────────────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────────────╮
│ --directed --undirected follow edge direction; undirected by default │
│ because edge direction encodes role, not │
│ reachability │
│ [default: undirected] │
│ --max-paths INTEGER shortest paths to report [default: 3] │
│ --results --no-results join the regression-results overlay onto │
│ every node │
│ [default: results] │
│ --graph TEXT graph.json to query │
│ --overlay TEXT results-overlay.json to join │
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────────────╯
graph explain
Usage: rtl-buddy graph explain [OPTIONS] NODE
one node's attributes, every edge on it, and its last result
╭─ Arguments ──────────────────────────────────────────────────────────────────────────╮
│ * node TEXT node id, or a bare unambiguous name [required] │
╰──────────────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────────────╮
│ --results --no-results join the regression-results overlay onto every │
│ node │
│ [default: results] │
│ --expand full node summaries for every edge peer instead │
│ of the lean id/label/type references │
│ --graph TEXT graph.json to query │
│ --overlay TEXT results-overlay.json to join │
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────────────╯
cov
Usage: rtl-buddy cov [OPTIONS] COMMAND [ARGS]...
query coverage artefacts already on disk
╭─ Options ────────────────────────────────────────────────────────────────────────────╮
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────────────╯
╭─ Commands ───────────────────────────────────────────────────────────────────────────╮
│ summary run-level and per-test scalars, coldest files first │
│ module per-file, per-point coverage for one module's sources │
╰──────────────────────────────────────────────────────────────────────────────────────╯
cov summary
Usage: rtl-buddy cov summary [OPTIONS]
run-level and per-test scalars, coldest files first
╭─ Options ────────────────────────────────────────────────────────────────────────────╮
│ --limit INTEGER files to report, coldest first (0 for all) [default: 20] │
│ --cov-dir TEXT coverage artefact directory to read │
│ [default: (newest cov_dir under the project root)] │
│ --manifest TEXT manifest.json to read directly │
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────────────╯
cov module
Usage: rtl-buddy cov module [OPTIONS] MODULE
per-file, per-point coverage for one module's sources
╭─ Arguments ──────────────────────────────────────────────────────────────────────────╮
│ * module TEXT module name as the coverage model records it [required] │
╰──────────────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────────────╮
│ --cold --all list only the points with no hits [default: cold] │
│ --limit INTEGER points to list per metric (0 for all) [default: 20] │
│ --cov-dir TEXT coverage artefact directory to read │
│ [default: (newest cov_dir under the project root)] │
│ --manifest TEXT manifest.json to read directly │
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────────────╯
axi-profile
Usage: rtl-buddy axi-profile [OPTIONS] COMMAND [ARGS]...
profile AXI interconnect performance via rtl-buddy-axi-profiler
╭─ Options ────────────────────────────────────────────────────────────────────────────╮
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────────────╯
╭─ Commands ───────────────────────────────────────────────────────────────────────────╮
│ run ingest a test's FST and emit per-test axi-perf.json │
│ discover parse RTL to (re)generate the model's axi-bundles.yaml manifest │
│ gen-monitor emit the SV bind-style AXI monitor for the model's testbench │
│ notebook launch the packaged marimo notebook against a test's per-txn parquet │
╰──────────────────────────────────────────────────────────────────────────────────────╯
axi-profile run
Usage: rtl-buddy axi-profile run [OPTIONS] TEST_NAME
ingest a test's FST and emit per-test axi-perf.json
╭─ Arguments ──────────────────────────────────────────────────────────────────────────╮
│ * test_name TEXT test from tests.yaml [required] │
╰──────────────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────────────╮
│ --test-config -c TEXT tests.yaml to use [default: tests.yaml] │
│ --output -o TEXT output path for axi-perf.json (default: │
│ artefacts/axi/<test>/axi-perf.json) │
│ --tb-prefix TEXT Override the testbench top scope name used │
│ as the hierarchical prefix in the FST. │
│ Default is the test's tb name from │
│ tests.yaml. Pass empty string to disable. │
│ --emit-txns-parquet Also emit a per-transaction parquet artifact │
│ at artefacts/axi/<test>/axi-txns.parquet — │
│ the canonical location `rb axi-profile │
│ notebook` reads. Requires the axi-profiler │
│ extra (pyarrow). │
│ --emit-txns-parquet-path TEXT Explicit path for the per-transaction │
│ parquet artefact. Implies │
│ --emit-txns-parquet. │
│ --tool TEXT path to the axi-profiler binary │
│ [default: axi-profiler] │
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────────────╯
axi-profile discover
Usage: rtl-buddy axi-profile discover [OPTIONS] MODEL_NAME
parse RTL to (re)generate the model's axi-bundles.yaml manifest
╭─ Arguments ──────────────────────────────────────────────────────────────────────────╮
│ * model_name TEXT model from models.yaml [required] │
╰──────────────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────────────╮
│ --model-config -c TEXT models.yaml to use [default: models.yaml] │
│ --output -o TEXT output path for axi-bundles.yaml (default: the model's │
│ `axi_bundles:` from models.yaml when set, else │
│ artefacts/axi/<model>/axi-bundles.yaml) │
│ --amend TEXT existing axi-bundles.yaml to merge user edits from │
│ (deferred to a follow-up; warns if passed) │
│ --tool TEXT path to the axi-profiler binary │
│ [default: axi-profiler] │
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────────────╯
axi-profile gen-monitor
Usage: rtl-buddy axi-profile gen-monitor [OPTIONS] MODEL_NAME
emit the SV bind-style AXI monitor for the model's testbench
╭─ Arguments ──────────────────────────────────────────────────────────────────────────╮
│ * model_name TEXT model from models.yaml [required] │
╰──────────────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────────────╮
│ --model-config -c TEXT models.yaml to use [default: models.yaml] │
│ --output -o TEXT output path for the generated SV monitor │
│ (default: the model's `axi_monitor_out:` from │
│ models.yaml) │
│ --time-precision TEXT IEEE-1800 timeprecision atom (1ns / 100ps / 1ps / │
│ ...). Must match the testbench's `timeprecision. │
│ --buffer-cap INTEGER Per-bundle FIFO depth cap. Drained only at │
│ $finish. │
│ --tool TEXT path to the axi-profiler binary │
│ [default: axi-profiler] │
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────────────╯
axi-profile notebook
Usage: rtl-buddy axi-profile notebook [OPTIONS] TEST_NAME
launch the packaged marimo notebook against a test's per-txn parquet
╭─ Arguments ──────────────────────────────────────────────────────────────────────────╮
│ * test_name TEXT test from tests.yaml [required] │
╰──────────────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────────────╮
│ --test-config -c TEXT tests.yaml to use [default: tests.yaml] │
│ --port INTEGER TCP port for marimo's edit server (default: │
│ OS-assigned) │
│ --foreground --daemon Run marimo in the foreground (default). │
│ --daemon is accepted for compatibility and │
│ also runs in the foreground. │
│ [default: foreground] │
│ --headless Forward `--headless --no-token` to marimo │
│ for hub launches. The hub opens the URL, and │
│ the handoff is loopback-only. │
│ --marimo TEXT path to the marimo binary (default: 'marimo' │
│ on PATH) │
│ [default: marimo] │
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────────────╯
verible
Usage: rtl-buddy verible [OPTIONS] COMMAND [ARGS]...
verible commands
╭─ Options ────────────────────────────────────────────────────────────────────────────╮
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────────────╯
╭─ Commands ───────────────────────────────────────────────────────────────────────────╮
│ lint run verible-verilog-lint │
│ syntax run verible-verilog-syntax │
│ format run verible-verilog-format │
│ preprocessor run verible-verilog-preprocessor │
│ filelist generate verible.filelist from models.yaml so verible-verilog-ls can │
│ resolve cross-file symbols │
╰──────────────────────────────────────────────────────────────────────────────────────╯
verible lint
Usage: rtl-buddy verible lint [OPTIONS] [VERIBLE_ARGS]...
run verible-verilog-lint
╭─ Arguments ──────────────────────────────────────────────────────────────────────────╮
│ verible_args [VERIBLE_ARGS]... │
╰──────────────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────────────╮
│ --model TEXT Model name from models.yaml whose filelist supplies the files │
│ to visit (repeatable). Bare source entries only: -v/-y │
│ library files and +incdir+/+define+/+libext+ directives are │
│ dropped, then the cfg-verible `exclude` globs and --exclude │
│ filter the rest. │
│ --exclude TEXT Glob of project-root-relative paths dropped from --model │
│ expansion (repeatable, fnmatch semantics: * also crosses │
│ directory separators). Adds to the cfg-verible `exclude` │
│ list. │
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────────────╯
verible syntax
Usage: rtl-buddy verible syntax [OPTIONS] [VERIBLE_ARGS]...
run verible-verilog-syntax
╭─ Arguments ──────────────────────────────────────────────────────────────────────────╮
│ verible_args [VERIBLE_ARGS]... │
╰──────────────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────────────╮
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────────────╯
verible format
Usage: rtl-buddy verible format [OPTIONS] [VERIBLE_ARGS]...
run verible-verilog-format
╭─ Arguments ──────────────────────────────────────────────────────────────────────────╮
│ verible_args [VERIBLE_ARGS]... │
╰──────────────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────────────╮
│ --model TEXT Model name from models.yaml whose filelist supplies the files │
│ to visit (repeatable). Bare source entries only: -v/-y │
│ library files and +incdir+/+define+/+libext+ directives are │
│ dropped, then the cfg-verible `exclude` globs and --exclude │
│ filter the rest. │
│ --exclude TEXT Glob of project-root-relative paths dropped from --model │
│ expansion (repeatable, fnmatch semantics: * also crosses │
│ directory separators). Adds to the cfg-verible `exclude` │
│ list. │
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────────────╯
verible preprocessor
Usage: rtl-buddy verible preprocessor [OPTIONS] [VERIBLE_ARGS]...
run verible-verilog-preprocessor
╭─ Arguments ──────────────────────────────────────────────────────────────────────────╮
│ verible_args [VERIBLE_ARGS]... │
╰──────────────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────────────╮
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────────────╯
verible filelist
Usage: rtl-buddy verible filelist [OPTIONS]
generate verible.filelist from models.yaml so verible-verilog-ls can resolve
cross-file symbols
╭─ Options ────────────────────────────────────────────────────────────────────────────╮
│ --model TEXT Model name(s) to include. May be repeated. Default: union of │
│ every model declared in any models.yaml under the project │
│ root. │
│ --output -o TEXT Output path. Defaults to <project_root>/verible.filelist so │
│ verible-verilog-ls auto-discovers it. │
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────────────╯
mut
Usage: rtl-buddy mut [OPTIONS] COMMAND [ARGS]...
mutation testing
╭─ Options ────────────────────────────────────────────────────────────────────────────╮
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────────────╯
╭─ Commands ───────────────────────────────────────────────────────────────────────────╮
│ list enumerate mutation candidate sites without mutating │
│ run generate mutants, score against an FPV proof, report │
│ score recompute mutation score from a saved report │
╰──────────────────────────────────────────────────────────────────────────────────────╯
mut list
Usage: rtl-buddy mut list [OPTIONS]
enumerate mutation candidate sites without mutating
╭─ Options ────────────────────────────────────────────────────────────────────────────╮
│ --mut-config -c TEXT mut.yaml to use [default: mut.yaml] │
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────────────╯
mut run
Usage: rtl-buddy mut run [OPTIONS]
generate mutants, score against an FPV proof, report
╭─ Options ────────────────────────────────────────────────────────────────────────────╮
│ --mut-config -c TEXT mut.yaml to use [default: mut.yaml] │
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────────────╯
mut score
Usage: rtl-buddy mut score [OPTIONS] REPORT
recompute mutation score from a saved report
╭─ Arguments ──────────────────────────────────────────────────────────────────────────╮
│ * report TEXT path to a mut_report.json from a previous run [required] │
╰──────────────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────────────╮
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────────────╯
hub
Usage: rtl-buddy hub [OPTIONS] COMMAND [ARGS]...
manage the rtl-buddy-hub daemon
╭─ Options ────────────────────────────────────────────────────────────────────────────╮
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────────────╯
╭─ Commands ───────────────────────────────────────────────────────────────────────────╮
│ start start the rtl-buddy-hub daemon for this project │
│ stop ask the running hub to shut down │
│ status print the running hub's discovery record │
│ log tail the hub log │
│ install-launchagent install the macOS LaunchAgent so the hub auto-starts at login │
│ uninstall-launchagent remove the macOS LaunchAgent │
│ config hub.toml utilities │
│ send One-shot peer for the running rtl-buddy-hub. Connects as │
│ origin=cli. │
╰──────────────────────────────────────────────────────────────────────────────────────╯
hub start
Usage: rtl-buddy hub start [OPTIONS]
start the rtl-buddy-hub daemon for this project
╭─ Options ────────────────────────────────────────────────────────────────────────────╮
│ --foreground --daemon Run in the foreground │
│ (default). --daemon │
│ detaches the hub into │
│ its own session, │
│ redirects its output │
│ to hub.log, and │
│ returns as soon as │
│ .rtl-buddy/hub.json │
│ is published. │
│ [default: foreground] │
│ --serve-viewer --no-serve-viewer Also serve the viewer │
│ HTTP+WebSocket layer │
│ at the http_port. │
│ When no │
│ --viewer-bundle is │
│ given, the hub │
│ auto-discovers the │
│ SPA shipped by │
│ rtl-buddy-view (if │
│ installed) and falls │
│ back to a placeholder │
│ page if neither is │
│ available. │
│ [default: │
│ no-serve-viewer] │
│ --viewer-bundle PATH Override the │
│ auto-discovered SPA │
│ with this path │
│ (directory containing │
│ index.html, or a path │
│ to a single │
│ index.html). Use this │
│ when iterating on the │
│ SPA from a checkout — │
│ the auto-discovered │
│ bundle ships with the │
│ installed wheel and │
│ won't reflect │
│ uncommitted viewer/ │
│ changes. Only used │
│ with --serve-viewer. │
│ --listen-port INTEGER RANGE TCP port for adapter │
│ [0<=x<=65535] peers (nvim, rb │
│ wave). Overrides │
│ .listen_port from │
│ hub.toml. 0 = │
│ OS-assigned. Pin to a │
│ specific number so │
│ peers' discovery │
│ records stay stable │
│ across restarts. │
│ --http-port INTEGER RANGE HTTP/WS port for the │
│ [0<=x<=65535] browser-side SPA. │
│ Overrides .http_port │
│ from hub.toml. 0 = │
│ OS-assigned. Pin to a │
│ specific number so │
│ the SPA URL stays the │
│ same across restarts. │
│ Only used with │
│ --serve-viewer. │
│ --model TEXT Generate view.json on │
│ hub start for this │
│ model name (looked up │
│ in models.yaml), │
│ avoiding a separate │
│ `rb hier` invocation. │
│ When unset the hub │
│ falls back to │
│ .view_json from │
│ hub.toml. Requires │
│ --serve-viewer. │
│ --models-file PATH Explicit models.yaml │
│ that owns the --model │
│ entry. Skips the │
│ project-tree │
│ discovery walk. Use │
│ this to disambiguate │
│ when the same model │
│ name exists in more │
│ than one models.yaml. │
│ --axi-perf-from PATH Path to an │
│ axi-perf.json (output │
│ of `rb axi-profile │
│ run`). The hub bakes │
│ its │
│ per-bundle/interconn… │
│ throughput overlay │
│ into every generated │
│ view.json AND records │
│ the source's │
│ test/suite_dir so the │
│ SPA's 'Open in │
│ marimo' button skips │
│ its prompt. Use the │
│ canonical │
│ <suite>/artefacts/ax… │
│ layout so the │
│ test/suite_dir │
│ derivation lands. │
│ Only used with │
│ --serve-viewer. │
│ --help Show this message and │
│ exit. │
╰──────────────────────────────────────────────────────────────────────────────────────╯
hub stop
Usage: rtl-buddy hub stop [OPTIONS]
ask the running hub to shut down
╭─ Options ────────────────────────────────────────────────────────────────────────────╮
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────────────╯
hub status
Usage: rtl-buddy hub status [OPTIONS]
print the running hub's discovery record
╭─ Options ────────────────────────────────────────────────────────────────────────────╮
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────────────╯
hub log
Usage: rtl-buddy hub log [OPTIONS]
tail the hub log
╭─ Options ────────────────────────────────────────────────────────────────────────────╮
│ --lines -n INTEGER Trailing lines to print before following. │
│ [default: 50] │
│ -f --no-follow Follow the log (tail -f). [default: no-follow] │
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────────────╯
hub install-launchagent
Usage: rtl-buddy hub install-launchagent [OPTIONS]
install the macOS LaunchAgent so the hub auto-starts at login
╭─ Options ────────────────────────────────────────────────────────────────────────────╮
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────────────╯
hub uninstall-launchagent
Usage: rtl-buddy hub uninstall-launchagent [OPTIONS]
remove the macOS LaunchAgent
╭─ Options ────────────────────────────────────────────────────────────────────────────╮
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────────────╯
hub config
Usage: rtl-buddy hub config [OPTIONS] COMMAND [ARGS]...
hub.toml utilities
╭─ Options ────────────────────────────────────────────────────────────────────────────╮
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────────────╯
╭─ Commands ───────────────────────────────────────────────────────────────────────────╮
│ validate schema-check .rtl-buddy/hub.toml │
╰──────────────────────────────────────────────────────────────────────────────────────╯
hub config validate
Usage: rtl-buddy hub config validate [OPTIONS]
schema-check .rtl-buddy/hub.toml
╭─ Options ────────────────────────────────────────────────────────────────────────────╮
│ --path PATH Override the default project hub.toml path. │
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────────────╯
hub send
Usage: rtl-buddy hub send [OPTIONS] COMMAND [ARGS]...
One-shot peer for the running rtl-buddy-hub. Connects as origin=cli.
╭─ Options ────────────────────────────────────────────────────────────────────────────╮
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────────────╯
╭─ Commands ───────────────────────────────────────────────────────────────────────────╮
│ select Broadcast selection_changed{instance_path}. │
│ signal Broadcast signal_selected{signal, wave_scope}. │
│ cursor Broadcast cursor_time_changed{t_fs}. │
│ scope Broadcast scope_changed{wave_scope}. │
│ open Broadcast source_focused{file, line, col}. │
│ graph-focus Broadcast graph_focus{node} — point the hub's design knowledge graph │
│ pane (http://127.0.0.1:<http_port>/gph) at one node of │
│ artefacts/graph/graph.json. NODE is a graph node id: 'module:fifo', │
│ 'inst:top/top.u_fifo', 'test:verif/dma#smoke', │
│ 'covitem:dma#DMA-COV-1' — the vocabulary `rb graph query` returns and │
│ docs/concepts/graph.md lists. The hub caches the focus and replays it │
│ to the pane on connect, so sending this before the browser tab is │
│ open works. │
│ cov-focus Broadcast cov_focus{target} — point the hub's coverage pane │
│ (http://127.0.0.1:<http_port>/cov) at one target of the run's │
│ coverage model. TARGET is prefixed: 'file:design/blk.sv', │
│ 'module:blk', or 'test:verif/blk#basic'; an unprefixed string is read │
│ as a file path. --metric foregrounds one coverage kind, --line │
│ scrolls a file target to a line, and --item names a │
│ branch/toggle/expression bin or an SVA cover point. The hub caches │
│ the focus and replays it to the pane on connect, so sending this │
│ before the browser tab is open works. │
│ diagnose Push a diagnostics_set bundle for SOURCE. Each ITEM is │
│ <file>:<line>:<severity>:<code>:<message>. --clear sends an empty set │
│ (clears any cached diagnostics from SOURCE). Use --instance to attach │
│ a view.json instance_path hint that consumers (the SPA's on-canvas │
│ badge layer in particular) use as a fast path instead of the │
│ file+line resolver. │
│ state Snapshot the hub's cached state (active model, selection, cursor, │
│ scope, peers). │
│ wave-add Ask the wave peer (surfer) to add one or more signals to the view. │
│ wave-cursor Ask the wave peer (surfer) to move its cursor to T_FS. │
│ wave-scope Ask the wave peer (surfer) to switch its active scope without │
│ populating the variable panel (maps to WCP set_scope). │
│ wave-pan Pan surfer's viewport to center on T_FS (zoom unchanged). Maps to WCP │
│ set_viewport_to. │
│ wave-zoom Zoom + pan surfer to fit [START_FS, END_FS]. Maps to WCP │
│ set_viewport_range. │
│ wave-zoom-fit Zoom surfer out to fit the whole waveform. Maps to WCP zoom_to_fit. │
│ wave-items List the items currently in surfer's wave view (id, type, name). Maps │
│ to WCP get_item_list + get_item_info. │
│ wave-remove Ask the wave peer (surfer) to remove items by id. IDs come from │
│ wave-add / wave-items. Reports removed vs not_found. │
│ wave-move Reorder items in surfer's view. Move the given IDS (in the order │
│ listed) so the block starts at --to INDEX, or just before --before │
│ ID. Exactly one of --to / --before is required. │
│ wave-comment Add comment rows (named dividers) to surfer's view. Returns the new │
│ item ids. Maps to WCP add_dividers. │
│ view-pan Ask the schematic (rtl-buddy-sch) to pan/center on INSTANCE_PATH. │
│ overlay Flip an overlay's enabled state on the SPA. Built-in NAMES are │
│ 'clock', 'reset', 'axi-perf', 'wave'; an unknown name is a no-op. Use │
│ --on / --off (default --on). Useful for agents or scripted demos that │
│ want to direct the user's attention to a specific overlay layer │
│ without a UI click. │
│ capture Ask the schematic (rtl-buddy-sch) to snapshot the current graph and │
│ write it to --out. Graph-only — surrounding panels are not captured. │
│ Useful for agents that want to look at what the user is seeing │
│ without a browser screenshot tool. │
│ open-source Ask the src peer (nvim) to open FILE at line+col. │
│ resolve resolve coordinates via the hub's view.json + tb_prefix mapping │
╰──────────────────────────────────────────────────────────────────────────────────────╯
hub send select
Usage: rtl-buddy hub send select [OPTIONS] INSTANCE_PATH
Broadcast selection_changed{instance_path}.
╭─ Arguments ──────────────────────────────────────────────────────────────────────────╮
│ * instance_path TEXT view.json instance_path, e.g. top.u_fifo.u_wr_ptr │
│ [required] │
╰──────────────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────────────╮
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────────────╯
hub send signal
Usage: rtl-buddy hub send signal [OPTIONS] SIGNAL
Broadcast signal_selected{signal, wave_scope}.
╭─ Arguments ──────────────────────────────────────────────────────────────────────────╮
│ * signal TEXT signal name, e.g. wr_ptr_q [required] │
╰──────────────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────────────╮
│ * --wave-scope TEXT surfer/VCD scope owning the signal, e.g. tb.dut.u_fifo │
│ [required] │
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────────────╯
hub send cursor
Usage: rtl-buddy hub send cursor [OPTIONS] T_FS
Broadcast cursor_time_changed{t_fs}.
╭─ Arguments ──────────────────────────────────────────────────────────────────────────╮
│ * t_fs INTEGER cursor time in femtoseconds (decimal integer) [required] │
╰──────────────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────────────╮
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────────────╯
hub send scope
Usage: rtl-buddy hub send scope [OPTIONS] WAVE_SCOPE
Broadcast scope_changed{wave_scope}.
╭─ Arguments ──────────────────────────────────────────────────────────────────────────╮
│ * wave_scope TEXT surfer/VCD scope, e.g. tb.dut.u_fifo [required] │
╰──────────────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────────────╮
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────────────╯
hub send open
Usage: rtl-buddy hub send open [OPTIONS] SPEC
Broadcast source_focused{file, line, col}.
╭─ Arguments ──────────────────────────────────────────────────────────────────────────╮
│ * spec TEXT file:line[:col], e.g. design/dma/dma.sv:42:7 [required] │
╰──────────────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────────────╮
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────────────╯
hub send graph-focus
Usage: rtl-buddy hub send graph-focus [OPTIONS] NODE
Broadcast graph_focus{node} — point the hub's design knowledge graph pane
(http://127.0.0.1:<http_port>/gph) at one node of artefacts/graph/graph.json. NODE is
a graph node id: 'module:fifo', 'inst:top/top.u_fifo', 'test:verif/dma#smoke',
'covitem:dma#DMA-COV-1' — the vocabulary `rb graph query` returns and
docs/concepts/graph.md lists. The hub caches the focus and replays it to the pane on
connect, so sending this before the browser tab is open works.
╭─ Arguments ──────────────────────────────────────────────────────────────────────────╮
│ * node TEXT graph node id, e.g. test:verif/dma#smoke [required] │
╰──────────────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────────────╮
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────────────╯
hub send cov-focus
Usage: rtl-buddy hub send cov-focus [OPTIONS] TARGET
Broadcast cov_focus{target} — point the hub's coverage pane
(http://127.0.0.1:<http_port>/cov) at one target of the run's coverage model. TARGET
is prefixed: 'file:design/blk.sv', 'module:blk', or 'test:verif/blk#basic'; an
unprefixed string is read as a file path. --metric foregrounds one coverage kind,
--line scrolls a file target to a line, and --item names a branch/toggle/expression
bin or an SVA cover point. The hub caches the focus and replays it to the pane on
connect, so sending this before the browser tab is open works.
╭─ Arguments ──────────────────────────────────────────────────────────────────────────╮
│ * target TEXT coverage target, e.g. module:blk or design/blk.sv [required] │
╰──────────────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────────────╮
│ --metric TEXT line|branch|toggle|expression|cover — which │
│ kind to foreground. │
│ --line INTEGER RANGE [x>=1] 1-based source line to scroll to. │
│ --item TEXT Point within the target: a │
│ branch/toggle/expression bin name as /cov.json │
│ spells it, or an SVA cover point name. │
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────────────╯
hub send diagnose
Usage: rtl-buddy hub send diagnose [OPTIONS] SOURCE [ITEMS]...
Push a diagnostics_set bundle for SOURCE. Each ITEM is
<file>:<line>:<severity>:<code>:<message>. --clear sends an empty set (clears any
cached diagnostics from SOURCE). Use --instance to attach a view.json instance_path
hint that consumers (the SPA's on-canvas badge layer in particular) use as a fast path
instead of the file+line resolver.
╭─ Arguments ──────────────────────────────────────────────────────────────────────────╮
│ * source TEXT producer key (e.g. 'analysis-tool', 'claude-analysis'); │
│ latest-writer-wins per source on the hub's cache │
│ [required] │
│ items [ITEMS]... <file>:<line>:<sev>:<code>:<msg> ... │
╰──────────────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────────────╮
│ --clear Send an empty items list (clears SOURCE). │
│ --instance TEXT Optional view.json instance_path to attach to every ITEM in │
│ this push. Use when the producer knows which instance a │
│ finding pertains to (most one-shot agent calls do); skip for │
│ batch lint output where each item lives at a different │
│ file:line. │
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────────────╯
hub send state
Usage: rtl-buddy hub send state [OPTIONS]
Snapshot the hub's cached state (active model, selection, cursor, scope, peers).
╭─ Options ────────────────────────────────────────────────────────────────────────────╮
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────────────╯
hub send wave-add
Usage: rtl-buddy hub send wave-add [OPTIONS] VARIABLES...
Ask the wave peer (surfer) to add one or more signals to the view.
╭─ Arguments ──────────────────────────────────────────────────────────────────────────╮
│ * variables VARIABLES... fully-scoped variable names, e.g. │
│ tb.dut.u_fifo.wr_ptr_q │
│ [required] │
╰──────────────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────────────╮
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────────────╯
hub send wave-cursor
Usage: rtl-buddy hub send wave-cursor [OPTIONS] T_FS
Ask the wave peer (surfer) to move its cursor to T_FS.
╭─ Arguments ──────────────────────────────────────────────────────────────────────────╮
│ * t_fs INTEGER cursor time in femtoseconds (decimal integer) [required] │
╰──────────────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────────────╮
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────────────╯
hub send wave-scope
Usage: rtl-buddy hub send wave-scope [OPTIONS] WAVE_SCOPE
Ask the wave peer (surfer) to switch its active scope without populating the variable
panel (maps to WCP set_scope).
╭─ Arguments ──────────────────────────────────────────────────────────────────────────╮
│ * wave_scope TEXT surfer/VCD scope [required] │
╰──────────────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────────────╮
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────────────╯
hub send wave-pan
Usage: rtl-buddy hub send wave-pan [OPTIONS] T_FS
Pan surfer's viewport to center on T_FS (zoom unchanged). Maps to WCP set_viewport_to.
╭─ Arguments ──────────────────────────────────────────────────────────────────────────╮
│ * t_fs INTEGER center time in femtoseconds [required] │
╰──────────────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────────────╮
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────────────╯
hub send wave-zoom
Usage: rtl-buddy hub send wave-zoom [OPTIONS] START_FS END_FS
Zoom + pan surfer to fit [START_FS, END_FS]. Maps to WCP set_viewport_range.
╭─ Arguments ──────────────────────────────────────────────────────────────────────────╮
│ * start_fs INTEGER range start in femtoseconds [required] │
│ * end_fs INTEGER range end in femtoseconds [required] │
╰──────────────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────────────╮
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────────────╯
hub send wave-zoom-fit
Usage: rtl-buddy hub send wave-zoom-fit [OPTIONS]
Zoom surfer out to fit the whole waveform. Maps to WCP zoom_to_fit.
╭─ Options ────────────────────────────────────────────────────────────────────────────╮
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────────────╯
hub send wave-items
Usage: rtl-buddy hub send wave-items [OPTIONS]
List the items currently in surfer's wave view (id, type, name). Maps to WCP
get_item_list + get_item_info.
╭─ Options ────────────────────────────────────────────────────────────────────────────╮
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────────────╯
hub send wave-remove
Usage: rtl-buddy hub send wave-remove [OPTIONS] IDS...
Ask the wave peer (surfer) to remove items by id. IDs come from wave-add / wave-items.
Reports removed vs not_found.
╭─ Arguments ──────────────────────────────────────────────────────────────────────────╮
│ * ids IDS... DisplayedItemRef ids to remove, e.g. 3 5 7 [required] │
╰──────────────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────────────╮
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────────────╯
hub send wave-move
Usage: rtl-buddy hub send wave-move [OPTIONS] IDS...
Reorder items in surfer's view. Move the given IDS (in the order listed) so the block
starts at --to INDEX, or just before --before ID. Exactly one of --to / --before is
required.
╭─ Arguments ──────────────────────────────────────────────────────────────────────────╮
│ * ids IDS... DisplayedItemRef ids to move, e.g. 5 6 [required] │
╰──────────────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────────────╮
│ --to INTEGER RANGE [x>=0] target visible index (0 = top of view) │
│ --before INTEGER RANGE [x>=0] move the block to just before this item id │
│ (resolved via wave-items) │
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────────────╯
hub send wave-comment
Usage: rtl-buddy hub send wave-comment [OPTIONS] TEXTS...
Add comment rows (named dividers) to surfer's view. Returns the new item ids. Maps to
WCP add_dividers.
╭─ Arguments ──────────────────────────────────────────────────────────────────────────╮
│ * texts TEXTS... comment labels, one divider per entry [required] │
╰──────────────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────────────╮
│ --after INTEGER RANGE [x>=0] insert the comments after this item id │
│ (default: end of view) │
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────────────╯
hub send view-pan
Usage: rtl-buddy hub send view-pan [OPTIONS] INSTANCE_PATH
Ask the schematic (rtl-buddy-sch) to pan/center on INSTANCE_PATH.
╭─ Arguments ──────────────────────────────────────────────────────────────────────────╮
│ * instance_path TEXT view.json instance_path [required] │
╰──────────────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────────────╮
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────────────╯
hub send overlay
Usage: rtl-buddy hub send overlay [OPTIONS] NAME
Flip an overlay's enabled state on the SPA. Built-in NAMES are 'clock', 'reset',
'axi-perf', 'wave'; an unknown name is a no-op. Use --on / --off (default --on).
Useful for agents or scripted demos that want to direct the user's attention to a
specific overlay layer without a UI click.
╭─ Arguments ──────────────────────────────────────────────────────────────────────────╮
│ * name TEXT overlay name [required] │
╰──────────────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────────────╮
│ --on --off Enable (default) or disable the named overlay. [default: on] │
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────────────╯
hub send capture
Usage: rtl-buddy hub send capture [OPTIONS]
Ask the schematic (rtl-buddy-sch) to snapshot the current graph and write it to --out.
Graph-only — surrounding panels are not captured. Useful for agents that want to look
at what the user is seeing without a browser screenshot tool.
╭─ Options ────────────────────────────────────────────────────────────────────────────╮
│ * --out -o PATH Destination file. Extension │
│ determines format if --format │
│ omitted. │
│ [required] │
│ --format -f TEXT png (default) or svg. Inferred │
│ from --out suffix if not given. │
│ --scale FLOAT RANGE [0.1<=x<=8.0] PNG upscale factor (1.0 = │
│ native). Ignored for SVG. │
│ [default: 1.0] │
│ --timeout FLOAT RANGE [1.0<=x<=120.0] Seconds to wait for the SPA to │
│ reply. Large designs may need │
│ longer. │
│ [default: 15.0] │
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────────────╯
hub send open-source
Usage: rtl-buddy hub send open-source [OPTIONS] SPEC
Ask the src peer (nvim) to open FILE at line+col.
╭─ Arguments ──────────────────────────────────────────────────────────────────────────╮
│ * spec TEXT file:line[:col], e.g. design/dma/dma.sv:42:7 [required] │
╰──────────────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────────────╮
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────────────╯
hub send resolve
Usage: rtl-buddy hub send resolve [OPTIONS] COMMAND [ARGS]...
resolve coordinates via the hub's view.json + tb_prefix mapping
╭─ Options ────────────────────────────────────────────────────────────────────────────╮
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────────────╯
╭─ Commands ───────────────────────────────────────────────────────────────────────────╮
│ view-to-wave instance_path → wave_scope │
│ wave-to-view wave_scope → instance_path │
│ signal-to-view signal + wave_scope → driver instance_path(s) and driven port │
╰──────────────────────────────────────────────────────────────────────────────────────╯
hub send resolve view-to-wave
Usage: rtl-buddy hub send resolve view-to-wave [OPTIONS] INSTANCE_PATH
instance_path → wave_scope
╭─ Arguments ──────────────────────────────────────────────────────────────────────────╮
│ * instance_path TEXT view.json instance_path [required] │
╰──────────────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────────────╮
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────────────╯
hub send resolve wave-to-view
Usage: rtl-buddy hub send resolve wave-to-view [OPTIONS] WAVE_SCOPE
wave_scope → instance_path
╭─ Arguments ──────────────────────────────────────────────────────────────────────────╮
│ * wave_scope TEXT surfer/VCD wave_scope [required] │
╰──────────────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────────────╮
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────────────╯
hub send resolve signal-to-view
Usage: rtl-buddy hub send resolve signal-to-view [OPTIONS] SIGNAL
signal + wave_scope → driver instance_path(s) and driven port
╭─ Arguments ──────────────────────────────────────────────────────────────────────────╮
│ * signal TEXT signal name (e.g. wr_ptr_q) [required] │
╰──────────────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────────────╮
│ * --wave-scope TEXT enclosing wave scope [required] │
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────────────╯
skill
Usage: rtl-buddy skill [OPTIONS] COMMAND [ARGS]...
manage the rtl_buddy agent skill
╭─ Options ────────────────────────────────────────────────────────────────────────────╮
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────────────╯
╭─ Commands ───────────────────────────────────────────────────────────────────────────╮
│ install Install the bundled rtl_buddy skill family. │
│ uninstall Remove installed rtl_buddy skill-family files from the selected │
│ scope. │
│ status Report whether each skill is installed and matches the package │
│ version. │
│ view Print the primary bundled rtl_buddy skill to stdout. │
│ print-gitignore Print the gitignore lines for project-level skill installs. │
╰──────────────────────────────────────────────────────────────────────────────────────╯
skill install
Usage: rtl-buddy skill install [OPTIONS]
Install the bundled rtl_buddy skill family.
Default scope is user-level (`~/.claude/skills/rtl-buddy/` and
`~/.codex/skills/rtl-buddy/`). Use `--project` to install into the
discovered project root instead; project-level copies take precedence
over user-level when both exist. Use `--dir PATH` to write the family as
sibling directories under PATH, bypassing the `.claude`/`.agents` layout.
A marked sibling `rtl_buddy/` directory is removed to prevent a stale
duplicate of the primary skill.
╭─ Options ────────────────────────────────────────────────────────────────────────────╮
│ --project install into the discovered project root instead of the │
│ user home │
│ --root PATH explicit target root (implies project-level layout) │
│ --dir PATH write the skill family directly under <DIR>/, bypassing │
│ the .claude/.agents/.codex layout │
│ --no-claude skip writing the Claude Code target │
│ --no-codex skip writing the Codex target │
│ --no-gitignore skip updating .gitignore on project-level installs │
│ --dry-run print what would be written and exit │
│ --force overwrite even when content matches │
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────────────╯
skill uninstall
Usage: rtl-buddy skill uninstall [OPTIONS]
Remove installed rtl_buddy skill-family files from the selected scope.
Removes both the `rtl-buddy` directory and a marked sibling `rtl_buddy`
directory.
╭─ Options ────────────────────────────────────────────────────────────────────────────╮
│ --project uninstall from the discovered project root instead of the │
│ user home │
│ --root PATH explicit target root (implies project-level layout) │
│ --no-claude skip the Claude Code target │
│ --no-codex skip the Codex target │
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────────────╯
skill status
Usage: rtl-buddy skill status [OPTIONS]
Report whether each skill is installed and matches the package version.
╭─ Options ────────────────────────────────────────────────────────────────────────────╮
│ --project report status for the discovered project root instead of the │
│ user home │
│ --root PATH explicit target root (implies project-level layout) │
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────────────╯
skill view
Usage: rtl-buddy skill view [OPTIONS]
Print the primary bundled rtl_buddy skill to stdout.
╭─ Options ────────────────────────────────────────────────────────────────────────────╮
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────────────╯
skill print-gitignore
Usage: rtl-buddy skill print-gitignore [OPTIONS]
Print the gitignore lines for project-level skill installs.
╭─ Options ────────────────────────────────────────────────────────────────────────────╮
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────────────╯
docs
Usage: rtl-buddy docs [OPTIONS] COMMAND [ARGS]...
browse bundled documentation
╭─ Options ────────────────────────────────────────────────────────────────────────────╮
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────────────╯
╭─ Commands ───────────────────────────────────────────────────────────────────────────╮
│ list list bundled documentation pages │
│ show show a bundled documentation page │
╰──────────────────────────────────────────────────────────────────────────────────────╯
docs list
Usage: rtl-buddy docs list [OPTIONS]
list bundled documentation pages
╭─ Options ────────────────────────────────────────────────────────────────────────────╮
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────────────╯
docs show
Usage: rtl-buddy docs show [OPTIONS] SLUG
show a bundled documentation page
╭─ Arguments ──────────────────────────────────────────────────────────────────────────╮
│ * slug TEXT MkDocs path slug or slug#section-anchor, for example │
│ concepts/root-config or agents#local-docs-access │
│ [required] │
╰──────────────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────────────╮
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────────────╯
spec
Usage: rtl-buddy spec [OPTIONS] COMMAND [ARGS]...
spec traceability commands
╭─ Options ────────────────────────────────────────────────────────────────────────────╮
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────────────╯
╭─ Commands ───────────────────────────────────────────────────────────────────────────╮
│ list list all spec blocks discovered in the project │
│ check-design show which spec blocks have design models referencing them │
│ check-coverage show which spec coverage items are addressed by tests │
╰──────────────────────────────────────────────────────────────────────────────────────╯
spec list
Usage: rtl-buddy spec list [OPTIONS]
list all spec blocks discovered in the project
╭─ Options ────────────────────────────────────────────────────────────────────────────╮
│ --spec-dir TEXT Directory to search for specs.yaml files │
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────────────╯
spec check-design
Usage: rtl-buddy spec check-design [OPTIONS]
show which spec blocks have design models referencing them
╭─ Options ────────────────────────────────────────────────────────────────────────────╮
│ --spec-dir TEXT Directory to search for specs.yaml files │
│ --design-dir TEXT Directory to search for models.yaml files │
│ --block TEXT Only include spec blocks with this name; may be repeated │
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────────────╯
spec check-coverage
Usage: rtl-buddy spec check-coverage [OPTIONS]
show which spec coverage items are addressed by tests
╭─ Options ────────────────────────────────────────────────────────────────────────────╮
│ --spec-dir TEXT Directory to search for specs.yaml files │
│ --verif-dir TEXT Directory to search for tests.yaml files │
│ --block TEXT Only include spec blocks with this name; may be repeated │
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────────────╯
xplr
Usage: rtl-buddy xplr [OPTIONS] COMMAND [ARGS]...
design-space exploration experiment ledger (agent-facing)
╭─ Options ────────────────────────────────────────────────────────────────────────────╮
│ --root TEXT anchor project-root discovery at this path instead of the │
│ current directory (root_config.yaml/.git are resolved from │
│ here). Group-level: place it between 'xplr' and the subcommand, │
│ e.g. `rb xplr --root <project> list`. For driving a ledger from │
│ outside its project checkout │
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────────────╯
╭─ Commands ───────────────────────────────────────────────────────────────────────────╮
│ register open a new experiment: pin the current git ref, record the │
│ agent-declared knob manifest, return its experiment id │
│ attach-outcome attach flow-declared outcome metrics to an experiment │
│ (pending/running -> success|failed) │
│ list list experiments in the ledger (one summary row each) │
│ show show one experiment's full record │
│ diff pairwise experiment diff: knob delta, direction-aware outcome delta, │
│ and the git diff between the pinned sources │
│ frontier curate the Pareto frontier (non-dominated set) over the declared │
│ numeric outcome metrics; dominated, infeasible (routed=false), and │
│ excluded experiments are reported alongside │
│ knob-effect per-knob effect history: every experiment that declared the knob, │
│ with metric deltas vs its parent when available │
│ materialize check the experiment's pinned sha out into its own git worktree │
│ (isolated build dir; disposable — the branch is the durable │
│ artifact). Idempotent │
│ release remove the experiment's worktree (worktree remove + prune); the exp │
│ branch and the ledger record are kept │
│ gc reclaim experiment disk space, non-interactively: evict heavy │
│ artifacts + worktrees per policy (default keep-frontier never │
│ touches Pareto-frontier members or their lineage); record.json and │
│ the pinned sha always survive, so evicted experiments can be │
│ re-materialized │
│ mock synthetic DSE backend with known optima (dev/CI harness) │
╰──────────────────────────────────────────────────────────────────────────────────────╯
xplr register
Usage: rtl-buddy xplr register [OPTIONS]
open a new experiment: pin the current git ref, record the agent-declared knob
manifest, return its experiment id
╭─ Options ────────────────────────────────────────────────────────────────────────────╮
│ --json TEXT JSON manifest file, or '-' for stdin: {knobs: [{name, from, │
│ to, rationale?, layer?}], hypothesis?, parent?, │
│ config_snapshot?, source?: {git_sha?, branch?, diff_from?}, │
│ provenance?: {tools?, agent?}} │
│ --baseline TEXT git ref to record as source.diff_from (the RTL-diff │
│ baseline). Default: the parent experiment's pinned sha when │
│ 'parent' is given, else HEAD before any snapshot │
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────────────╯
xplr attach-outcome
Usage: rtl-buddy xplr attach-outcome [OPTIONS] EXP
attach flow-declared outcome metrics to an experiment (pending/running ->
success|failed)
╭─ Arguments ──────────────────────────────────────────────────────────────────────────╮
│ * exp_id EXP experiment id, e.g. exp-0001 [required] │
╰──────────────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────────────╮
│ * --json TEXT JSON outcome file, or '-' for stdin: {status: │
│ 'success'|'failed', metrics?, metric_meta?, artifacts?, │
│ provenance?: {tools?, reused_state?}} │
│ [required] │
│ --force overwrite an outcome that is already terminal │
│ (success/failed) │
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────────────╯
xplr list
Usage: rtl-buddy xplr list [OPTIONS]
list experiments in the ledger (one summary row each)
╭─ Options ────────────────────────────────────────────────────────────────────────────╮
│ --status TEXT only experiments with this outcome status │
│ (pending|running|success|failed) │
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────────────╯
xplr show
Usage: rtl-buddy xplr show [OPTIONS] EXP
show one experiment's full record
╭─ Arguments ──────────────────────────────────────────────────────────────────────────╮
│ * exp_id EXP experiment id, e.g. exp-0001 [required] │
╰──────────────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────────────╮
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────────────╯
xplr diff
Usage: rtl-buddy xplr diff [OPTIONS] EXP_A EXP_B
pairwise experiment diff: knob delta, direction-aware outcome delta, and the git diff
between the pinned sources
╭─ Arguments ──────────────────────────────────────────────────────────────────────────╮
│ * exp_a TEXT first experiment id [required] │
│ * exp_b TEXT second experiment id [required] │
╰──────────────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────────────╮
│ --patch include the full git diff patch between the pinned sources (not │
│ just --stat) │
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────────────╯
xplr frontier
Usage: rtl-buddy xplr frontier [OPTIONS]
curate the Pareto frontier (non-dominated set) over the declared numeric outcome
metrics; dominated, infeasible (routed=false), and excluded experiments are reported
alongside
╭─ Options ────────────────────────────────────────────────────────────────────────────╮
│ --metrics TEXT override/declare dominance directions: 'name:min,name2:max' │
│ (record-level metric_meta otherwise) │
│ --prefer TEXT scalar preference to sort the frontier (never drops │
│ non-dominated points): comma/plus-separated weight*metric, │
│ e.g. '0.7*lut_pct+0.3*delay_ns'; lower score = better after │
│ direction normalization │
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────────────╯
xplr knob-effect
Usage: rtl-buddy xplr knob-effect [OPTIONS] KNOB
per-knob effect history: every experiment that declared the knob, with metric deltas
vs its parent when available
╭─ Arguments ──────────────────────────────────────────────────────────────────────────╮
│ * name KNOB knob name, e.g. synth.target_freq_mhz [required] │
╰──────────────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────────────╮
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────────────╯
xplr materialize
Usage: rtl-buddy xplr materialize [OPTIONS] EXP
check the experiment's pinned sha out into its own git worktree (isolated build dir;
disposable — the branch is the durable artifact). Idempotent
╭─ Arguments ──────────────────────────────────────────────────────────────────────────╮
│ * exp_id EXP experiment id, e.g. exp-0001 [required] │
╰──────────────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────────────╮
│ --path TEXT worktree location (default: <worktree-root>/<exp>/, │
│ worktree-root from cfg-xplr, under artefacts/ — keep it │
│ gitignored) │
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────────────╯
xplr release
Usage: rtl-buddy xplr release [OPTIONS] EXP
remove the experiment's worktree (worktree remove + prune); the exp branch and the
ledger record are kept
╭─ Arguments ──────────────────────────────────────────────────────────────────────────╮
│ * exp_id EXP experiment id, e.g. exp-0001 [required] │
╰──────────────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────────────╮
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────────────╯
xplr gc
Usage: rtl-buddy xplr gc [OPTIONS]
reclaim experiment disk space, non-interactively: evict heavy artifacts + worktrees
per policy (default keep-frontier never touches Pareto-frontier members or their
lineage); record.json and the pinned sha always survive, so evicted experiments can be
re-materialized
╭─ Options ────────────────────────────────────────────────────────────────────────────╮
│ --dry-run report what would be evicted without touching anything │
│ --policy TEXT eviction policy for this run: keep-frontier (default; │
│ frontier members + lineage are never evicted) | │
│ oldest-first | manual (list candidates, evict nothing) │
│ --target-gb FLOAT gc down to this usage (default: cfg-xplr │
│ disk-high-watermark-gb) │
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────────────╯
xplr mock
Usage: rtl-buddy xplr mock [OPTIONS] COMMAND [ARGS]...
synthetic DSE backend with known optima (dev/CI harness)
╭─ Options ────────────────────────────────────────────────────────────────────────────╮
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────────────╯
╭─ Commands ───────────────────────────────────────────────────────────────────────────╮
│ info list scenarios: knob specs, metric_meta, cost model, and the analytic ground │
│ truth (optimum / Pareto front) │
│ run evaluate one knob vector; with --register, record it as a ledger experiment │
│ with the outcome attached in one step │
│ score score the ledger's mockflow experiments against the ground truth: regret │
│ (single-objective) or hypervolume + distance-to-front (multi-objective) │
╰──────────────────────────────────────────────────────────────────────────────────────╯
xplr mock info
Usage: rtl-buddy xplr mock info [OPTIONS]
list scenarios: knob specs, metric_meta, cost model, and the analytic ground truth
(optimum / Pareto front)
╭─ Options ────────────────────────────────────────────────────────────────────────────╮
│ --scenario TEXT show one scenario only (rastrigin|zdt1) │
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────────────╯
xplr mock run
Usage: rtl-buddy xplr mock run [OPTIONS]
evaluate one knob vector; with --register, record it as a ledger experiment with the
outcome attached in one step
╭─ Options ────────────────────────────────────────────────────────────────────────────╮
│ * --scenario TEXT scenario name (rastrigin|zdt1) [required] │
│ --json TEXT JSON knob-value object {name: value}, or '-' for │
│ stdin; omitted knobs take their scenario defaults │
│ --seed INTEGER noise seed (irrelevant when --noise is 0) │
│ [default: 0] │
│ --noise FLOAT stddev of seeded Gaussian noise added to the │
│ objective metrics (simulated run-to-run variance; │
│ default 0 = exact) │
│ [default: 0.0] │
│ --register register a ledger experiment AND attach the │
│ outcome in one step (knobs recorded as │
│ from=scenario default) │
│ --source-sha TEXT with --register: record this sha verbatim as │
│ source.git_sha (the agent-declared pin path; no │
│ dirty bit). The escape hatch for sandboxes where │
│ the project root is not a git repository │
│ --source-branch TEXT with --source-sha: optional source.branch label, │
│ recorded verbatim │
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────────────╯
xplr mock score
Usage: rtl-buddy xplr mock score [OPTIONS]
score the ledger's mockflow experiments against the ground truth: regret
(single-objective) or hypervolume + distance-to-front (multi-objective)
╭─ Options ────────────────────────────────────────────────────────────────────────────╮
│ --scenario TEXT score one scenario only (default: every scenario with │
│ mockflow experiments in the ledger) │
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────────────╯