CLI Reference

This page is generated from real argparse parsers in tools/*.py.

Each command is shown with argument introspection and raw --help output.

`tools/merlin.py`

Unified Merlin developer command reference parser.

Usage

usage: uv run tools/merlin.py [-h]
                              {build,compile,setup,ci,patches,benchmark,chipyard,ray,targetgen}
                              ...

Arguments

Argument	Required	Default	Choices	Help

Subcommand `benchmark`

usage: uv run tools/merlin.py benchmark [-h] [--dry-run]
                                        target
                                        {compile-dual-vmfb,run-dual-remote}
                                        ...

Argument	Required	Default	Choices	Help
`--dry-run`	no	`False`	-	Print commands without executing
`target`	yes	-	-	Target name from config/targets.json
`action`	yes	-	`compile-dual-vmfb, run-dual-remote`	Benchmark action
`extra_args`	yes	-	-

Subcommand `build`

usage: uv run tools/merlin.py build [-h] [--dry-run]
                                    [--profile {firesim,full-plugin,gemmini,npu,package-firesim,package-host,package-spacemit,radiance,spacemit,vanilla}]
                                    [--target {host,spacemit,firesim}]
                                    [--config {debug,release,asan,trace,perf}]
                                    [--cmake-target CMAKE_TARGET]
                                    [--with-plugin]
                                    [--plugin-compiler | --no-plugin-compiler]
                                    [--plugin-runtime | --no-plugin-runtime]
                                    [--plugin-runtime-radiance | --no-plugin-runtime-radiance]
                                    [--plugin-runtime-samples | --no-plugin-runtime-samples]
                                    [--plugin-runtime-benchmarks | --no-plugin-runtime-benchmarks]
                                    [--plugin-runtime-radiance-tests | --no-plugin-runtime-radiance-tests]
                                    [--plugin-runtime-radiance-rpc | --no-plugin-runtime-radiance-rpc]
                                    [--plugin-runtime-radiance-direct | --no-plugin-runtime-radiance-direct]
                                    [--plugin-runtime-radiance-kmod | --no-plugin-runtime-radiance-kmod]
                                    [--compiler-scope {all,gemmini,npu,saturn,spacemit,none}]
                                    [--build-compiler | --no-build-compiler]
                                    [--build-python-bindings | --no-build-python-bindings]
                                    [--build-samples | --no-build-samples]
                                    [--build-tests | --no-build-tests]
                                    [--enable-libbacktrace | --no-enable-libbacktrace]
                                    [--enable-tracy] [--offline-friendly]
                                    [--cmake-bin CMAKE_BIN]
                                    [--use-system-cmake]
                                    [--use-ccache | --no-use-ccache]
                                    [--cmake-arg CMAKE_ARG]
                                    [--cmake-build-arg CMAKE_BUILD_ARG]
                                    [--native-build-arg NATIVE_BUILD_ARG]
                                    [--clean] [--verbose]

Argument	Required	Default	Choices	Help
`--dry-run`	no	`False`	-	Print commands without executing
`--profile`	no	-	`firesim, full-plugin, gemmini, npu, package-firesim, package-host, package-spacemit, radiance, spacemit, vanilla`	High-level user profile preset. Use this for normal workflows; advanced flags may still override details.
`--target`	no	-	`host, spacemit, firesim`	Target platform.
`--config`	no	-	`debug, release, asan, trace, perf`	Build configuration type
`--cmake-target`	no	-	-	Build specific CMake target (default: install)
`--with-plugin`	no	`False`	-	Enable Merlin compiler+runtime plugins (legacy umbrella switch).
`--plugin-compiler`, `--no-plugin-compiler`	no	-	-	Enable/disable Merlin compiler plugin targets (default follows --with-plugin).
`--plugin-runtime`, `--no-plugin-runtime`	no	-	-	Enable/disable Merlin runtime plugin integration (default follows --with-plugin).
`--plugin-runtime-radiance`, `--no-plugin-runtime-radiance`	no	-	-	Enable/disable Radiance HAL runtime plugin path (default: host+plugin only).
`--plugin-runtime-samples`, `--no-plugin-runtime-samples`	no	-	-	Enable/disable runtime plugin samples subdir.
`--plugin-runtime-benchmarks`, `--no-plugin-runtime-benchmarks`	no	-	-	Enable/disable runtime plugin benchmarks subdir.
`--plugin-runtime-radiance-tests`, `--no-plugin-runtime-radiance-tests`	no	-	-	Enable/disable Radiance runtime plugin tests.
`--plugin-runtime-radiance-rpc`, `--no-plugin-runtime-radiance-rpc`	no	-	-	Enable/disable Radiance RPC-compat transport backend.
`--plugin-runtime-radiance-direct`, `--no-plugin-runtime-radiance-direct`	no	-	-	Enable/disable Radiance direct-submit transport backend.
`--plugin-runtime-radiance-kmod`, `--no-plugin-runtime-radiance-kmod`	no	-	-	Enable/disable Radiance kmod transport backend.
`--compiler-scope`	no	-	`all, gemmini, npu, saturn, spacemit, none`	Limit compiler-plugin target registration scope. Only used when compiler plugin + compiler build are enabled.
`--build-compiler`, `--no-build-compiler`	no	-	-	Override IREE_BUILD_COMPILER for this build.
`--build-python-bindings`, `--no-build-python-bindings`	no	-	-	Override IREE_BUILD_PYTHON_BINDINGS for this build.
`--build-samples`, `--no-build-samples`	no	-	-	Override IREE_BUILD_SAMPLES for this build.
`--build-tests`, `--no-build-tests`	no	-	-	Override IREE_BUILD_TESTS for this build.
`--enable-libbacktrace`, `--no-enable-libbacktrace`	no	-	-	Override IREE_ENABLE_LIBBACKTRACE for this build.
`--enable-tracy`	no	`False`	-	Enable Tracy runtime tracing (IREE_ENABLE_RUNTIME_TRACING=ON, IREE_TRACING_MODE=4). Compatible with any --config.
`--offline-friendly`	no	`False`	-	Prefer settings that avoid network fetches in CMake (equivalent to --no-build-compiler --no-build-python-bindings --no-enable-libbacktrace unless explicitly overridden).
`--cmake-bin`	no	`cmake`	-	CMake executable to use (default: cmake).
`--use-system-cmake`	no	`False`	-	Use /usr/bin/cmake instead of cmake from PATH.
`--use-ccache`, `--no-use-ccache`	no	`True`	-	Enable/disable ccache compiler launchers (default: enabled).
`--cmake-arg`, `--configure-custom-arg`	no	`[]`	-	Extra argument forwarded to CMake configure (repeatable).
`--cmake-build-arg`, `--build-custom-arg`	no	`[]`	-	Extra argument forwarded to CMake build command (repeatable).
`--native-build-arg`	no	`[]`	-	Extra argument forwarded to the native build tool after '--' (repeatable).
`--clean`	no	`False`	-	Delete build directory before building
`--verbose`	no	`False`	-	Enable verbose build output

Subcommand `chipyard`

usage: uv run tools/merlin.py chipyard [-h] [--dry-run]
                                       [--chipyard-root CHIPYARD_ROOT]
                                       {set-path,info,validate,checkout,build-sim,run,configure-firesim,build-bitstream,register-hwdb,stage-workload,build-firemarshal,status}
                                       ...

Argument	Required	Default	Choices	Help
`--dry-run`	no	`False`	-	Print commands without executing
`--chipyard-root`	no	-	-	Override chipyard root for this invocation

Subcommand `ci`

usage: uv run tools/merlin.py ci [-h] [--dry-run]
                                 {lint,cli-docs-drift,patch-gate,release-status}
                                 ...

Argument	Required	Default	Choices	Help
`--dry-run`	no	`False`	-	Print commands without executing

Subcommand `compile`

usage: uv run tools/merlin.py compile [-h] [--dry-run] --target TARGET
                                      [--hw HW] [--quantized]
                                      [--output-dir OUTPUT_DIR]
                                      [--build-dir BUILD_DIR]
                                      [--compile-to COMPILE_TO]
                                      [--dump-compilation-phases-to DUMP_COMPILATION_PHASES_TO]
                                      [--iree-compile-arg IREE_COMPILE_ARG]
                                      [--reuse-imported-mlir] [--tracy]
                                      [--dump-artifacts] [--dump-phases]
                                      [--dump-graph] [--build-benchmarks]
                                      input_path

Argument	Required	Default	Choices	Help
`--dry-run`	no	`False`	-	Print commands without executing
`input_path`	yes	-	-	Path to the model directory OR specific .mlir/.onnx file
`--target`	yes	-	-	Target YAML config file name (e.g., spacemit_x60)
`--hw`	no	-	-	Hardware sub-target from YAML (e.g., RVV, OPU). If omitted, uses default_hw from YAML.
`--quantized`	no	`False`	-	Force quantized mode (auto-detected if .q. in filename)
`--output-dir`	no	-	-	Override output directory (default: build/compiled_models//_/). If set, all generated files/artifacts are written under this directory.
`--build-dir`	no	`host-vanilla-release`	-	Which build directory to use for compiler tools (default: host-vanilla-release). If omitted and target YAML uses plugin_flags, compile.py auto-selects host-merlin-release.
`--compile-to`	no	-	-	Stop compilation at the given phase (for example: global-optimization). When set, output is emitted as an intermediate MLIR file.
`--dump-compilation-phases-to`	no	-	-	Directory for --dump-compilation-phases-to. If omitted and --dump-phases is set, defaults to /phases/.
`--iree-compile-arg`, `--compilation-custom-arg`	no	`[]`	-	Extra flag forwarded directly to iree-compile. Repeat for multiple flags.
`--reuse-imported-mlir`	no	`False`	-	Reuse an existing output MLIR instead of refreshing from explicit input files. By default, explicit input files are re-imported/re-copied.
`--tracy`	no	`False`	-	Enable Tracy profiling flags: embed debug info, use system linking, and enable debug symbols in generated code. Equivalent to --iree-hal-executable-debug-level=3 --iree-llvmcpu-link-embedded=false --iree-llvmcpu-debug-symbols=true
`--dump-artifacts`	no	`False`	-	Dump executable sources, binaries, and configs
`--dump-phases`	no	`False`	-	Dump MLIR compilation phases
`--dump-graph`	no	`False`	-	Dump the flow dispatch graph (.dot)
`--build-benchmarks`	no	`False`	-	Recompile individual dispatch benchmarks and zip them

Subcommand `patches`

usage: uv run tools/merlin.py patches [-h]
                                      {verify,log,drift,export-upstream} ...

Argument	Required	Default	Choices	Help

Subcommand `ray`

usage: uv run tools/merlin.py ray [-h] [--dry-run] [--state-root STATE_ROOT]
                                  {cluster,jobs,resources,artifacts} ...

Argument	Required	Default	Choices	Help
`--dry-run`	no	`False`	-	Print commands without executing
`--state-root`	no	`build/generated/ray`	-	Directory for Merlin-owned Ray cluster, run, artifact, and lease metadata.

Subcommand `setup`

usage: uv run tools/merlin.py setup [-h] [--env-name ENV_NAME]
                                    [--env-file ENV_FILE] [--offline]
                                    [--skip-conda] [--skip-pip]
                                    [--python-deps {auto,uv,pip}]
                                    [--conda-no-plugins | --no-conda-no-plugins]
                                    [--submodules-profile {core,npu,smolvla,full}]
                                    [--submodule-path SUBMODULE_PATH]
                                    [--submodule-paths-recursive | --no-submodule-paths-recursive]
                                    [--submodule-depth SUBMODULE_DEPTH]
                                    [--submodule-jobs SUBMODULE_JOBS]
                                    [--submodule-sync]
                                    [--toolchain-target {spacemit,firesim,all}]
                                    [--with-qemu] [--toolchain-force]
                                    [--prebuilt-artifact {host-linux-x86_64,host-macos,runtime-spacemit,runtime-saturnopu}]
                                    [--prebuilt-tag PREBUILT_TAG]
                                    [--prebuilt-repo PREBUILT_REPO]
                                    [--prebuilt-force]
                                    [{all,env,toolchain,submodules,prebuilt}]

Argument	Required	Default	Choices	Help
`component`	no	`all`	`all, env, toolchain, submodules, prebuilt`
`--env-name`	no	`merlin-dev`	-	Conda environment name to update/install packages into (default: merlin-dev).
`--env-file`	no	`<repo>/env_linux.yml`	-	Conda environment file to use. Default is platform-specific: env_linux.yml
`--offline`	no	`False`	-	Run setup in offline mode when possible.
`--skip-conda`	no	`False`	-	Skip conda environment sync.
`--skip-pip`	no	`False`	-	Skip Python dependency sync (uv/pip).
`--python-deps`	no	`auto`	`auto, uv, pip`	Python dependency installer. 'auto' prefers uv sync with uv.lock and falls back to pip requirements.
`--conda-no-plugins`, `--no-conda-no-plugins`	no	-	-	Force CONDA_NO_PLUGINS for conda env update. If unset, setup.py retries with CONDA_NO_PLUGINS=true on failure.
`--submodules-profile`	no	`core`	`core, npu, smolvla, full`	Which submodule profile to initialize for the current Merlin checkout (default: core).
`--submodule-path`	no	`[]`	-	Additional top-level submodule path to initialize (repeatable).
`--submodule-paths-recursive`, `--no-submodule-paths-recursive`	no	`False`	-	Whether extra --submodule-path entries should be initialized recursively.
`--submodule-depth`	no	`1`	-	Shallow depth for submodule fetches (default: 1). Use 0 for full history.
`--submodule-jobs`	no	`8`	-	Parallel submodule fetch jobs (default: 8).
`--submodule-sync`	no	`False`	-	Run `git submodule sync --recursive` before updating. Submodule SHAs still come from the current Merlin commit.
`--toolchain-target`	no	`spacemit`	`spacemit, firesim, all`	Which toolchain target to install (default: spacemit).
`--with-qemu`	no	`False`	-	For firesim toolchain setup, also install QEMU.
`--toolchain-force`	no	`False`	-	Reinstall toolchains even if the destination already exists.
`--prebuilt-artifact`	no	`host-linux-x86_64`	`host-linux-x86_64, host-macos, runtime-spacemit, runtime-saturnopu`	Which published Merlin prebuilt artifact to install.
`--prebuilt-tag`	no	`latest`	-	GitHub release tag to download from, or 'latest' (default: latest).
`--prebuilt-repo`	no	`ucb-bar/merlin`	-	GitHub repository containing release assets (default: ucb-bar/merlin).
`--prebuilt-force`	no	`False`	-	Replace an existing destination build tree when installing a prebuilt artifact.

Subcommand `targetgen`

usage: uv run tools/merlin.py targetgen [-h] [--dry-run]
                                        {validate,plan,generate,explain,orchestrate,execute,stage-mutation,answer,status}
                                        ...

Argument	Required	Default	Choices	Help
`--dry-run`	no	`False`	-	Print commands without executing

`--help` Output

usage: uv run tools/merlin.py [-h]
                              {build,compile,setup,ci,patches,benchmark,chipyard,ray,targetgen}
                              ...

Unified Merlin developer command reference parser.

positional arguments:
  {build,compile,setup,ci,patches,benchmark,chipyard,ray,targetgen}
    build               Configure and build Merlin and target runtimes
    compile             Compile MLIR/ONNX models to target artifacts
    setup               Bootstrap developer environment and toolchains
    ci                  Run repository CI/lint/patch workflows
    patches             Verify submodule state and manage upstream patches
    benchmark           Run benchmark helper scripts
    chipyard            Manage Chipyard hardware backend interactions
    ray                 Manage Merlin's Ray control plane, jobs, resources,
                        and artifacts
    targetgen           Plan and orchestrate hardware-spec-driven target
                        enablement

options:
  -h, --help            show this help message and exit

`tools/build.py`

Configure and build Merlin and target runtimes

Usage

usage: uv run tools/build.py [-h]
                             [--profile {firesim,full-plugin,gemmini,npu,package-firesim,package-host,package-spacemit,radiance,spacemit,vanilla}]
                             [--target {host,spacemit,firesim}]
                             [--config {debug,release,asan,trace,perf}]
                             [--cmake-target CMAKE_TARGET] [--with-plugin]
                             [--plugin-compiler | --no-plugin-compiler]
                             [--plugin-runtime | --no-plugin-runtime]
                             [--plugin-runtime-radiance | --no-plugin-runtime-radiance]
                             [--plugin-runtime-samples | --no-plugin-runtime-samples]
                             [--plugin-runtime-benchmarks | --no-plugin-runtime-benchmarks]
                             [--plugin-runtime-radiance-tests | --no-plugin-runtime-radiance-tests]
                             [--plugin-runtime-radiance-rpc | --no-plugin-runtime-radiance-rpc]
                             [--plugin-runtime-radiance-direct | --no-plugin-runtime-radiance-direct]
                             [--plugin-runtime-radiance-kmod | --no-plugin-runtime-radiance-kmod]
                             [--compiler-scope {all,gemmini,npu,saturn,spacemit,none}]
                             [--build-compiler | --no-build-compiler]
                             [--build-python-bindings | --no-build-python-bindings]
                             [--build-samples | --no-build-samples]
                             [--build-tests | --no-build-tests]
                             [--enable-libbacktrace | --no-enable-libbacktrace]
                             [--enable-tracy] [--offline-friendly]
                             [--cmake-bin CMAKE_BIN] [--use-system-cmake]
                             [--use-ccache | --no-use-ccache]
                             [--cmake-arg CMAKE_ARG]
                             [--cmake-build-arg CMAKE_BUILD_ARG]
                             [--native-build-arg NATIVE_BUILD_ARG] [--clean]
                             [--verbose]

Arguments

Argument	Required	Default	Choices	Help
`--profile`	no	-	`firesim, full-plugin, gemmini, npu, package-firesim, package-host, package-spacemit, radiance, spacemit, vanilla`	High-level user profile preset. Use this for normal workflows; advanced flags may still override details.
`--target`	no	-	`host, spacemit, firesim`	Target platform.
`--config`	no	-	`debug, release, asan, trace, perf`	Build configuration type
`--cmake-target`	no	-	-	Build specific CMake target (default: install)
`--with-plugin`	no	`False`	-	Enable Merlin compiler+runtime plugins (legacy umbrella switch).
`--plugin-compiler`, `--no-plugin-compiler`	no	-	-	Enable/disable Merlin compiler plugin targets (default follows --with-plugin).
`--plugin-runtime`, `--no-plugin-runtime`	no	-	-	Enable/disable Merlin runtime plugin integration (default follows --with-plugin).
`--plugin-runtime-radiance`, `--no-plugin-runtime-radiance`	no	-	-	Enable/disable Radiance HAL runtime plugin path (default: host+plugin only).
`--plugin-runtime-samples`, `--no-plugin-runtime-samples`	no	-	-	Enable/disable runtime plugin samples subdir.
`--plugin-runtime-benchmarks`, `--no-plugin-runtime-benchmarks`	no	-	-	Enable/disable runtime plugin benchmarks subdir.
`--plugin-runtime-radiance-tests`, `--no-plugin-runtime-radiance-tests`	no	-	-	Enable/disable Radiance runtime plugin tests.
`--plugin-runtime-radiance-rpc`, `--no-plugin-runtime-radiance-rpc`	no	-	-	Enable/disable Radiance RPC-compat transport backend.
`--plugin-runtime-radiance-direct`, `--no-plugin-runtime-radiance-direct`	no	-	-	Enable/disable Radiance direct-submit transport backend.
`--plugin-runtime-radiance-kmod`, `--no-plugin-runtime-radiance-kmod`	no	-	-	Enable/disable Radiance kmod transport backend.
`--compiler-scope`	no	-	`all, gemmini, npu, saturn, spacemit, none`	Limit compiler-plugin target registration scope. Only used when compiler plugin + compiler build are enabled.
`--build-compiler`, `--no-build-compiler`	no	-	-	Override IREE_BUILD_COMPILER for this build.
`--build-python-bindings`, `--no-build-python-bindings`	no	-	-	Override IREE_BUILD_PYTHON_BINDINGS for this build.
`--build-samples`, `--no-build-samples`	no	-	-	Override IREE_BUILD_SAMPLES for this build.
`--build-tests`, `--no-build-tests`	no	-	-	Override IREE_BUILD_TESTS for this build.
`--enable-libbacktrace`, `--no-enable-libbacktrace`	no	-	-	Override IREE_ENABLE_LIBBACKTRACE for this build.
`--enable-tracy`	no	`False`	-	Enable Tracy runtime tracing (IREE_ENABLE_RUNTIME_TRACING=ON, IREE_TRACING_MODE=4). Compatible with any --config.
`--offline-friendly`	no	`False`	-	Prefer settings that avoid network fetches in CMake (equivalent to --no-build-compiler --no-build-python-bindings --no-enable-libbacktrace unless explicitly overridden).
`--cmake-bin`	no	`cmake`	-	CMake executable to use (default: cmake).
`--use-system-cmake`	no	`False`	-	Use /usr/bin/cmake instead of cmake from PATH.
`--use-ccache`, `--no-use-ccache`	no	`True`	-	Enable/disable ccache compiler launchers (default: enabled).
`--cmake-arg`, `--configure-custom-arg`	no	`[]`	-	Extra argument forwarded to CMake configure (repeatable).
`--cmake-build-arg`, `--build-custom-arg`	no	`[]`	-	Extra argument forwarded to CMake build command (repeatable).
`--native-build-arg`	no	`[]`	-	Extra argument forwarded to the native build tool after '--' (repeatable).
`--clean`	no	`False`	-	Delete build directory before building
`--verbose`	no	`False`	-	Enable verbose build output

`--help` Output

usage: uv run tools/build.py [-h]
                             [--profile {firesim,full-plugin,gemmini,npu,package-firesim,package-host,package-spacemit,radiance,spacemit,vanilla}]
                             [--target {host,spacemit,firesim}]
                             [--config {debug,release,asan,trace,perf}]
                             [--cmake-target CMAKE_TARGET] [--with-plugin]
                             [--plugin-compiler | --no-plugin-compiler]
                             [--plugin-runtime | --no-plugin-runtime]
                             [--plugin-runtime-radiance | --no-plugin-runtime-radiance]
                             [--plugin-runtime-samples | --no-plugin-runtime-samples]
                             [--plugin-runtime-benchmarks | --no-plugin-runtime-benchmarks]
                             [--plugin-runtime-radiance-tests | --no-plugin-runtime-radiance-tests]
                             [--plugin-runtime-radiance-rpc | --no-plugin-runtime-radiance-rpc]
                             [--plugin-runtime-radiance-direct | --no-plugin-runtime-radiance-direct]
                             [--plugin-runtime-radiance-kmod | --no-plugin-runtime-radiance-kmod]
                             [--compiler-scope {all,gemmini,npu,saturn,spacemit,none}]
                             [--build-compiler | --no-build-compiler]
                             [--build-python-bindings | --no-build-python-bindings]
                             [--build-samples | --no-build-samples]
                             [--build-tests | --no-build-tests]
                             [--enable-libbacktrace | --no-enable-libbacktrace]
                             [--enable-tracy] [--offline-friendly]
                             [--cmake-bin CMAKE_BIN] [--use-system-cmake]
                             [--use-ccache | --no-use-ccache]
                             [--cmake-arg CMAKE_ARG]
                             [--cmake-build-arg CMAKE_BUILD_ARG]
                             [--native-build-arg NATIVE_BUILD_ARG] [--clean]
                             [--verbose]

Configure and build Merlin and target runtimes

options:
  -h, --help            show this help message and exit
  --profile {firesim,full-plugin,gemmini,npu,package-firesim,package-host,package-spacemit,radiance,spacemit,vanilla}
                        High-level user profile preset. Use this for normal
                        workflows; advanced flags may still override details.
  --target {host,spacemit,firesim}
                        Target platform.
  --config {debug,release,asan,trace,perf}
                        Build configuration type
  --cmake-target CMAKE_TARGET
                        Build specific CMake target (default: install)
  --with-plugin         Enable Merlin compiler+runtime plugins (legacy
                        umbrella switch).
  --plugin-compiler, --no-plugin-compiler
                        Enable/disable Merlin compiler plugin targets (default
                        follows --with-plugin).
  --plugin-runtime, --no-plugin-runtime
                        Enable/disable Merlin runtime plugin integration
                        (default follows --with-plugin).
  --plugin-runtime-radiance, --no-plugin-runtime-radiance
                        Enable/disable Radiance HAL runtime plugin path
                        (default: host+plugin only).
  --plugin-runtime-samples, --no-plugin-runtime-samples
                        Enable/disable runtime plugin samples subdir.
  --plugin-runtime-benchmarks, --no-plugin-runtime-benchmarks
                        Enable/disable runtime plugin benchmarks subdir.
  --plugin-runtime-radiance-tests, --no-plugin-runtime-radiance-tests
                        Enable/disable Radiance runtime plugin tests.
  --plugin-runtime-radiance-rpc, --no-plugin-runtime-radiance-rpc
                        Enable/disable Radiance RPC-compat transport backend.
  --plugin-runtime-radiance-direct, --no-plugin-runtime-radiance-direct
                        Enable/disable Radiance direct-submit transport
                        backend.
  --plugin-runtime-radiance-kmod, --no-plugin-runtime-radiance-kmod
                        Enable/disable Radiance kmod transport backend.
  --compiler-scope {all,gemmini,npu,saturn,spacemit,none}
                        Limit compiler-plugin target registration scope. Only
                        used when compiler plugin + compiler build are
                        enabled.
  --build-compiler, --no-build-compiler
                        Override IREE_BUILD_COMPILER for this build.
  --build-python-bindings, --no-build-python-bindings
                        Override IREE_BUILD_PYTHON_BINDINGS for this build.
  --build-samples, --no-build-samples
                        Override IREE_BUILD_SAMPLES for this build.
  --build-tests, --no-build-tests
                        Override IREE_BUILD_TESTS for this build.
  --enable-libbacktrace, --no-enable-libbacktrace
                        Override IREE_ENABLE_LIBBACKTRACE for this build.
  --enable-tracy        Enable Tracy runtime tracing
                        (IREE_ENABLE_RUNTIME_TRACING=ON, IREE_TRACING_MODE=4).
                        Compatible with any --config.
  --offline-friendly    Prefer settings that avoid network fetches in CMake
                        (equivalent to --no-build-compiler --no-build-python-
                        bindings --no-enable-libbacktrace unless explicitly
                        overridden).
  --cmake-bin CMAKE_BIN
                        CMake executable to use (default: cmake).
  --use-system-cmake    Use /usr/bin/cmake instead of cmake from PATH.
  --use-ccache, --no-use-ccache
                        Enable/disable ccache compiler launchers (default:
                        enabled).
  --cmake-arg CMAKE_ARG, --configure-custom-arg CMAKE_ARG
                        Extra argument forwarded to CMake configure
                        (repeatable).
  --cmake-build-arg CMAKE_BUILD_ARG, --build-custom-arg CMAKE_BUILD_ARG
                        Extra argument forwarded to CMake build command
                        (repeatable).
  --native-build-arg NATIVE_BUILD_ARG
                        Extra argument forwarded to the native build tool
                        after '--' (repeatable).
  --clean               Delete build directory before building
  --verbose             Enable verbose build output

`tools/compile.py`

Compile MLIR/ONNX models to target artifacts

Usage

usage: uv run tools/compile.py [-h] --target TARGET [--hw HW] [--quantized]
                               [--output-dir OUTPUT_DIR]
                               [--build-dir BUILD_DIR]
                               [--compile-to COMPILE_TO]
                               [--dump-compilation-phases-to DUMP_COMPILATION_PHASES_TO]
                               [--iree-compile-arg IREE_COMPILE_ARG]
                               [--reuse-imported-mlir] [--tracy]
                               [--dump-artifacts] [--dump-phases]
                               [--dump-graph] [--build-benchmarks]
                               input_path

Arguments

Argument	Required	Default	Choices	Help
`input_path`	yes	-	-	Path to the model directory OR specific .mlir/.onnx file
`--target`	yes	-	-	Target YAML config file name (e.g., spacemit_x60)
`--hw`	no	-	-	Hardware sub-target from YAML (e.g., RVV, OPU). If omitted, uses default_hw from YAML.
`--quantized`	no	`False`	-	Force quantized mode (auto-detected if .q. in filename)
`--output-dir`	no	-	-	Override output directory (default: build/compiled_models//_/). If set, all generated files/artifacts are written under this directory.
`--build-dir`	no	`host-vanilla-release`	-	Which build directory to use for compiler tools (default: host-vanilla-release). If omitted and target YAML uses plugin_flags, compile.py auto-selects host-merlin-release.
`--compile-to`	no	-	-	Stop compilation at the given phase (for example: global-optimization). When set, output is emitted as an intermediate MLIR file.
`--dump-compilation-phases-to`	no	-	-	Directory for --dump-compilation-phases-to. If omitted and --dump-phases is set, defaults to /phases/.
`--iree-compile-arg`, `--compilation-custom-arg`	no	`[]`	-	Extra flag forwarded directly to iree-compile. Repeat for multiple flags.
`--reuse-imported-mlir`	no	`False`	-	Reuse an existing output MLIR instead of refreshing from explicit input files. By default, explicit input files are re-imported/re-copied.
`--tracy`	no	`False`	-	Enable Tracy profiling flags: embed debug info, use system linking, and enable debug symbols in generated code. Equivalent to --iree-hal-executable-debug-level=3 --iree-llvmcpu-link-embedded=false --iree-llvmcpu-debug-symbols=true
`--dump-artifacts`	no	`False`	-	Dump executable sources, binaries, and configs
`--dump-phases`	no	`False`	-	Dump MLIR compilation phases
`--dump-graph`	no	`False`	-	Dump the flow dispatch graph (.dot)
`--build-benchmarks`	no	`False`	-	Recompile individual dispatch benchmarks and zip them

`--help` Output

usage: uv run tools/compile.py [-h] --target TARGET [--hw HW] [--quantized]
                               [--output-dir OUTPUT_DIR]
                               [--build-dir BUILD_DIR]
                               [--compile-to COMPILE_TO]
                               [--dump-compilation-phases-to DUMP_COMPILATION_PHASES_TO]
                               [--iree-compile-arg IREE_COMPILE_ARG]
                               [--reuse-imported-mlir] [--tracy]
                               [--dump-artifacts] [--dump-phases]
                               [--dump-graph] [--build-benchmarks]
                               input_path

Compile MLIR/ONNX models to target artifacts

positional arguments:
  input_path            Path to the model directory OR specific .mlir/.onnx
                        file

options:
  -h, --help            show this help message and exit
  --target TARGET       Target YAML config file name (e.g., spacemit_x60)
  --hw HW               Hardware sub-target from YAML (e.g., RVV, OPU). If
                        omitted, uses default_hw from YAML.
  --quantized           Force quantized mode (auto-detected if .q. in
                        filename)
  --output-dir OUTPUT_DIR
                        Override output directory (default:
                        build/compiled_models/<model>/<target>_<basename>/).
                        If set, all generated files/artifacts are written
                        under this directory.
  --build-dir BUILD_DIR
                        Which build directory to use for compiler tools
                        (default: host-vanilla-release). If omitted and target
                        YAML uses plugin_flags, compile.py auto-selects host-
                        merlin-release.
  --compile-to COMPILE_TO
                        Stop compilation at the given phase (for example:
                        global-optimization). When set, output is emitted as
                        an intermediate MLIR file.
  --dump-compilation-phases-to DUMP_COMPILATION_PHASES_TO
                        Directory for --dump-compilation-phases-to. If omitted
                        and --dump-phases is set, defaults to
                        <output_dir>/phases/.
  --iree-compile-arg IREE_COMPILE_ARG, --compilation-custom-arg IREE_COMPILE_ARG
                        Extra flag forwarded directly to iree-compile. Repeat
                        for multiple flags.
  --reuse-imported-mlir
                        Reuse an existing output MLIR instead of refreshing
                        from explicit input files. By default, explicit input
                        files are re-imported/re-copied.
  --tracy               Enable Tracy profiling flags: embed debug info, use
                        system linking, and enable debug symbols in generated
                        code. Equivalent to --iree-hal-executable-debug-
                        level=3 --iree-llvmcpu-link-embedded=false --iree-
                        llvmcpu-debug-symbols=true
  --dump-artifacts      Dump executable sources, binaries, and configs
  --dump-phases         Dump MLIR compilation phases
  --dump-graph          Dump the flow dispatch graph (.dot)
  --build-benchmarks    Recompile individual dispatch benchmarks and zip them

`tools/setup.py`

Bootstrap developer environment and toolchains

Usage

usage: uv run tools/setup.py [-h] [--env-name ENV_NAME] [--env-file ENV_FILE]
                             [--offline] [--skip-conda] [--skip-pip]
                             [--python-deps {auto,uv,pip}]
                             [--conda-no-plugins | --no-conda-no-plugins]
                             [--submodules-profile {core,npu,smolvla,full}]
                             [--submodule-path SUBMODULE_PATH]
                             [--submodule-paths-recursive | --no-submodule-paths-recursive]
                             [--submodule-depth SUBMODULE_DEPTH]
                             [--submodule-jobs SUBMODULE_JOBS]
                             [--submodule-sync]
                             [--toolchain-target {spacemit,firesim,all}]
                             [--with-qemu] [--toolchain-force]
                             [--prebuilt-artifact {host-linux-x86_64,host-macos,runtime-spacemit,runtime-saturnopu}]
                             [--prebuilt-tag PREBUILT_TAG]
                             [--prebuilt-repo PREBUILT_REPO]
                             [--prebuilt-force]
                             [{all,env,toolchain,submodules,prebuilt}]

Arguments

Argument	Required	Default	Choices	Help
`component`	no	`all`	`all, env, toolchain, submodules, prebuilt`
`--env-name`	no	`merlin-dev`	-	Conda environment name to update/install packages into (default: merlin-dev).
`--env-file`	no	`<repo>/env_linux.yml`	-	Conda environment file to use. Default is platform-specific: env_linux.yml
`--offline`	no	`False`	-	Run setup in offline mode when possible.
`--skip-conda`	no	`False`	-	Skip conda environment sync.
`--skip-pip`	no	`False`	-	Skip Python dependency sync (uv/pip).
`--python-deps`	no	`auto`	`auto, uv, pip`	Python dependency installer. 'auto' prefers uv sync with uv.lock and falls back to pip requirements.
`--conda-no-plugins`, `--no-conda-no-plugins`	no	-	-	Force CONDA_NO_PLUGINS for conda env update. If unset, setup.py retries with CONDA_NO_PLUGINS=true on failure.
`--submodules-profile`	no	`core`	`core, npu, smolvla, full`	Which submodule profile to initialize for the current Merlin checkout (default: core).
`--submodule-path`	no	`[]`	-	Additional top-level submodule path to initialize (repeatable).
`--submodule-paths-recursive`, `--no-submodule-paths-recursive`	no	`False`	-	Whether extra --submodule-path entries should be initialized recursively.
`--submodule-depth`	no	`1`	-	Shallow depth for submodule fetches (default: 1). Use 0 for full history.
`--submodule-jobs`	no	`8`	-	Parallel submodule fetch jobs (default: 8).
`--submodule-sync`	no	`False`	-	Run `git submodule sync --recursive` before updating. Submodule SHAs still come from the current Merlin commit.
`--toolchain-target`	no	`spacemit`	`spacemit, firesim, all`	Which toolchain target to install (default: spacemit).
`--with-qemu`	no	`False`	-	For firesim toolchain setup, also install QEMU.
`--toolchain-force`	no	`False`	-	Reinstall toolchains even if the destination already exists.
`--prebuilt-artifact`	no	`host-linux-x86_64`	`host-linux-x86_64, host-macos, runtime-spacemit, runtime-saturnopu`	Which published Merlin prebuilt artifact to install.
`--prebuilt-tag`	no	`latest`	-	GitHub release tag to download from, or 'latest' (default: latest).
`--prebuilt-repo`	no	`ucb-bar/merlin`	-	GitHub repository containing release assets (default: ucb-bar/merlin).
`--prebuilt-force`	no	`False`	-	Replace an existing destination build tree when installing a prebuilt artifact.

`--help` Output

usage: uv run tools/setup.py [-h] [--env-name ENV_NAME] [--env-file ENV_FILE]
                             [--offline] [--skip-conda] [--skip-pip]
                             [--python-deps {auto,uv,pip}]
                             [--conda-no-plugins | --no-conda-no-plugins]
                             [--submodules-profile {core,npu,smolvla,full}]
                             [--submodule-path SUBMODULE_PATH]
                             [--submodule-paths-recursive | --no-submodule-paths-recursive]
                             [--submodule-depth SUBMODULE_DEPTH]
                             [--submodule-jobs SUBMODULE_JOBS]
                             [--submodule-sync]
                             [--toolchain-target {spacemit,firesim,all}]
                             [--with-qemu] [--toolchain-force]
                             [--prebuilt-artifact {host-linux-x86_64,host-macos,runtime-spacemit,runtime-saturnopu}]
                             [--prebuilt-tag PREBUILT_TAG]
                             [--prebuilt-repo PREBUILT_REPO]
                             [--prebuilt-force]
                             [{all,env,toolchain,submodules,prebuilt}]

Bootstrap developer environment and toolchains

positional arguments:
  {all,env,toolchain,submodules,prebuilt}

options:
  -h, --help            show this help message and exit
  --env-name ENV_NAME   Conda environment name to update/install packages into
                        (default: merlin-dev).
  --env-file ENV_FILE   Conda environment file to use. Default is platform-
                        specific: env_linux.yml
  --offline             Run setup in offline mode when possible.
  --skip-conda          Skip conda environment sync.
  --skip-pip            Skip Python dependency sync (uv/pip).
  --python-deps {auto,uv,pip}
                        Python dependency installer. 'auto' prefers uv sync
                        with uv.lock and falls back to pip requirements.
  --conda-no-plugins, --no-conda-no-plugins
                        Force CONDA_NO_PLUGINS for conda env update. If unset,
                        setup.py retries with CONDA_NO_PLUGINS=true on
                        failure.
  --submodules-profile {core,npu,smolvla,full}
                        Which submodule profile to initialize for the current
                        Merlin checkout (default: core).
  --submodule-path SUBMODULE_PATH
                        Additional top-level submodule path to initialize
                        (repeatable).
  --submodule-paths-recursive, --no-submodule-paths-recursive
                        Whether extra --submodule-path entries should be
                        initialized recursively.
  --submodule-depth SUBMODULE_DEPTH
                        Shallow depth for submodule fetches (default: 1). Use
                        0 for full history.
  --submodule-jobs SUBMODULE_JOBS
                        Parallel submodule fetch jobs (default: 8).
  --submodule-sync      Run `git submodule sync --recursive` before updating.
                        Submodule SHAs still come from the current Merlin
                        commit.
  --toolchain-target {spacemit,firesim,all}
                        Which toolchain target to install (default: spacemit).
  --with-qemu           For firesim toolchain setup, also install QEMU.
  --toolchain-force     Reinstall toolchains even if the destination already
                        exists.
  --prebuilt-artifact {host-linux-x86_64,host-macos,runtime-spacemit,runtime-saturnopu}
                        Which published Merlin prebuilt artifact to install.
  --prebuilt-tag PREBUILT_TAG
                        GitHub release tag to download from, or 'latest'
                        (default: latest).
  --prebuilt-repo PREBUILT_REPO
                        GitHub repository containing release assets (default:
                        ucb-bar/merlin).
  --prebuilt-force      Replace an existing destination build tree when
                        installing a prebuilt artifact.

`tools/ci.py`

Run repository CI/lint/patch workflows

Usage

usage: uv run tools/ci.py [-h]
                          {lint,cli-docs-drift,patch-gate,release-status} ...

Arguments

Argument	Required	Default	Choices	Help

Subcommand `cli-docs-drift`

usage: uv run tools/ci.py cli-docs-drift [-h]

Argument	Required	Default	Choices	Help

Subcommand `lint`

usage: uv run tools/ci.py lint [-h]

Argument	Required	Default	Choices	Help

Subcommand `patch-gate`

usage: uv run tools/ci.py patch-gate [-h]

Argument	Required	Default	Choices	Help

Subcommand `release-status`

usage: uv run tools/ci.py release-status [-h] [--tracking-file TRACKING_FILE]
                                         [--offline] [--json]

Argument	Required	Default	Choices
`--tracking-file`	no	`<repo>/.github/upstream_tracking.yaml`	-
`--offline`	no	`False`	-
`--json`	no	`False`	-

`--help` Output

usage: uv run tools/ci.py [-h]
                          {lint,cli-docs-drift,patch-gate,release-status} ...

Run repository CI/lint/patch workflows

positional arguments:
  {lint,cli-docs-drift,patch-gate,release-status}
    lint                Run linters (shellcheck, python)
    cli-docs-drift      Regenerate docs/reference/cli.md and fail on drift
    patch-gate          CI gate: apply, verify, drift check
    release-status      Check upstream IREE versions

options:
  -h, --help            show this help message and exit

`tools/patches.py`

Apply/verify/refresh/drift patch stack

Usage

usage: uv run tools/patches.py [-h] {verify,log,drift,export-upstream} ...

Arguments

Argument	Required	Default	Choices	Help

Subcommand `drift`

usage: uv run tools/patches.py drift [-h]

Argument	Required	Default	Choices	Help

Subcommand `export-upstream`

usage: uv run tools/patches.py export-upstream [-h] commit

Argument	Required	Default	Choices	Help
`commit`	yes	-	-	Commit hash to export

Subcommand `log`

usage: uv run tools/patches.py log [-h]

Argument	Required	Default	Choices	Help

Subcommand `verify`

usage: uv run tools/patches.py verify [-h]

Argument	Required	Default	Choices	Help

`--help` Output

usage: uv run tools/patches.py [-h] {verify,log,drift,export-upstream} ...

Apply/verify/refresh/drift patch stack

positional arguments:
  {verify,log,drift,export-upstream}
    verify              Verify submodule is a clean rebase of pinned upstream
    log                 Show Merlin commits on top of upstream base
    drift               Check how far behind upstream the base is
    export-upstream     Export a commit as format-patch for upstream PR

options:
  -h, --help            show this help message and exit

`tools/benchmark.py`

Run benchmark helper scripts

Usage

usage: uv run tools/benchmark.py [-h]
                                 target {compile-dual-vmfb,run-dual-remote}
                                 ...

Arguments

Argument	Required	Default	Choices	Help
`target`	yes	-	-	Target name from config/targets.json
`action`	yes	-	`compile-dual-vmfb, run-dual-remote`	Benchmark action
`extra_args`	yes	-	-

`--help` Output

usage: uv run tools/benchmark.py [-h]
                                 target {compile-dual-vmfb,run-dual-remote}
                                 ...

Run benchmark helper scripts

positional arguments:
  target                Target name from config/targets.json
  {compile-dual-vmfb,run-dual-remote}
                        Benchmark action
  extra_args

options:
  -h, --help            show this help message and exit

CLI Reference

tools/merlin.py

Usage

Arguments

Subcommand benchmark

Subcommand build

Subcommand chipyard

Subcommand ci

Subcommand compile

Subcommand patches

Subcommand ray

Subcommand setup

Subcommand targetgen

--help Output

tools/build.py

Usage

Arguments

--help Output

tools/compile.py

Usage

Arguments

--help Output

tools/setup.py

Usage

Arguments

--help Output

tools/ci.py

Usage

Arguments

Subcommand cli-docs-drift

Subcommand lint

Subcommand patch-gate

Subcommand release-status

--help Output

tools/patches.py

Usage

Arguments

Subcommand drift

Subcommand export-upstream

Subcommand log

Subcommand verify

--help Output

tools/benchmark.py

Usage

Arguments

--help Output

`tools/merlin.py`

Subcommand `benchmark`

Subcommand `build`

Subcommand `chipyard`

Subcommand `ci`

Subcommand `compile`

Subcommand `patches`

Subcommand `ray`

Subcommand `setup`

Subcommand `targetgen`

`--help` Output

`tools/build.py`

`--help` Output

`tools/compile.py`

`--help` Output

`tools/setup.py`

`--help` Output

`tools/ci.py`

Subcommand `cli-docs-drift`

Subcommand `lint`

Subcommand `patch-gate`

Subcommand `release-status`

`--help` Output

`tools/patches.py`

Subcommand `drift`

Subcommand `export-upstream`

Subcommand `log`

Subcommand `verify`

`--help` Output

`tools/benchmark.py`

`--help` Output