CLI Overview

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

Global options

Option	Description
-v / --verbose	Increase verbosity (stackable: -v, -vv, -vvv)
-q / --quiet	Suppress all output except errors (for scripting)
--version	Show version and exit
--help	Show help for any command

Verbosity levels

Flag	Level	Output
(default)	PROGRESS	Phase and step output only
-v	INFO	Adds detail lines
-vv	VERBOSE	Adds timestamps and logger names
-vvv	DEBUG	Full SSH command output, script diagnostics
-q	WARNING	Errors and warnings only (for scripting)

Command groups

Workload commands

Command	Description
sparkrun run <recipe>	Launch an inference workload
sparkrun stop [target]	Stop a running workload (recipe name or cluster ID)
sparkrun logs <target>	Re-attach to workload logs (recipe name or cluster ID)
sparkrun status	Show running sparkrun containers (alias for cluster status)
sparkrun benchmark <recipe>	Benchmark an inference recipe (auto: run → benchmark → stop)
sparkrun update	Update sparkrun + registries (--no-update-registries to skip)

Recipe commands

Command	Description
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 recipe update	Refresh recipe registries from git

Scoping to one registry

list and search accept an @registry scope in the query itself: sparkrun list @community and sparkrun list @community/qwen are equivalent to --registry community. An unknown or disabled registry is reported as an error rather than returning “no recipes found”.

Tip

Recipes can be local names, file paths, URLs, or Spark Arena shortcuts (@spark-arena/<recipe-id>). For example: sparkrun run @spark-arena/abc123 or sparkrun show @spark-arena/abc123.

Registry commands

Command	Description
sparkrun registry list	List 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-profiles	List 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-metadata	Export registry metadata
sparkrun registry revert-to-defaults	Restore the built-in default registry list

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

Cluster commands

Command	Description
sparkrun cluster create <name>	Create a new named cluster
sparkrun cluster update <name>	Update hosts, description, or user
sparkrun cluster list	List 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-default	Remove the default cluster setting
sparkrun cluster default	Show the current default cluster
sparkrun cluster status	Show sparkrun containers running on cluster hosts
sparkrun cluster check-job <target>	Check if a job is running (exit 0 = running, 1 = not)
sparkrun cluster monitor	Live-monitor CPU, RAM, and GPU metrics across hosts
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)

Export commands

Command	Description
sparkrun export recipe <recipe>	Export a normalized recipe to stdout or file
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.

Tune commands

Command	Description
sparkrun tune sglang <recipe>	Tune SGLang fused MoE Triton kernels
sparkrun tune vllm <recipe>	Tune vLLM fused MoE Triton kernels

See tune for details.

Proxy commands

Command	Description
sparkrun proxy start	Start the LiteLLM-based inference proxy
sparkrun proxy stop	Stop the running proxy
sparkrun proxy status	Show proxy status and registered models
sparkrun proxy models	List 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 list	List configured aliases

See proxy for details.

Arena commands

Command	Description
sparkrun arena login	Authenticate with Spark Arena via OAuth
sparkrun arena logout	Remove stored Spark Arena credentials
sparkrun arena status	Show Spark Arena login status
sparkrun arena benchmark <recipe>	Benchmark a recipe and submit results to Spark Arena

See Spark Arena for the leaderboard and community benchmarks.

Setup commands

Command	Description
sparkrun setup install	Install sparkrun as a uv tool + tab-completion + registry sync
sparkrun setup completion	Install shell tab-completion (bash/zsh/fish)
sparkrun setup update	Update sparkrun + registries (alias: sparkrun update)
sparkrun setup ssh	Set up passwordless SSH mesh across hosts
sparkrun setup cx7	Detect and configure ConnectX-7 NICs across hosts
sparkrun setup fix-permissions	Fix root-owned HF cache files on cluster hosts
sparkrun setup clear-cache	Drop Linux page cache on cluster hosts to free memory
sparkrun setup earlyoom	Install and configure earlyoom OOM protection on cluster hosts
sparkrun setup wizard	Guided setup wizard (cluster, SSH, CX7, Docker group, sudoers, earlyoom)
sparkrun setup check	Non-destructive readiness probe of a cluster’s hosts
sparkrun setup diagnose	Collect hardware/firmware/network/Docker diagnostics
sparkrun setup docker-group	Add the SSH user to the docker group on cluster hosts (usermod -aG docker)
sparkrun setup fe-system-update	Full system update on DGX Spark Founders Edition hosts (apt + firmware + reboot)
sparkrun setup telemetry	View or change anonymous telemetry settings
sparkrun setup features	Manage 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.