Skip to content

CLI Overview

sparkrun provides a unified CLI for managing LLM inference workloads on DGX Spark systems.

OptionDescription
-v / --verboseIncrease verbosity (stackable: -v, -vv, -vvv)
-q / --quietSuppress all output except errors (for scripting)
--versionShow version and exit
--helpShow help for any command
FlagLevelOutput
(default)PROGRESSPhase and step output only
-vINFOAdds detail lines
-vvVERBOSEAdds timestamps and logger names
-vvvDEBUGFull SSH command output, script diagnostics
-qWARNINGErrors and warnings only (for scripting)
CommandDescription
sparkrun run <recipe>Launch an inference workload
sparkrun build <recipe>Prepare assets without inference; advanced command
sparkrun stop [target]Stop a running workload (recipe name or workload ID)
sparkrun logs <target>Re-attach to workload logs (recipe name or workload ID)
sparkrun statusShow running sparkrun containers (alias for cluster status)
sparkrun benchmark <recipe>Benchmark an inference recipe (auto: run → benchmark → stop)
sparkrun benchmark <recipe> --arenaBenchmark and submit results to Spark Arena
sparkrun updateUpdate core, compatible managed plugins, and registries; --no-update-plugins skips plugin fetching
CommandDescription
sparkrun list [query]List available recipes (alias)
sparkrun show <recipe>Show recipe details + VRAM estimate (alias)
sparkrun search <query>Search recipes (alias)
sparkrun recipe list [query]List available recipes from all registries
sparkrun recipe show <recipe>Show detailed recipe information
sparkrun recipe search <query>Search for recipes by name, model, or description
sparkrun recipe validate <recipe>Validate a recipe file
sparkrun recipe vram <recipe>Estimate VRAM usage for a recipe
sparkrun registry update [NAME]Refresh all enabled recipe registries, or one named registry, from git
CommandDescription
sparkrun registry listList configured recipe registries
sparkrun registry add <url>Add a registry from a repo manifest
sparkrun registry remove <name>Remove a recipe registry
sparkrun registry enable <name>Enable a recipe registry
sparkrun registry disable <name>Disable a recipe registry
sparkrun registry update [name]Update registries from git
sparkrun registry list-benchmark-profilesList available benchmark profiles
sparkrun registry show-benchmark-profile <name>Show benchmark profile details
sparkrun registry trust <name>Trust a registry’s recipes (skip hook confirmation)
sparkrun registry untrust <name>Revoke a registry’s trust
sparkrun registry export-metadataExport registry metadata
sparkrun registry revert-to-defaultsRestore the built-in default registry list

Spark Arena is included as a default registry. See Registries for details.

CommandDescription
sparkrun cluster create <name>Create a new named cluster
sparkrun cluster update <name>Update hosts, description, or user
sparkrun cluster listList all saved clusters
sparkrun cluster show <name>Show details of a saved cluster
sparkrun cluster delete <name>Delete a saved cluster
sparkrun cluster set-default <name>Set the default cluster
sparkrun cluster unset-defaultRemove the default cluster setting
sparkrun cluster defaultShow the current default cluster
sparkrun cluster statusShow sparkrun containers running on cluster hosts
sparkrun cluster check-job <target>Check if a job is running (exit 0 = running, 1 = not)
sparkrun cluster monitorLive host metrics with sensor history and interactive workload logs with search and export
sparkrun cluster inspect [name]Show effective cluster config and check remote cache dirs
sparkrun cluster import svd <path>Import a spark-vllm-docker .env file into a cluster (aliased as eugr)
CommandDescription
sparkrun export recipe <recipe>Export a normalized recipe to stdout or file
sparkrun export recipe <recipe> --realizeResolve hardware-specific settings and pin image/model references
sparkrun export running-recipe <target>Export the effective recipe from a running workload
sparkrun export systemd <target>Generate (and optionally install) a systemd service for persistent inference

See export for details.

CommandDescription
sparkrun tune sglang <recipe>Tune SGLang fused MoE or dense block-FP8 kernels
sparkrun tune vllm <recipe>Tune vLLM fused MoE or dense FP8 kernels

See tune for details.

CommandDescription
sparkrun proxy startStart the selected gateway (LiteLLM by default)
sparkrun proxy stopStop the running proxy
sparkrun proxy statusShow proxy status and registered models
sparkrun proxy systemd installInstall and enable a Linux proxy service
sparkrun proxy systemd statusInspect the service and recent journal output
sparkrun proxy systemd uninstallStop, disable, and remove the service
sparkrun proxy modelsList models registered with the proxy
sparkrun proxy load <recipe>Load a model via sparkrun run and register with proxy
sparkrun proxy unload <recipe>Stop a model and remove from proxy
sparkrun proxy alias add <name> <model>Add a model alias
sparkrun proxy alias remove <name>Remove a model alias
sparkrun proxy alias listList configured aliases

See proxy for details.

These commands manage Spark Arena authentication.

CommandDescription
sparkrun arena loginAuthenticate with Spark Arena via OAuth
sparkrun arena logoutRemove stored Spark Arena credentials
sparkrun arena statusShow Spark Arena login status

Use sparkrun benchmark <recipe> --arena to run and submit benchmarks. See the Spark Arena tutorial for the submission workflow and Spark Arena for the leaderboard.

CommandDescription
sparkrun setup installInstall sparkrun as a uv tool + tab-completion + registry sync
sparkrun setup completionInstall shell tab-completion (bash/zsh/fish)
sparkrun setup updateUpdate core, plugins, and registries; supports --no-update-plugins and --no-update-registries
sparkrun setup sshSet up passwordless SSH mesh across hosts
sparkrun setup cx7Detect and configure ConnectX-7 NICs across hosts
sparkrun setup fix-permissionsFix root-owned HF cache files on cluster hosts
sparkrun setup clear-cacheDrop Linux page cache on cluster hosts to free memory
sparkrun setup earlyoomInstall and configure earlyoom OOM protection on cluster hosts
sparkrun setup wizardGuided setup wizard (cluster, SSH, CX7, Docker group, sudoers, earlyoom)
sparkrun setup checkNon-destructive readiness probe of a cluster’s hosts
sparkrun setup diagnoseCollect hardware/firmware/network/Docker diagnostics
sparkrun setup docker-groupAdd the SSH user to the docker group on cluster hosts (usermod -aG docker)
sparkrun setup fe-system-updateFull system update on DGX Spark Founders Edition hosts (apt + firmware + reboot)
sparkrun setup telemetryView or change anonymous telemetry settings
sparkrun setup featuresManage feature flags (list/enable/disable/reset)
sparkrun setup uninstall [cluster]Reverse the wizard’s changes for a cluster, in reverse order

sparkrun setup tailscale (publish an inference endpoint on a tailnet) ships gated behind a feature flag and is hidden until enabled. See Feature Flags.

CommandReference
sparkrun plugins list/add/update/remove/rollbackManaged plugin commands; use one subcommand at a time
sparkrun daemonDaemon lifecycle and client; optional feature, direct CLI remains default
sparkrun model-cacheModel-cache commands; inspect, repair, adopt, retain, prune, and delete cached models
sparkrun setup ssh-rotate-keysConfirmed identity rotation

Show advanced help with SPARKRUN_ADVANCED=1. Feature gates remain separate from visibility. See What’s New in 0.4.0 for release highlights.