`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=…). Give a CLI token the Read and Operate scopes; a token with only Read can look but every change answers 403 insufficient-scope, and admin-only commands such as swarm release also need Admin, which only an admin can grant. Tokens created before scopes existed keep their owner's full power.

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 train --config <file.json> --pretrained Qwen/Qwen3-8B --lora`	Fine-tune with LoRA adapters over frozen weights
`swarm train --config <file.json> --plan`	Ask the leader how it would place the job on its ready nodes now: fellows, GPUs, layers, boundary, wire. Submits nothing
`swarm train --config <file.json> --compression fixed_int4 --freeze-backbone`	Load a model, add a 4-bit boundary and export it - nothing trains
`swarm jobs`	List jobs (filter with `--status`)
`swarm jobs show <job_id>`	A job's placement: stages, fellows, GPUs, layer ranges, where the boundary fell and why, wire and transport
`swarm watch <job_id>`	Stream live loss + per-fellow status
`swarm stop <job_id>`	Checkpoint and cancel a running job
`swarm resume <job_id>`	Start a stopped pipeline run again from its last committed snapshot, on the same nodes

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.

AI agents (MCP)¶

The leader serves the Model Context Protocol at /mcp, so Claude Code, Claude Desktop, Cursor or any MCP client can do what the web UI does, with your token's scopes. Setup per client, scopes, toolsets and the safety model: Use SilentSwarm from an AI agent; every tool: MCP tool reference.

Command	What it does
`swarm mcp config`	Ready-to-paste setup for every client, with your leader's URL
`swarm mcp config --client claude-code`	Just one client: `claude-code`, `claude-desktop`, `cursor`, `vscode` or `json` (the snippet goes to stdout, notes to stderr)
`swarm mcp config --auth oauth`	No token: setup for clients that sign in through the browser (Claude Code, Cursor, VS Code, any OAuth-capable client; Claude Desktop's bridge after `swarm login`)
`swarm mcp config --toolsets pools,admin`	Point the client at more toolsets (`all` for every one)
`swarm mcp serve`	A stdio MCP server that forwards to the leader - what Claude Desktop starts
`swarm mcp tools [--toolsets all]`	The tools your token can call, marked read / write / destructive
`swarm login`	Sign the CLI in through the browser - no API token; every command and `swarm mcp serve` use it
`swarm login --device`	The same from a machine without a browser: type the code it shows on any device
`swarm logout`	End the CLI's sign-in (revoked on the leader, forgotten here)

The snippets never contain the token: Claude Code, Cursor and the generic JSON read it from $SWARM_API_TOKEN, and swarm mcp serve uses the same credential as every other command (--token, SWARM_API_TOKEN, then api_token in ~/.swarm/config.toml, then the sign-in from swarm login). Give it Read to look and Operate to run jobs, load models and manage buckets.

export SWARM_API_TOKEN=sk-swarm-...
swarm mcp config --client claude-code     # prints the `claude mcp add ...` line

{
  "mcpServers": {
    "silentswarm": {
      "command": "swarm",
      "args": ["--leader-url", "https://your-leader.example.com", "mcp", "serve"]
    }
  }
}

That is the Claude Desktop entry swarm mcp config --client claude-desktop prints. Desktop does not use your shell's PATH, so put the full path to swarm in command if it cannot start it. swarm mcp serve writes only MCP messages to stdout; a refused token (HTTP 401), an unreachable leader or a wrong --leader-url is explained on stderr and to the client as the answer to its request, and the bridge exits with status 1.

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 jobs show <job_id>                         # where each stage runs
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.

swarm CLI cheat sheet¶