swarm CLI cheat sheet

The most-used commands, grouped by what you're doing. Full reference: CLI Reference · run swarm <command> --help for every flag.

Setup

Point the CLI at your leader once (or pass --leader-url each time):

# ~/.swarm/config.toml
leader_url = "https://your-leader.example.com"

Authenticate with an API token (create one on the Profile page, or SWARM_API_TOKEN=…):

export SWARM_API_TOKEN=sk-swarm-...
swarm info          # quickstart + workflow summary

Cluster status

Command	What it does
swarm nodes	Cluster node status, resources, network metrics
swarm devices	GPU / device inventory across fellows
swarm fellows	List registered fellows (ids, state)

Training

Command	What it does
swarm configs	List experiment configs you can run by name
swarm sweep --name <cfg> --dry-run	Preview the jobs a sweep would queue
swarm sweep --name <cfg>	Submit an experiment-grid sweep
swarm train --config <file.json> --wait	Submit one training job and wait
swarm jobs	List jobs (filter with --status)
swarm watch <job_id>	Stream live loss + per-fellow status
swarm stop <job_id>	Checkpoint and cancel a running job

Inference

Command	What it does
swarm models	List servable (trained) models
swarm model-load <model_id>	Load a model onto a fellow to serve it
swarm infer <model_id> "<prompt>"	One-shot chat completion
swarm model-unload <model_id>	Unload a model and free its VRAM

The loaded model is also reachable at the OpenAI-compatible POST /v1/chat/completions endpoint with your API token.

Cluster operations

Command	What it does
swarm update [--fellow-id N]	Push an UPDATE so fellows re-bootstrap from the leader
swarm release --all	Release fellows from the registry (--purge-install to clean them)
swarm set-speed --fellow-id N --tx-mbps 50	Per-fellow network limits
swarm start-cluster --fellows 2	Start a local leader + fellows (dev)
swarm stop-cluster / restart-cluster	Stop / restart the local cluster

Typical flows

Fine-tune, then chat with the result:

swarm configs                                   # pick a config
swarm sweep --name exp_qwen2_5_3b_bottleneck_long --dry-run   # preview
swarm sweep --name exp_qwen2_5_3b_bottleneck_long            # run
swarm jobs                                       # grab the job id
swarm watch <job_id>                             # live metrics
swarm models                                     # the trained model appears
swarm model-load <model_id>
swarm infer <model_id> "Summarize the plot of Hamlet in two sentences."

Add / recycle a worker node:

swarm fellows                    # who's connected
swarm update --fellow-id 62676   # re-bootstrap one fellow
swarm release --all --purge-install   # clear the cluster and start fresh

Tip: swarm llm-doc prints an LLM-friendly full CLI reference you can pipe into an assistant.