CLI Reference
This page is auto-generated from rtl-buddy --help output.
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 │
│ --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 │
│ verible run verible cmd │
│ wave open waveform viewer for a test │
│ wave-install-nvim install nvim plugin for rb wave annotation │
│ synth run synthesis │
│ synth-regression run synthesis regression │
│ cdc run CDC lint │
│ cdc-regression run CDC lint regression │
│ skill manage the rtl_buddy agent skill │
│ docs browse bundled documentation │
│ spec spec traceability commands │
╰──────────────────────────────────────────────────────────────────────────────────────╯
test
Usage: rtl-buddy test [OPTIONS] [TEST_NAME]
run a simple test
╭─ Arguments ──────────────────────────────────────────────────────────────────────────╮
│ test_name [TEST_NAME] name of test [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 │
│ --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 │
│ --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 │
│ --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 │
│ --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. │
╰──────────────────────────────────────────────────────────────────────────────────────╯
verible
Usage: rtl-buddy verible [OPTIONS] CMD [VERIBLE_ARGS]...
run verible cmd
╭─ Arguments ──────────────────────────────────────────────────────────────────────────╮
│ * cmd TEXT Verible cmd [required] │
│ verible_args [VERIBLE_ARGS]... │
╰──────────────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────────────╮
│ --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: 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-install-nvim
Usage: rtl-buddy wave-install-nvim [OPTIONS]
install nvim plugin for rb wave annotation
╭─ Options ────────────────────────────────────────────────────────────────────────────╮
│ --force overwrite existing installation │
│ --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. │
│ uninstall Remove the installed rtl_buddy skill files from the selected scope. │
│ status Report whether the skill is installed and whether it matches the │
│ current package version. │
│ print-gitignore Print the gitignore lines for project-level skill installs. │
╰──────────────────────────────────────────────────────────────────────────────────────╯
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 │
╰──────────────────────────────────────────────────────────────────────────────────────╯
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 │
╰──────────────────────────────────────────────────────────────────────────────────────╯
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)] │
│ --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. │
╰──────────────────────────────────────────────────────────────────────────────────────╯