Skip to content

swarm CLI reference

Every swarm command with its arguments, options and the leader API routes it calls. The task-by-task guide is the CLI cheat sheet; the same actions from an AI agent are in the MCP tool reference.

Global options

Given before the command: swarm --format json jobs.

Option Kind What it does
--leader-url option Leader base URL
--token option API bearer token (default: $SWARM_API_TOKEN, then api_token in ~/.swarm/config.toml, then the sign-in from swarm login)
--pool option The pool to act on (default: $SWARM_POOL, then pool in ~/.swarm/config.toml - see swarm pools use)
--profile option Use [profiles.<name>] of ~/.swarm/config.toml (its leader_url, api_token, pool); default: $SWARM_PROFILE
--format option Output format: table or json (default: table)
--version flag -
--install-completion flag Install completion for the current shell.
--show-completion flag Show completion for the current shell, to copy it or customize the installation.

Output. --format json prints the API's answer unchanged; errors go to stderr, so stdout stays parseable.

Exit codes. 0 done; 1 failed (an API error, the leader unreachable, nothing by that name); 2 a usage error, or a destructive command that was not confirmed - without a terminal it needs --yes; 130 interrupted.

Naming things. A pool, bucket or org is its id, owner/slug (as in the page address), a slug of your own, or the pasted page URL. A job or model id may be shortened to a unique prefix. Commands that act on one pool use --pool, else SWARM_POOL, else the default set with swarm pools use.

Coverage. Of the 157 API routes the web UI uses that belong on the CLI, 157 have a command; swarm api reaches any route by its path. 41 more are browser-only on purpose.

Commands

swarm admin

The admin pages (an admin credential with the admin scope), and admin host for the commands on the leader host.

Subcommands: audit, banners, funnel, host, inquiries, mail, mesh, pools, quotas, users, waitlist.

swarm admin audit

The audit log, newest first.

Parameter Kind What it does
--event option Events starting with this, e.g. auth. or admin.
--search, -q option In the event, actor or detail
--limit option (default: 100)

Calls: GET /api/v1/admin/audit

swarm admin banners

Site banners (no subcommand), create, update, delete.

Subcommands: create, delete, list, update.

Calls: GET /api/v1/admin/banners

swarm admin banners create

Show a banner on every page (and to CLI users, on stderr).

Parameter Kind What it does
MESSAGE argument What every page shows (up to 500 characters)
--level option info, warning or success (default: info)
--inactive flag Create it switched off

Calls: POST /api/v1/admin/banners

swarm admin banners delete

Delete a banner.

Parameter Kind What it does
BANNER_ID argument The banner's id
--yes, -y flag Do it without asking (needed without a terminal, e.g. in a script).

Calls: DELETE /api/v1/admin/banners/{banner_id}, GET /api/v1/admin/banners

swarm admin banners list

Every site banner, active or not.

Calls: GET /api/v1/admin/banners

swarm admin banners update

Change a banner's text or level, or switch it on or off.

Parameter Kind What it does
BANNER_ID argument The banner's id
--message option -
--level option info, warning or success
--active, --inactive flag -

Calls: PATCH /api/v1/admin/banners/{banner_id}

swarm admin funnel

From landing-page visit to a node that served: the numbers per step.

Parameter Kind What it does
--days option (default: 30)

Calls: GET /api/v1/admin/funnel

swarm admin host

Run swarm-leader admin on the leader host: create-user, set-password, send-test-mail (--help lists them).

swarm admin inquiries

Contact-form messages (no subcommand), delete.

Subcommands: delete.

Calls: GET /api/v1/admin/inquiries

swarm admin inquiries delete

Delete an inquiry.

Parameter Kind What it does
INQUIRY_ID argument The inquiry's id
--yes, -y flag Do it without asking (needed without a terminal, e.g. in a script).

Calls: DELETE /api/v1/admin/inquiries/{inquiry_id}, GET /api/v1/admin/inquiries

swarm admin mail

Mail status and queue (no subcommand), test.

Subcommands: test.

Parameter Kind What it does
--status option pending, sent or failed
--limit option (default: 50)

Calls: GET /api/v1/admin/mail

swarm admin mail test

Send a test mail to your own address.

Calls: POST /api/v1/admin/mail/test

swarm admin mesh

The private network between fellows (Headscale): its state per fellow, or switch it.

Parameter Kind What it does
SWITCH argument, optional on or off to switch the mesh; empty shows it
--yes, -y flag Do it without asking (needed without a terminal, e.g. in a script).

Calls: GET /api/v1/admin/mesh, PATCH /api/v1/admin/mesh

swarm admin pools

Every pool of the deployment (no subcommand), show, create, update, delete.

Subcommands: create, delete, list, show, update.

Calls: GET /api/v1/admin/pools

swarm admin pools create

Create a pool without an owner's quota (a deployment pool).

Parameter Kind What it does
NAME argument Display name
--slug option -
--description option -
--visibility option public or private (default: public)
--max-nodes option Node cap (default: none)

Calls: POST /api/v1/admin/pools

swarm admin pools delete

Delete any pool.

Parameter Kind What it does
POOL argument owner/slug, id or page URL
--force flag Also with nodes attached
--yes, -y flag Do it without asking (needed without a terminal, e.g. in a script).

Calls: DELETE /api/v1/admin/pools/{pool_id}, GET /api/v1/admin/pools/{pool_id}, GET /api/v1/resolve, GET /api/v1/auth/me

swarm admin pools list

Every pool of the deployment.

Calls: GET /api/v1/admin/pools

swarm admin pools show

One pool, as the admin sees it.

Parameter Kind What it does
POOL argument owner/slug, id or page URL

Calls: GET /api/v1/admin/pools/{pool_id}, GET /api/v1/resolve, GET /api/v1/auth/me

swarm admin pools update

Change any pool's settings or owner.

Parameter Kind What it does
POOL argument owner/slug, id or page URL
--name option -
--description option -
--visibility option -
--max-nodes option -
--no-max-nodes flag -
--open-join, --approve-joins flag -
--slug option -
--owner option Move it to this handle
--min-context option -
--no-min-context flag -

Calls: PATCH /api/v1/admin/pools/{pool_id}, GET /api/v1/resolve, GET /api/v1/auth/me

swarm admin quotas

Each role's limits (no subcommand), and changing one.

Subcommands: set.

Calls: GET /api/v1/admin/role-limits

swarm admin quotas set

Change a role's quota; only the options given change, none means unlimited.

Parameter Kind What it does
ROLE argument user or admin
--max-pools option A number, or none
--max-nodes-per-pool option A number, or none
--max-buckets option A number, or none
--max-storage-bytes option A number, or none

Calls: PATCH /api/v1/admin/role-limits/{role}

swarm admin users

Accounts (no subcommand lists them) and what an admin does with one.

Subcommands: approve, create, delete, list, pending, resend-verification, reset-password, show, signup-intents, status, update.

Parameter Kind What it does
--search, -q option Part of an email or name
--status option active, disabled, pending_approval or unverified
--role option user or admin
--page option (default: 1)
--page-size option (default: 50)

Calls: GET /api/v1/admin/users

swarm admin users approve

Approve an account that waits for an admin.

Parameter Kind What it does
USER argument The account's email or user id

Calls: POST /api/v1/admin/users/{user_id}/approve, GET /api/v1/admin/users

swarm admin users create

Create an account; the person gets an email to set their password.

Parameter Kind What it does
EMAIL argument The new account's email
--name option Display name
--role option user or admin (default: user)

Calls: POST /api/v1/admin/users

swarm admin users delete

Delete an account with its own pools, tokens and chats (nodes are detached).

Parameter Kind What it does
USER argument The account's email or user id
--yes, -y flag Do it without asking (needed without a terminal, e.g. in a script).

Calls: DELETE /api/v1/admin/users/{user_id}, GET /api/v1/admin/users

swarm admin users list

Accounts, newest first, with their pools and nodes.

Parameter Kind What it does
--search, -q option Part of an email or name
--status option active, disabled, pending_approval or unverified
--role option user or admin
--page option (default: 1)
--page-size option (default: 50)

Calls: GET /api/v1/admin/users

swarm admin users pending

How many accounts wait for approval or email verification.

Calls: GET /api/v1/admin/users/pending-count

swarm admin users resend-verification

Mail the account its email-verification link again.

Parameter Kind What it does
USER argument The account's email or user id

Calls: POST /api/v1/admin/users/{user_id}/resend-verification, GET /api/v1/admin/users

swarm admin users reset-password

Mail the account a password-reset link.

Parameter Kind What it does
USER argument The account's email or user id

Calls: POST /api/v1/admin/users/{user_id}/reset-password, GET /api/v1/admin/users

swarm admin users show

One account.

Parameter Kind What it does
USER argument The account's email or user id

Calls: GET /api/v1/admin/users

swarm admin users signup-intents

Why people signed up (to host, to use, unknown) and where the waitlist came from.

Calls: GET /api/v1/admin/users/signup-intents

swarm admin users status

Enable or disable an account.

Parameter Kind What it does
USER argument The account's email or user id
STATUS argument active or disabled (disabling also revokes the account's API tokens)
--yes, -y flag Do it without asking (needed without a terminal, e.g. in a script).

Calls: POST /api/v1/admin/users/{user_id}/status, GET /api/v1/admin/users

swarm admin users update

Change an account's name, email or role.

Parameter Kind What it does
USER argument The account's email or user id
--name option -
--email option A new email (verified again)
--role option user or admin

Calls: PATCH /api/v1/admin/users/{user_id}, GET /api/v1/admin/users

swarm admin waitlist

The beta waitlist.

Calls: GET /api/v1/admin/waitlist

swarm api

Call any leader API route with the CLI's credential (like gh api).

Parameter Kind What it does
METHOD argument GET, POST, PUT, PATCH or DELETE
PATH argument /api/v1/... or short, without /api/v1/ (pools)
--field, -f option key=value, sent as a string (repeatable): query parameters for GET and DELETE, the JSON body else
--typed-field, -F option key=value with the value read as JSON (numbers, true/false, null, lists)
--input option A file with the JSON body ('-': stdin)
--stream flag Follow a server-sent event stream; one JSON line per event (Ctrl-C ends it)

Calls: any route you name.

swarm buckets

Training sets: one base model plus datasets, in one pool.

Subcommands: create, delete, limits, list, show, update.

Parameter Kind What it does
--pool, -p option Only buckets of this pool

Calls: GET /api/v1/buckets, GET /api/v1/resolve, GET /api/v1/auth/me

swarm buckets create

Create a bucket in a pool; add data with swarm datasets upload or add-hf.

Parameter Kind What it does
NAME argument The bucket's name
--pool, -p option The pool it trains on (default: the default pool)
--base-model option Hugging Face model id or a trained model id
--description option -
--owner option An organization's handle (default: you)
--slug option The last part of its address (default: from the name)

Calls: POST /api/v1/buckets, GET /api/v1/resolve, GET /api/v1/auth/me

swarm buckets delete

Delete a bucket and its datasets (models trained from it stay).

Parameter Kind What it does
BUCKET argument owner/slug, a slug of yours, an id or the page URL
--yes, -y flag Do it without asking (needed without a terminal, e.g. in a script).

Calls: DELETE /api/v1/buckets/{bucket_id}, GET /api/v1/buckets/{bucket_id}, GET /api/v1/resolve, GET /api/v1/auth/me

swarm buckets limits

How many buckets and how much storage you use, and your limits.

Calls: GET /api/v1/buckets/limits

swarm buckets list

The buckets you can see; --pool narrows them to one pool.

Parameter Kind What it does
--pool, -p option Only buckets of this pool

Calls: GET /api/v1/buckets, GET /api/v1/resolve, GET /api/v1/auth/me

swarm buckets show

One bucket and its datasets.

Parameter Kind What it does
BUCKET argument owner/slug, a slug of yours, an id or the page URL

Calls: GET /api/v1/buckets/{bucket_id}, GET /api/v1/buckets/{bucket_id}/datasets, GET /api/v1/resolve, GET /api/v1/auth/me

swarm buckets update

Change a bucket's name, base model, description, slug or owner.

Parameter Kind What it does
BUCKET argument owner/slug, a slug of yours, an id or the page URL
--name option -
--base-model option -
--description option -
--slug option New slug (the address changes; the old one redirects)
--owner option Move it to this handle

Calls: PATCH /api/v1/buckets/{bucket_id}, GET /api/v1/resolve, GET /api/v1/auth/me

swarm chat

Chat with a loaded model; replies stream as they are written. /save stores it where the Inference page lists its chats.

Parameter Kind What it does
MODEL argument, optional The loaded model (default: the resumed chat's)
--resume option Continue a saved chat (id or prefix)
--system option A system prompt
--max-tokens option (default: 1024)
--temperature option -
--top-p option -
--top-k option -
--min-p option -

Calls: POST /api/v1/chat/completions, POST /api/v1/chats, PATCH /api/v1/chats/{chat_id}, GET /api/v1/chats/{chat_id}, GET /api/v1/chats, GET /api/v1/models

swarm chats

Saved chats: list (no subcommand), show, export, rename, delete.

Subcommands: delete, export, list, rename, show.

Parameter Kind What it does
--limit option (default: 50)

Calls: GET /api/v1/chats

swarm chats delete

Delete a saved chat.

Parameter Kind What it does
CHAT argument The chat's id or a unique prefix
--yes, -y flag Do it without asking (needed without a terminal, e.g. in a script).

Calls: DELETE /api/v1/chats/{chat_id}, GET /api/v1/chats/{chat_id}, GET /api/v1/chats

swarm chats export

Export a saved chat as Markdown or JSON.

Parameter Kind What it does
CHAT argument The chat's id or a unique prefix
--md, --json flag Markdown (default) or the JSON
--output, -o option A file (default: stdout)

Calls: GET /api/v1/chats/{chat_id}, GET /api/v1/chats

swarm chats list

Your saved chats, newest first (the Inference page's list).

Parameter Kind What it does
--limit option (default: 50)

Calls: GET /api/v1/chats

swarm chats rename

Rename a saved chat.

Parameter Kind What it does
CHAT argument The chat's id or a unique prefix
TITLE argument The new title

Calls: PATCH /api/v1/chats/{chat_id}, GET /api/v1/chats

swarm chats show

A saved chat's messages.

Parameter Kind What it does
CHAT argument The chat's id or a unique prefix
--md flag As Markdown

Calls: GET /api/v1/chats/{chat_id}, GET /api/v1/chats

swarm cluster

The machines of your pools: nodes, GPUs, the swarm graph, the leader's gauges.

Subcommands: devices, graph, metrics, nodes.

swarm cluster devices

Show the GPU/device inventory across fellows.

Parameter Kind What it does
--filter option Status filter, e.g. status=ready
--node option Filter devices to a specific node hostname

Calls: GET /api/v1/cluster/devices

swarm cluster graph

The swarm graph as a tree: the leader, each fellow, and how it is linked (tunnel, p2p, relay).

Parameter Kind What it does
--pool, -p option Only this pool's nodes
--follow, -f flag Redraw as it changes

Calls: GET /api/v1/ops/join-graph, GET /api/v1/ops/join-graph/stream, GET /api/v1/resolve, GET /api/v1/auth/me

swarm cluster metrics

The leader's gauges over your pools: fellows registered and ready, failures, the active job, signal connections, per-node health series.

Calls: GET /api/v1/metrics

swarm cluster nodes

Show node status and resource/network metrics.

Parameter Kind What it does
--filter option Status filter, e.g. status=training

Calls: GET /api/v1/cluster/nodes

swarm configs

List available experiment configs you can run by name.

Parameter Kind What it does
--configs-dir option Directory holding experiment configs (default: exp/configs or $SWARM_CONFIGS_DIR).

swarm datasets

A bucket's data: upload files, import URLs, reference Hugging Face datasets.

Subcommands: add-hf, delete, hf-configs, import, list, preload, upload.

swarm datasets add-hf

Reference a Hugging Face dataset (no storage used); preload it to avoid Hub limits.

Parameter Kind What it does
BUCKET argument owner/slug, a slug of yours, an id or the page URL
REPO argument Hugging Face dataset id, e.g. Salesforce/wikitext
--config option The dataset config, e.g. wikitext-2-raw-v1 (see hf-configs)
--name option Display name (default: the repo)

Calls: POST /api/v1/buckets/{bucket_id}/datasets/hf, GET /api/v1/resolve, GET /api/v1/auth/me

swarm datasets delete

Remove a dataset: an uploaded file is deleted, a Hugging Face reference dropped.

Parameter Kind What it does
BUCKET argument owner/slug, a slug of yours, an id or the page URL
DATASET argument The dataset's id or name
--yes, -y flag Do it without asking (needed without a terminal, e.g. in a script).

Calls: DELETE /api/v1/buckets/{bucket_id}/datasets/{dataset_id}, GET /api/v1/buckets/{bucket_id}/datasets, GET /api/v1/resolve, GET /api/v1/auth/me

swarm datasets hf-configs

The configs a referenced Hugging Face dataset offers, from the Hub.

Parameter Kind What it does
BUCKET argument owner/slug, a slug of yours, an id or the page URL
DATASET argument The Hugging Face reference's id or name

Calls: GET /api/v1/buckets/{bucket_id}/datasets/{dataset_id}/hf-configs, GET /api/v1/buckets/{bucket_id}/datasets, GET /api/v1/resolve, GET /api/v1/auth/me

swarm datasets import

Have the leader download a dataset file from a public URL (up to its import limit).

Parameter Kind What it does
BUCKET argument owner/slug, a slug of yours, an id or the page URL
URL argument A public http(s) URL the leader downloads
--format option jsonl or text (default: jsonl)
--name option Its name (default: from the URL)

Calls: POST /api/v1/buckets/{bucket_id}/datasets/import, GET /api/v1/resolve, GET /api/v1/auth/me

swarm datasets list

A bucket's datasets: uploaded files and Hugging Face references.

Parameter Kind What it does
BUCKET argument owner/slug, a slug of yours, an id or the page URL

Calls: GET /api/v1/buckets/{bucket_id}/datasets, GET /api/v1/resolve, GET /api/v1/auth/me

swarm datasets preload

Copy the rows a run needs from a referenced Hugging Face dataset into the bucket, so fellows read them from the leader. Waits until the copy is done.

Parameter Kind What it does
BUCKET argument owner/slug, a slug of yours, an id or the page URL
DATASET argument The Hugging Face reference's id or name
--config option The config to copy (default: the reference's own, or the only one)

Calls: POST /api/v1/buckets/{bucket_id}/datasets/{dataset_id}/snapshot, GET /api/v1/buckets/{bucket_id}/datasets, GET /api/v1/resolve, GET /api/v1/auth/me

swarm datasets upload

Upload a dataset file, streamed from disk with a progress bar. The upload does not resume: a broken one starts again from the beginning.

Parameter Kind What it does
BUCKET argument owner/slug, a slug of yours, an id or the page URL
FILE argument The file: JSONL with a "text" field, or plain text
--format option jsonl or text (default: from the file's extension)
--name option Its name in the bucket (default: the file name)

Calls: POST /api/v1/buckets/{bucket_id}/datasets, GET /api/v1/buckets/limits, GET /api/v1/resolve, GET /api/v1/auth/me

swarm fellows

Registered fellows: list (no subcommand), release, update, speed limits, purges.

Subcommands: join-command, list, logs, pending-purges, release, retry-purge, set-speed, show, update.

Calls: GET /api/v1/workers

swarm fellows join-command

Print the command that installs a fellow on a new machine and joins it to a pool. It holds a one-time credential: do not post it anywhere public.

Parameter Kind What it does
--pool, -p option The pool it joins (default: the default pool, else the deployment's)
--role option active (scheduled now) or standby (warm spare) (default: active)
--ttl option Seconds the one-time invite stays valid (default: 3600)
--verify-first flag Print the read-before-run variant that checks the script's checksum
--enrollment flag An enrollment token for containers and Kubernetes instead: no expiry, many nodes
--max-nodes option With --enrollment: most nodes it admits
--wait flag Then follow the join's setup log until the machine registers or fails

Calls: POST /api/v1/bootstrap/join-sessions, GET /api/v1/health, GET /api/v1/bootstrap/join-sessions/{session_id}, GET /api/v1/bootstrap/join-sessions/{session_id}/logs/stream, GET /api/v1/pools/{pool_id}/nodes, GET /api/v1/resolve, GET /api/v1/auth/me

swarm fellows list

List registered fellows.

Calls: GET /api/v1/workers

swarm fellows logs

A fellow's runtime log, as shipped to the leader (the last 500 lines are kept).

Parameter Kind What it does
FELLOW_ID argument The fellow's id
--tail, -n option The newest N lines (default: 100)
--level option Only info, warn, error or step lines
--follow, -f flag Keep printing new lines (Ctrl-C ends it)

Calls: GET /api/v1/workers/{fellow_id}/logs, GET /api/v1/workers/{fellow_id}/logs/stream

swarm fellows pending-purges

List purge cleanups waiting for delivery.

Calls: GET /api/v1/workers/purge-pending

swarm fellows release

Release fellows from the leader registry.

Parameter Kind What it does
--fellow-id option Fellow ID to release (repeatable)
--all flag Release all registered fellows
--purge-install flag Ask fellows to purge local installation before release
--purge-config flag Also remove local ~/.swarm/config.toml during purge
--purge-firewall flag Also roll back bootstrap-managed ufw rules during purge
--yes, -y flag Do it without asking (needed without a terminal, e.g. in a script).

Calls: POST /api/v1/workers/release, DELETE /api/v1/workers/{fellow_id}

swarm fellows retry-purge

Retry pending purges to reconnected fellows.

Parameter Kind What it does
--fellow-id option Pending purge fellow ID to retry (repeatable)
--all flag Retry all pending purge entries

Calls: POST /api/v1/workers/purge-pending/retry

swarm fellows set-speed

Set a fellow's network speed limits.

Parameter Kind What it does
--fellow-id option Target fellow ID
--tx-mbps option Max TX bandwidth in Mbps
--rx-mbps option Max RX bandwidth in Mbps

Calls: POST /api/v1/workers/{fellow_id}/network-limit

swarm fellows show

One fellow: host, status, version, transport, mesh, hardware and GPUs.

Parameter Kind What it does
FELLOW_ID argument The fellow's id

Calls: GET /api/v1/workers/{fellow_id}

swarm fellows update

Tell fellows to re-bootstrap from the leader, and follow them back.

Parameter Kind What it does
--fellow-id option Fellow ID to update (repeatable; omit for all)
--no-wait flag Do not wait for fellows to come back online; exit after sending signal.
--timeout option Seconds to wait for fellows to come back online after update. (default: 180.0)

Calls: POST /api/v1/workers/update, GET /api/v1/workers

swarm infer

Run a one-shot chat completion against a loaded model.

Parameter Kind What it does
MODEL_ID argument Loaded model id
PROMPT argument User prompt; - reads it from stdin
--max-tokens option (default: 256)
--temperature option 0 is deterministic; unset uses the model's default
--top-p option Nucleus sampling, 0-1
--top-k option Only the k most likely tokens; 0 turns it off
--min-p option Only tokens at least this fraction as likely as the best
--stream, --no-stream flag Print the reply as it is written (default: on a terminal)

Calls: POST /api/v1/chat/completions

swarm info

Show a practical quickstart and workflow summary.

Calls: GET /api/v1/health

swarm invites

Pool and organization invitations addressed to you.

Subcommands: accept, list.

Calls: GET /api/v1/pools/invites/mine, GET /api/v1/orgs/invites/mine

swarm invites accept

Accept an invitation.

Parameter Kind What it does
INVITE_ID argument The invite's id (from swarm invites)

Calls: GET /api/v1/pools/invites/mine, GET /api/v1/orgs/invites/mine, POST /api/v1/pools/invites/{invite_id}/accept, POST /api/v1/orgs/invites/{invite_id}/accept

swarm invites list

List the invitations addressed to you.

Calls: GET /api/v1/pools/invites/mine, GET /api/v1/orgs/invites/mine

swarm jobs

Training jobs: list (no subcommand), show, stop, resume.

Subcommands: cancel, clear, diagnose, incidents, list, metrics, placements, resume, show, snapshots, stop.

Parameter Kind What it does
--status option Filter by status

Calls: GET /api/v1/jobs

swarm jobs cancel

Cancel a job without a checkpoint (swarm jobs stop checkpoints first). A pipeline job keeps its committed snapshots: swarm jobs resume continues from the newest.

Parameter Kind What it does
JOB_ID argument Job id or a unique prefix of it
--yes, -y flag Do it without asking (needed without a terminal, e.g. in a script).

Calls: DELETE /api/v1/jobs/{job_id}, GET /api/v1/jobs/{job_id}, GET /api/v1/jobs

swarm jobs clear

Delete every job record on the leader, every pool and status (admin). It stops nothing: stop running jobs first. Exported models stay.

Parameter Kind What it does
--yes, -y flag Do it without asking (needed without a terminal, e.g. in a script).

Calls: DELETE /api/v1/jobs, GET /api/v1/jobs

swarm jobs diagnose

Why a job failed or stalls, in one screen: status and error, incidents, placements, and the last log lines of every fellow that ran it.

Parameter Kind What it does
JOB_ID argument Job id or a unique prefix of it
--lines, -n option Log lines per fellow (default: 20)

Calls: GET /api/v1/jobs/{job_id}, GET /api/v1/jobs/{job_id}/incidents, GET /api/v1/jobs/{job_id}/placements, GET /api/v1/workers/{fellow_id}/logs, GET /api/v1/jobs

swarm jobs incidents

The job's recoveries: each lost node, what the leader did and how it ended.

Parameter Kind What it does
JOB_ID argument Job id or a unique prefix of it

Calls: GET /api/v1/jobs/{job_id}/incidents, GET /api/v1/jobs

swarm jobs list

List jobs.

Parameter Kind What it does
--status option Filter by status

Calls: GET /api/v1/jobs

swarm jobs metrics

A job's loss history, one point per step (the Training page's chart).

Parameter Kind What it does
JOB_ID argument Job id or a unique prefix of it
--csv flag step,loss,timestamp lines, for a spreadsheet or a plot
--since-step option Only steps after this one
--last option Table: the newest N points (default: 20)

Calls: GET /api/v1/jobs/{job_id}/metrics/history, GET /api/v1/jobs

swarm jobs placements

Which node holds which stage of the job now, before, and the latest changes.

Parameter Kind What it does
JOB_ID argument Job id or a unique prefix of it
--events option (default: 20)

Calls: GET /api/v1/jobs/{job_id}/placements, GET /api/v1/jobs

swarm jobs resume

Start a stopped pipeline run again from its last committed snapshot.

Parameter Kind What it does
JOB_ID argument Job id or a unique prefix of it (see swarm jobs)

Calls: GET /api/v1/jobs, POST /api/v1/jobs/{job_id}/resume

swarm jobs show

Show a job's placement: stages, fellows, GPUs, layers, boundary, wire.

Parameter Kind What it does
JOB_ID argument Job id or a unique prefix of it (see swarm jobs)

Calls: GET /api/v1/jobs, GET /api/v1/jobs/{job_id}

swarm jobs snapshots

A job's committed snapshots (saved training state per stage); with --stage, download one stage's file (resumable: run it again after a break).

Parameter Kind What it does
JOB_ID argument Job id or a unique prefix of it
--step option Download: the snapshot step (default: the newest)
--stage option Download this stage's file
--output, -o option Where to write it (default: <job>-step<N>-stage<M>.safetensors)

Calls: GET /api/v1/jobs/{job_id}/snapshots, GET /api/v1/jobs/{job_id}/snapshots/{step}/stages/{stage_index}, GET /api/v1/jobs

swarm jobs stop

Checkpoint and cancel a running job.

Parameter Kind What it does
JOB_ID argument Job id or a unique prefix of it
--timeout option Timeout for cancel confirmation (default: 30)
--yes, -y flag Do it without asking (needed without a terminal, e.g. in a script).

Calls: DELETE /api/v1/jobs/{job_id}, POST /api/v1/jobs/{job_id}/checkpoint, GET /api/v1/jobs, GET /api/v1/jobs/{job_id}

swarm join-sessions

Join sessions ("Add fellow" invitations): list (no subcommand), show, logs, revoke.

Subcommands: list, logs, revoke, show.

Parameter Kind What it does
--status option pending, active, completed, failed, revoked or expired
--pool, -p option Only sessions into this pool

Calls: GET /api/v1/bootstrap/join-sessions, GET /api/v1/resolve, GET /api/v1/auth/me

swarm join-sessions list

Join sessions ("Add fellow" invitations) of your pools, newest first.

Parameter Kind What it does
--status option pending, active, completed, failed, revoked or expired
--pool, -p option Only sessions into this pool

Calls: GET /api/v1/bootstrap/join-sessions, GET /api/v1/resolve, GET /api/v1/auth/me

swarm join-sessions logs

The setup output a joining machine sent while it installed the fellow.

Parameter Kind What it does
SESSION_ID argument The session's id
--follow, -f flag Follow it until the join ends

Calls: GET /api/v1/bootstrap/join-sessions/{session_id}, GET /api/v1/bootstrap/join-sessions/{session_id}/logs, GET /api/v1/bootstrap/join-sessions/{session_id}/logs/stream

swarm join-sessions revoke

Revoke a join session so its command no longer admits a machine.

Parameter Kind What it does
SESSION_ID argument The session's id
--yes, -y flag Do it without asking (needed without a terminal, e.g. in a script).

Calls: DELETE /api/v1/bootstrap/join-sessions/{session_id}, GET /api/v1/bootstrap/join-sessions/{session_id}

swarm join-sessions show

One join session: status, the joining host and fellow, pool, role, expiry.

Parameter Kind What it does
SESSION_ID argument The session's id

Calls: GET /api/v1/bootstrap/join-sessions/{session_id}

swarm llm-doc

Print or write LLM-friendly CLI usage documentation.

Parameter Kind What it does
--output, -o option Write the generated markdown to this file instead of stdout.

swarm login

Sign in to the leader through the browser (no API token needed).

Parameter Kind What it does
--device flag Sign in with a code typed into any browser (for a machine without one, such as a server over SSH).
--scopes option What the CLI may do: read, operate, admin (admins only). You can narrow it on the consent page. (default: read,operate)
--no-browser flag Print the sign-in address instead of opening a browser.

swarm logout

End the CLI's sign-in to the leader.

swarm mcp

Use SilentSwarm from an AI agent: MCP client setup, stdio bridge, tool list.

Subcommands: config, serve, tools.

swarm mcp config

Print ready-to-paste MCP setup for Claude Code, Claude Desktop, Cursor, VS Code or any client (never prints a token).

Parameter Kind What it does
--client option One of: claude-code, claude-desktop, cursor, vscode, json. Default: all of them.
--toolsets option Comma-separated toolsets to list: cluster, training, buckets, serving, pools, orgs, account, admin, meta, or all. Default: cluster,training,buckets,serving,meta.
--auth option token: the snippets send an API token from $SWARM_API_TOKEN (default). oauth: no key - the client opens the leader's sign-in page in your browser (Claude Code, Cursor, VS Code, claude.ai connectors and other OAuth-capable clients; Claude Desktop's bridge after swarm login). (default: token)

swarm mcp serve

Run a stdio MCP server that forwards to the leader's /mcp (for clients like Claude Desktop that start a command).

Parameter Kind What it does
--toolsets option Comma-separated toolsets to list: cluster, training, buckets, serving, pools, orgs, account, admin, meta, or all. Default: cluster,training,buckets,serving,meta.
--token option API token (default: --token before mcp, $SWARM_API_TOKEN, or api_token in ~/.swarm/config.toml).
--debug flag Log the MCP traffic to stderr.

swarm mcp tools

List the MCP tools your API token can use.

Parameter Kind What it does
--toolsets option Comma-separated toolsets to list: cluster, training, buckets, serving, pools, orgs, account, admin, meta, or all. Default: cluster,training,buckets,serving,meta.
--token option API token (default as for serve).

swarm me

Your account: who you are (no subcommand), handle, namespaces, contribution.

Subcommands: contribution, namespaces, set-handle.

Calls: GET /api/v1/auth/me

swarm me contribution

What your machines gave the swarm.

Calls: GET /api/v1/me/contribution

swarm me namespaces

Where you can create pools and buckets.

Calls: GET /api/v1/me/namespaces

swarm me set-handle

Change your handle; your addresses follow.

Parameter Kind What it does
HANDLE argument The new handle: lowercase letters, digits, single hyphens

Calls: PATCH /api/v1/me/handle

swarm models

Servable models: list (no subcommand), load, unload.

Subcommands: delete, download, list, load, perf, push-export, settings, show, unload.

Calls: GET /api/v1/models

swarm models delete

Delete a model from the catalogue and the leader's disk (admin; not while loaded).

Parameter Kind What it does
MODEL argument Model id or a unique prefix of it
--yes, -y flag Do it without asking (needed without a terminal, e.g. in a script).

Calls: DELETE /api/v1/models/{model_id}, GET /api/v1/models/{model_id}, GET /api/v1/models

swarm models download

Download a model's weights as a tar.gz (built by the leader as it sends; a broken download starts again).

Parameter Kind What it does
MODEL argument Model id or a unique prefix of it
--output, -o option A directory (the file is <model>.tar.gz) or a file name (default: .)

Calls: GET /api/v1/models/{model_id}/archive, GET /api/v1/models

swarm models list

List servable (trained) models.

Calls: GET /api/v1/models

swarm models load

Load a model for inference (or --plan where it would go).

Parameter Kind What it does
MODEL_ID argument Servable model id or a unique prefix of it (from swarm models)
--fellow-id option Pin to a specific fellow
--device option CUDA device, e.g. cuda:0
--num-stages option Pipeline stages to serve over (default: the model's own). 1 serves a model trained over several stages on one fellow, across its GPUs (--fellow-id picks it).
--context option Tokens one conversation must hold (context window CW6): raises the model's window for this load, never lowers it. Refused, naming the short card, when the pool cannot hold it.
--kv-cache option How the stages store the KV cache: auto, native, float16 or int8 (about a quarter of float32, opt-in).
--plan flag Show where the load would go and what each card holds; loads nothing.
--maximize option With --plan: 'context' (the largest window the cards hold) or 'speed' (the fastest placement that holds the window).
--plan-id option Load exactly the plan shown by --plan (its plan_id), or fail with what changed.
--use-all flag Every node serves: every ready fellow a stage, every card a layer, split by measured speed (every-node serving).
--cuda-graphs, --no-cuda-graphs flag Replay decode steps from recorded CUDA graphs (checked at load); default: the leader's SWARM_SERVE_CUDA_GRAPHS.
--exclude-card option Leave a card out, as FELLOW_ID:GPU_INDEX (repeatable), e.g. 54737:0. Give the same ones to --plan and to the load that pins its --plan-id.
--wait flag Wait until the model reports ready
--timeout option Seconds to wait when --wait (default: 300.0)

Calls: GET /api/v1/models, POST /api/v1/models/{model_id}/plan, POST /api/v1/models/{model_id}/load, GET /api/v1/models/{model_id}/status

swarm models perf

How fast a served model answers: tokens/s, time to first token, per-stage timing.

Parameter Kind What it does
MODEL argument Model id or a unique prefix of it
--range option 15m, 1h, 6h, 24h or 7d (default: 15m)

Calls: GET /api/v1/models/{model_id}/performance, GET /api/v1/models

swarm models push-export

Ask fellows to upload a model's exported shards again (for an incomplete model).

Parameter Kind What it does
MODEL argument Model id or a unique prefix of it
--fellow option Only this fellow (default: every ready fellow of the model's pool)

Calls: POST /api/v1/models/{model_id}/push-export, GET /api/v1/models

swarm models settings

Change how a model is served: its context window and KV cache (managers).

Parameter Kind What it does
MODEL argument Model id or a unique prefix of it
--context option The context window it is served with, in tokens
--no-context flag Back to the pool's minimum / the model's own
--kv-cache option auto, native, float16 or int8
--tested-tokens option Record a context length you tested it at (0 clears)
--tested-note option A note for that test

Calls: PATCH /api/v1/models/{model_id}/settings, GET /api/v1/models

swarm models show

One model: base, stages, layers, size, the context it serves and where it came from.

Parameter Kind What it does
MODEL argument Model id or a unique prefix of it

Calls: GET /api/v1/models/{model_id}, GET /api/v1/models

swarm models unload

Unload a served model and free its VRAM.

Parameter Kind What it does
MODEL_ID argument Servable model id (or a unique prefix) to unload
--fellow-id option Unload from a specific fellow

Calls: GET /api/v1/models, POST /api/v1/models/{model_id}/unload

swarm open

Open the web UI page for a pool, bucket, org, job or model.

Parameter Kind What it does
REF argument, optional A pool, bucket or org (owner/slug, slug, id or URL), a job id or a model id (prefixes work); default: the default pool, else the dashboard
--kind option pool, bucket, org, job or model, when the name alone is ambiguous
--print flag Print the address, open nothing

Calls: GET /api/v1/resolve, GET /api/v1/auth/me, GET /api/v1/jobs, GET /api/v1/jobs/{job_id}, GET /api/v1/models, GET /api/v1/models/{model_id}

swarm orgs

Organizations: list (no subcommand), show, create, update, delete, members, invites.

Subcommands: create, delete, invites, list, members, show, update.

Calls: GET /api/v1/orgs

swarm orgs create

Create an organization; you become its owner.

Parameter Kind What it does
NAME argument The organization's name
--handle option Its address (default: from the name)
--description option -

Calls: POST /api/v1/orgs

swarm orgs delete

Delete an organization (owners; refused while it still owns pools or buckets).

Parameter Kind What it does
ORG argument The organization's handle, id or page URL
--yes, -y flag Do it without asking (needed without a terminal, e.g. in a script).

Calls: DELETE /api/v1/orgs/{org}, GET /api/v1/orgs/{org}

swarm orgs invites

An organization's open invitations (no subcommand), create, revoke.

Subcommands: create, revoke.

Parameter Kind What it does
ORG argument The organization's handle, id or page URL

Calls: GET /api/v1/orgs/{org}/invites

swarm orgs invites create

Invite someone by email; they accept with swarm invites accept.

Parameter Kind What it does
EMAIL argument Who to invite
--role option owner, admin or member (default: member)

Calls: POST /api/v1/orgs/{org}/invites

swarm orgs invites revoke

Revoke an open invitation.

Parameter Kind What it does
INVITE argument The invite's id or the invited email
--yes, -y flag Do it without asking (needed without a terminal, e.g. in a script).

Calls: DELETE /api/v1/orgs/{org}/invites/{invite_id}, GET /api/v1/orgs/{org}/invites

swarm orgs list

The organizations you belong to (an admin: all of them).

Calls: GET /api/v1/orgs

swarm orgs members

An organization's members (no subcommand), role, remove.

Subcommands: remove, role.

Parameter Kind What it does
ORG argument The organization's handle, id or page URL

Calls: GET /api/v1/orgs/{org}/members

swarm orgs members remove

Remove a member, or leave the organization yourself.

Parameter Kind What it does
USER argument The member's email, handle or user id (your own: leave)
--yes, -y flag Do it without asking (needed without a terminal, e.g. in a script).

Calls: DELETE /api/v1/orgs/{org}/members/{user_id}, GET /api/v1/orgs/{org}/members

swarm orgs members role

Change a member's role.

Parameter Kind What it does
USER argument The member's email, handle or user id
ROLE argument owner, admin or member

Calls: PATCH /api/v1/orgs/{org}/members/{user_id}, GET /api/v1/orgs/{org}/members

swarm orgs show

One organization and its members.

Parameter Kind What it does
ORG argument The organization's handle, id or page URL

Calls: GET /api/v1/orgs/{org}, GET /api/v1/orgs/{org}/members

swarm orgs update

Change an organization's name, description or handle.

Parameter Kind What it does
ORG argument The organization's handle, id or page URL
--name option -
--description option -
--handle option New handle (owners; old addresses redirect)

Calls: PATCH /api/v1/orgs/{org}

swarm overview

The dashboard: nodes, GPUs, jobs, served models, events.

Parameter Kind What it does
--events option How many recent pool events to show (default: 5)

Calls: GET /api/v1/cluster/overview, GET /api/v1/pools/activity, GET /api/v1/jobs, GET /api/v1/serving, GET /api/v1/pools/limits, GET /api/v1/banners, GET /api/v1/health

swarm pools

Your pools, and the default pool commands act on.

Subcommands: activity, clear, covers, create, current, delete, events, gatekeeper, heat, incidents, invites, join, limits, list, members, metrics, nodes, placements, requests, show, speed, update, use.

Calls: GET /api/v1/pools

swarm pools activity

Recent events across all your pools, newest first (the dashboard's feed).

Parameter Kind What it does
--limit option (default: 20)

Calls: GET /api/v1/pools/activity

swarm pools clear

Forget the default pool in ~/.swarm/config.toml.

swarm pools covers

Which standby covers which stage of the served models and the running job.

Parameter Kind What it does
--pool, -p option The pool (default: --pool before the command, SWARM_POOL or swarm pools use)

Calls: GET /api/v1/pools/{pool_id}/covers, GET /api/v1/resolve, GET /api/v1/auth/me

swarm pools create

Create a pool; add machines with swarm fellows join-command, people with swarm pools invites create.

Parameter Kind What it does
NAME argument The pool's display name
--slug option The last part of its address (default: from the name)
--description option -
--visibility option public (anyone may ask to join) or private
--max-nodes option Node cap
--owner option An organization's handle (default: you)
--check flag Only show the address it would get and whether it is free

Calls: POST /api/v1/pools, GET /api/v1/namespaces/check

swarm pools current

Show the default pool and where it is set.

Calls: GET /api/v1/resolve, GET /api/v1/auth/me

swarm pools delete

Delete a pool with its memberships and node bindings (the machines stay).

Parameter Kind What it does
POOL argument The pool to delete (no default, on purpose)
--force flag Also when nodes are attached (they are detached)
--yes, -y flag Do it without asking (needed without a terminal, e.g. in a script).

Calls: DELETE /api/v1/pools/{pool_id}, GET /api/v1/pools/{pool_id}, GET /api/v1/resolve, GET /api/v1/auth/me

swarm pools events

The pool's timeline: joins, drops, grade and role changes, runs.

Parameter Kind What it does
--limit option (default: 50)
--pool, -p option The pool (default: --pool before the command, SWARM_POOL or swarm pools use)

Calls: GET /api/v1/pools/{pool_id}/events, GET /api/v1/resolve, GET /api/v1/auth/me

swarm pools gatekeeper

Admissions (self-tests), checkouts and availability windows, quarantine history.

Parameter Kind What it does
--pool, -p option The pool (default: --pool before the command, SWARM_POOL or swarm pools use)

Calls: GET /api/v1/pools/{pool_id}/gatekeeper, GET /api/v1/resolve, GET /api/v1/auth/me

swarm pools heat

GPU power now, energy delivered as heat, and each node's heat demand.

Parameter Kind What it does
--pool, -p option The pool (default: --pool before the command, SWARM_POOL or swarm pools use)

Calls: GET /api/v1/pools/{pool_id}/heat, GET /api/v1/resolve, GET /api/v1/auth/me

swarm pools incidents

Recovery incidents: a training job lost a node and the leader moved it on.

Parameter Kind What it does
--limit option (default: 50)
--pool, -p option The pool (default: --pool before the command, SWARM_POOL or swarm pools use)

Calls: GET /api/v1/pools/{pool_id}/incidents, GET /api/v1/resolve, GET /api/v1/auth/me

swarm pools invites

A pool's open invitations (no subcommand), create, revoke.

Subcommands: create, revoke.

Parameter Kind What it does
--pool, -p option The pool (default: --pool before the command, SWARM_POOL or swarm pools use)

Calls: GET /api/v1/pools/{pool_id}/invites, GET /api/v1/resolve, GET /api/v1/auth/me

swarm pools invites create

Invite someone to the pool by email; they accept with swarm invites accept.

Parameter Kind What it does
EMAIL argument Who to invite
--role option member or admin (default: member)
--pool, -p option The pool (default: --pool before the command, SWARM_POOL or swarm pools use)

Calls: POST /api/v1/pools/{pool_id}/invites, GET /api/v1/resolve, GET /api/v1/auth/me

swarm pools invites revoke

Revoke an open invitation.

Parameter Kind What it does
INVITE argument The invite's id or the invited email
--pool, -p option The pool (default: --pool before the command, SWARM_POOL or swarm pools use)
--yes, -y flag Do it without asking (needed without a terminal, e.g. in a script).

Calls: DELETE /api/v1/pools/{pool_id}/invites/{invite_id}, GET /api/v1/pools/{pool_id}/invites, GET /api/v1/resolve, GET /api/v1/auth/me

swarm pools join

Join a public pool, or ask to (its managers approve).

Parameter Kind What it does
POOL argument A public pool: owner/slug, id or page URL

Calls: POST /api/v1/pools/{pool_id}/join, GET /api/v1/resolve, GET /api/v1/auth/me

swarm pools limits

Your pool quota: how many pools, nodes per pool, which visibilities.

Calls: GET /api/v1/pools/limits

swarm pools list

List the pools you can see.

Calls: GET /api/v1/pools

swarm pools members

A pool's members (no subcommand), and removing one.

Subcommands: remove.

Parameter Kind What it does
--pool, -p option The pool (default: --pool before the command, SWARM_POOL or swarm pools use)

Calls: GET /api/v1/pools/{pool_id}/members, GET /api/v1/resolve, GET /api/v1/auth/me

swarm pools members remove

Remove a member from the pool.

Parameter Kind What it does
USER argument The member's email, name or user id
--pool, -p option The pool (default: --pool before the command, SWARM_POOL or swarm pools use)
--yes, -y flag Do it without asking (needed without a terminal, e.g. in a script).

Calls: DELETE /api/v1/pools/{pool_id}/members/{user_id}, GET /api/v1/pools/{pool_id}/members, GET /api/v1/resolve, GET /api/v1/auth/me

swarm pools metrics

A pool's health: the live snapshot (KPIs, serving, one row per node), a series' history, or the snapshot followed live.

Parameter Kind What it does
--history option A series' history instead of the snapshot, e.g. gpu_util_pct, power_w
--fellow option With --history: one node's series
--window option With --history: how far back (15m, 6h, 7d) (default: 1h)
--follow, -f flag Follow the live snapshot (Ctrl-C ends it)
--pool, -p option The pool (default: --pool before the command, SWARM_POOL or swarm pools use)

Calls: GET /api/v1/pools/{pool_id}/metrics, GET /api/v1/pools/{pool_id}/metrics/history, GET /api/v1/pools/{pool_id}/metrics/stream, GET /api/v1/resolve, GET /api/v1/auth/me

swarm pools nodes

A pool's nodes (no subcommand) and what to do with one: role, checkout, availability, benchmark, self-test, heat demand.

Subcommands: availability, benchmark, checkin, checkout, heat-demand, role, selftest.

Parameter Kind What it does
--pool, -p option The pool (default: --pool before the command, SWARM_POOL or swarm pools use)

Calls: GET /api/v1/pools/{pool_id}/nodes, GET /api/v1/resolve, GET /api/v1/auth/me

swarm pools nodes availability

Show or set when a node is not available; it checks itself out ahead of each window. Without --window or --clear it shows the current windows.

Parameter Kind What it does
FELLOW argument The node: its fellow id or hostname
--window option A weekly time the node is NOT available, HH:MM-HH:MM (repeatable; over midnight is fine)
--days option Days for the windows: mon-fri, sat,sun or 0-4 (default: every day)
--tz option Time zone, e.g. Europe/Berlin
--clear flag Remove every window
--pool, -p option The pool (default: --pool before the command, SWARM_POOL or swarm pools use)

Calls: PUT /api/v1/pools/{pool_id}/nodes/{fellow_id}/availability, GET /api/v1/pools/{pool_id}/gatekeeper, GET /api/v1/pools/{pool_id}/nodes, GET /api/v1/resolve, GET /api/v1/auth/me

swarm pools nodes benchmark

Measure a node's speed now: TFLOPS and memory bandwidth per GPU, its network to the leader. Changes nothing about the node; a busy node answers busy.

Parameter Kind What it does
FELLOW argument The node: its fellow id or hostname
--wait flag Wait for the result (up to --timeout)
--timeout option (default: 180.0)
--pool, -p option The pool (default: --pool before the command, SWARM_POOL or swarm pools use)

Calls: POST /api/v1/pools/{pool_id}/nodes/{fellow_id}/benchmark, GET /api/v1/pools/{pool_id}/speed, GET /api/v1/pools/{pool_id}/nodes, GET /api/v1/resolve, GET /api/v1/auth/me

swarm pools nodes checkin

Give a checked-out node back to its pool.

Parameter Kind What it does
FELLOW argument The node: its fellow id or hostname
--pool, -p option The pool (default: --pool before the command, SWARM_POOL or swarm pools use)

Calls: DELETE /api/v1/pools/{pool_id}/nodes/{fellow_id}/checkout, GET /api/v1/pools/{pool_id}/nodes, GET /api/v1/resolve, GET /api/v1/auth/me

swarm pools nodes checkout

Check a node out for its host: no new work, its training stage moves off at the next snapshot boundary before the deadline.

Parameter Kind What it does
FELLOW argument The node: its fellow id or hostname
--in option When the host needs the machine back (15m, 2h, 1d) (default: 15m)
--pool, -p option The pool (default: --pool before the command, SWARM_POOL or swarm pools use)

Calls: POST /api/v1/pools/{pool_id}/nodes/{fellow_id}/checkout, GET /api/v1/pools/{pool_id}/nodes, GET /api/v1/resolve, GET /api/v1/auth/me

swarm pools nodes heat-demand

Set (or --clear) the heat a node's building asks for; training prefers the nodes asking for the most.

Parameter Kind What it does
FELLOW argument The node: its fellow id or hostname
PERCENT argument, optional How much heat the building wants, 0-100
--ttl option Until it expires (15m, 2h, 1d); send it again to keep it (default: 1h)
--source option Who is asking, e.g. heat pump
--clear flag Withdraw the demand
--pool, -p option The pool (default: --pool before the command, SWARM_POOL or swarm pools use)

Calls: PUT /api/v1/pools/{pool_id}/nodes/{fellow_id}/heat-demand, DELETE /api/v1/pools/{pool_id}/nodes/{fellow_id}/heat-demand, GET /api/v1/pools/{pool_id}/nodes, GET /api/v1/resolve, GET /api/v1/auth/me

swarm pools nodes role

Move a node between active, standby, draining and quarantined.

Parameter Kind What it does
FELLOW argument The node: its fellow id or hostname
ROLE argument active (scheduled), standby (warm spare), draining (moves off at the next snapshot) or quarantined (out of service)
--pool, -p option The pool (default: --pool before the command, SWARM_POOL or swarm pools use)

Calls: POST /api/v1/pools/{pool_id}/nodes/{fellow_id}/role, GET /api/v1/pools/{pool_id}/nodes, GET /api/v1/resolve, GET /api/v1/auth/me

swarm pools nodes selftest

Run a node's admission self-test again; it gets no work until it passes.

Parameter Kind What it does
FELLOW argument The node: its fellow id or hostname
--wait flag Wait for the verdict (up to --timeout)
--timeout option (default: 300.0)
--pool, -p option The pool (default: --pool before the command, SWARM_POOL or swarm pools use)

Calls: POST /api/v1/pools/{pool_id}/nodes/{fellow_id}/selftest, GET /api/v1/pools/{pool_id}/gatekeeper, GET /api/v1/pools/{pool_id}/nodes, GET /api/v1/resolve, GET /api/v1/auth/me

swarm pools placements

Which node holds which shard of which job or model, and the latest changes.

Parameter Kind What it does
--events option (default: 20)
--pool, -p option The pool (default: --pool before the command, SWARM_POOL or swarm pools use)

Calls: GET /api/v1/pools/{pool_id}/placements, GET /api/v1/resolve, GET /api/v1/auth/me

swarm pools requests

People asking to join (no subcommand), approve, deny.

Subcommands: approve, deny.

Parameter Kind What it does
--pool, -p option The pool (default: --pool before the command, SWARM_POOL or swarm pools use)

Calls: GET /api/v1/pools/{pool_id}/join-requests, GET /api/v1/resolve, GET /api/v1/auth/me

swarm pools requests approve

Let someone who asked into the pool.

Parameter Kind What it does
USER argument Their email, name or user id
--pool, -p option The pool (default: --pool before the command, SWARM_POOL or swarm pools use)

Calls: POST /api/v1/pools/{pool_id}/join-requests/{user_id}/approve, GET /api/v1/pools/{pool_id}/join-requests, GET /api/v1/resolve, GET /api/v1/auth/me

swarm pools requests deny

Turn down a request to join the pool.

Parameter Kind What it does
USER argument Their email, name or user id
--pool, -p option The pool (default: --pool before the command, SWARM_POOL or swarm pools use)
--yes, -y flag Do it without asking (needed without a terminal, e.g. in a script).

Calls: DELETE /api/v1/pools/{pool_id}/join-requests/{user_id}, GET /api/v1/pools/{pool_id}/join-requests, GET /api/v1/resolve, GET /api/v1/auth/me

swarm pools show

One pool: its settings, members and nodes.

Parameter Kind What it does
POOL argument, optional owner/slug, a slug of yours, an id or the page URL (default: the default pool)

Calls: GET /api/v1/pools/{pool_id}, GET /api/v1/pools/{pool_id}/members, GET /api/v1/pools/{pool_id}/nodes, GET /api/v1/resolve, GET /api/v1/auth/me

swarm pools speed

The pool's GPUs ranked by measured speed, and each node's network.

Parameter Kind What it does
--pool, -p option The pool (default: --pool before the command, SWARM_POOL or swarm pools use)

Calls: GET /api/v1/pools/{pool_id}/speed, GET /api/v1/resolve, GET /api/v1/auth/me

swarm pools update

Change a pool's settings; only the options given change (pool managers).

Parameter Kind What it does
POOL argument, optional owner/slug, a slug of yours, an id or the page URL (default: the default pool)
--name option -
--description option -
--visibility option public or private
--max-nodes option New node cap
--no-max-nodes flag Remove the node cap (back to the plan's limit)
--open-join, --approve-joins flag Public pools: join without approval, or ask first
--slug option New slug (old address redirects)
--owner option Move it to this handle
--min-context option Context window every served model must hold
--no-min-context flag Remove the context minimum

Calls: PATCH /api/v1/pools/{pool_id}, GET /api/v1/resolve, GET /api/v1/auth/me

swarm pools use

Make a pool the default (saved in ~/.swarm/config.toml).

Parameter Kind What it does
POOL argument owner/slug, a slug of yours, an id or a pool's page URL

Calls: GET /api/v1/resolve, GET /api/v1/auth/me

swarm profiles

The [profiles.] tables of ~/.swarm/config.toml: each a leader, its token (shown only as set or not) and its default pool. --profile NAME picks one.

swarm restart-cluster

Restart local leader and fellow processes, then wait for ready state.

Parameter Kind What it does
--fellows option Number of fellow processes to start (default: 2)
--leader-host option Host bind for leader process (default: 0.0.0.0)
--leader-port option Port for leader process (default: 8080)
--fellow-id-start option First fellow ID (default: 7001)
--base-act-port option First activation port (default: 5561)
--base-grad-port option First gradient port (default: 5562)
--fellow-cuda-visible-devices option CUDA_VISIBLE_DEVICES assignment for fellows; pass once to apply to all, or once per fellow in order. Use 'cpu' for CPU-only.
--ready-timeout-s option Timeout for ready checks (default: 30.0)
--dry-run flag Print actions without starting/stopping processes

Calls: GET /api/v1/cluster/nodes

swarm serving

What is loaded where (no subcommand).

Subcommands: list.

Calls: GET /api/v1/serving

swarm serving list

What is loaded where: each model that is loading, ready or failed, and its stages.

Calls: GET /api/v1/serving

swarm start-cluster

Start local leader and fellow processes, then wait for ready state.

Parameter Kind What it does
--fellows option Number of fellow processes to start (default: 2)
--leader-host option Host bind for leader process (default: 0.0.0.0)
--leader-port option Port for leader process (default: 8080)
--fellow-id-start option First fellow ID (default: 7001)
--base-act-port option First activation port (default: 5561)
--base-grad-port option First gradient port (default: 5562)
--fellow-cuda-visible-devices option CUDA_VISIBLE_DEVICES assignment for fellows; pass once to apply to all, or once per fellow in order. Use 'cpu' for CPU-only.
--ready-timeout-s option Timeout for ready checks (default: 30.0)
--dry-run flag Print actions without starting processes

Calls: GET /api/v1/cluster/nodes

swarm stats

The deployment-wide numbers the landing page shows: nodes, GPUs, pools, tokens/s.

Calls: GET /api/v1/public/stats

swarm stop-cluster

Stop local leader and fellow runtime processes.

Parameter Kind What it does
--wait-s option Wait time after stop signal (default: 1.0)
--dry-run flag Print actions without stopping processes

swarm sweep

Submit experiment-grid runs as a sequential queue of jobs.

Parameter Kind What it does
--config option Path to an experiment config file.
--name, -n option Experiment config by name/config_id (resolved from exp/configs). See swarm configs.
--partition option equal or weighted (default: equal)
--continue-on-fail flag Continue queue when one job fails
--dry-run flag Expand the experiment grid and print the plan without contacting the leader.

Calls: POST /api/v1/jobs, GET /api/v1/jobs/{job_id}

swarm train

Submit a training job: a config file, a bucket or a Hugging Face model.

Parameter Kind What it does
--config option A job config file (JSON). Or --bucket / --hf-model.
--bucket option Train a bucket's base model on its datasets, like the New run form
--hf-model option Train a Hugging Face model on WikiText, like the New run form
--steps option With --bucket/--hf-model: training steps (default 200)
--seq-len option With --bucket/--hf-model: tokens per sequence (default 128)
--batch-size option With --bucket/--hf-model: a number, or auto (default: the leader picks)
--lr option With --bucket/--hf-model: learning rate, or auto (default)
--method option With --bucket/--hf-model: lora (default, adapters over frozen weights), full or freeze
--set option Any other job field as dotted.key=value, e.g. train.log_every=5 (value read as JSON when it parses)
--watch flag After submitting, follow it live (swarm watch)
--yes, -y flag Do it without asking (needed without a terminal, e.g. in a script).
--partition, --split option equal or weighted (by measured card speed within memory, else free VRAM). Overrides the config file's partition; omitted, the file's own applies (default equal).
--compression option none | fixed_intN (N = 2..8) | learned_bottleneck (half the width, 8-bit codes per token, calibrated before training: a quarter of the bytes). Overrides the config file's compression_boundaries; omitted, the file's own apply.
--pretrained option HuggingFace GPT-2 repo id to fine-tune (e.g. gpt2). Overrides model dims.
--freeze-backbone flag Freeze pretrained weights and train only the compression boundary.
--lora flag Fine-tune with LoRA adapters over frozen weights.
--lora-r option LoRA rank. Higher adapts more, at proportionally more trainable parameters. (default: 8)
--lora-alpha option LoRA scaling factor. (default: 16)
--lora-export option merged (default, self-contained) or adapters (ships only the delta). (default: merged)
--lora-targets option Comma-separated modules to adapt. Resolved from the architecture when omitted.
--weight-dtype option Store the frozen base weights in float16 (or bfloat16) and compute in the job dtype - half the weights' VRAM. Pipeline stages with --lora or a frozen backbone.
--runtime option Training runtime: torch (default, PyTorch) or keras (legacy TF rollback). (default: torch)
--context option Context window the trained model serves with, in tokens (context window CW6): at least the pool's minimum. Overrides the config file's serve.context_tokens.
--plan-id option Start on exactly the placement swarm train --plan showed (its plan_id): the job waits and says what changed rather than start elsewhere (CW12).
--exclude-card option Leave a card out of the placement, as FELLOW_ID:GPU_INDEX (repeatable); kept out when the job starts too.
--maximize-seq-len flag With --plan: the longest sequence length that places and fits now.
--wait flag Wait for completion after submit
--dry-run flag Print partition plan without submitting
--plan flag Ask the leader how it would place this job on its ready nodes now. Submits nothing.

Calls: POST /api/v1/jobs, POST /api/v1/jobs/plan, GET /api/v1/jobs/{job_id}, GET /api/v1/buckets/{bucket_id}/train-job, GET /api/v1/jobs, GET /api/v1/jobs/{job_id}/metrics/stream, GET /api/v1/resolve, GET /api/v1/auth/me

swarm watch

Stream live job metrics and per-fellow status.

Parameter Kind What it does
JOB_ID argument Job id or a unique prefix of it
--refresh-rate option (default: 1.0)

Calls: GET /api/v1/jobs, GET /api/v1/jobs/{job_id}/metrics/stream

swarm whoami

Who the CLI acts as: account, credential, scopes, leader.

Calls: GET /api/v1/auth/me

Old command names

These worked before the commands were grouped by noun. They still run, print their new name on stderr, and go away in the next minor release: swarm devices, swarm model-load, swarm model-unload, swarm nodes, swarm pending-purges, swarm release, swarm resume, swarm retry-purge, swarm set-speed, swarm stop, swarm update.

Not on the CLI

Route Why
GET /api/v1/admin/oauth-clients Credential management: the CLI does not mint, list or revoke API tokens or connected apps; swarm login / swarm logout manage its own sign-in.
DELETE /api/v1/admin/oauth-clients/{client_id} Credential management: the CLI does not mint, list or revoke API tokens or connected apps; swarm login / swarm logout manage its own sign-in.
GET /api/v1/admin/oauth-grants Credential management: the CLI does not mint, list or revoke API tokens or connected apps; swarm login / swarm logout manage its own sign-in.
DELETE /api/v1/admin/oauth-grants/{grant_id} Credential management: the CLI does not mint, list or revoke API tokens or connected apps; swarm login / swarm logout manage its own sign-in.
GET /api/v1/api-tokens Credential management: the CLI does not mint, list or revoke API tokens or connected apps; swarm login / swarm logout manage its own sign-in.
POST /api/v1/api-tokens Credential management: the CLI does not mint, list or revoke API tokens or connected apps; swarm login / swarm logout manage its own sign-in.
DELETE /api/v1/api-tokens/{token_id} Credential management: the CLI does not mint, list or revoke API tokens or connected apps; swarm login / swarm logout manage its own sign-in.
GET /api/v1/auth/2fa Account security: a credential must not change what protects the account (password, 2FA, sessions); browser only, as on MCP.
POST /api/v1/auth/2fa/disable Account security: a credential must not change what protects the account (password, 2FA, sessions); browser only, as on MCP.
POST /api/v1/auth/2fa/enable Account security: a credential must not change what protects the account (password, 2FA, sessions); browser only, as on MCP.
POST /api/v1/auth/2fa/setup Account security: a credential must not change what protects the account (password, 2FA, sessions); browser only, as on MCP.
POST /api/v1/auth/2fa/verify Human login and registration forms; swarm login signs the CLI in instead.
GET /api/v1/auth/account-status Human login and registration forms; swarm login signs the CLI in instead.
POST /api/v1/auth/login Human login and registration forms; swarm login signs the CLI in instead.
POST /api/v1/auth/logout Human login and registration forms; swarm login signs the CLI in instead.
POST /api/v1/auth/logout-all Account security: a credential must not change what protects the account (password, 2FA, sessions); browser only, as on MCP.
POST /api/v1/auth/password Account security: a credential must not change what protects the account (password, 2FA, sessions); browser only, as on MCP.
POST /api/v1/auth/register Human login and registration forms; swarm login signs the CLI in instead.
POST /api/v1/auth/resend-verification Human login and registration forms; swarm login signs the CLI in instead.
POST /api/v1/auth/reset-password Human login and registration forms; swarm login signs the CLI in instead.
POST /api/v1/auth/session/extend Account security: a credential must not change what protects the account (password, 2FA, sessions); browser only, as on MCP.
GET /api/v1/auth/sessions Account security: a credential must not change what protects the account (password, 2FA, sessions); browser only, as on MCP.
DELETE /api/v1/auth/sessions/{session_id} Account security: a credential must not change what protects the account (password, 2FA, sessions); browser only, as on MCP.
GET /api/v1/auth/username-available Human login and registration forms; swarm login signs the CLI in instead.
POST /api/v1/auth/verify-email Human login and registration forms; swarm login signs the CLI in instead.
GET /api/v1/bootstrap/fellow.sh Fetched or written by the fellow bootstrap script, not by people.
GET /api/v1/bootstrap/fellow.sh.sha256 Fetched or written by the fellow bootstrap script, not by people.
PATCH /api/v1/bootstrap/join-sessions/{session_id} Fetched or written by the fellow bootstrap script, not by people.
POST /api/v1/bootstrap/join-sessions/{session_id}/logs Fetched or written by the fellow bootstrap script, not by people.
GET /api/v1/bootstrap/manifest.json Fetched or written by the fellow bootstrap script, not by people.
GET /api/v1/bootstrap/source.tar.gz Fetched or written by the fellow bootstrap script, not by people.
POST /api/v1/inquiries Public form on the landing and business pages; admins read it (CL10).
GET /api/v1/mcp/setup Setup snippets for the web page; swarm mcp config prints them locally.
GET /api/v1/me/oauth-clients Credential management: the CLI does not mint, list or revoke API tokens or connected apps; swarm login / swarm logout manage its own sign-in.
POST /api/v1/me/oauth-clients Credential management: the CLI does not mint, list or revoke API tokens or connected apps; swarm login / swarm logout manage its own sign-in.
DELETE /api/v1/me/oauth-clients/{client_id} Credential management: the CLI does not mint, list or revoke API tokens or connected apps; swarm login / swarm logout manage its own sign-in.
GET /api/v1/me/oauth-grants Credential management: the CLI does not mint, list or revoke API tokens or connected apps; swarm login / swarm logout manage its own sign-in.
DELETE /api/v1/me/oauth-grants/{grant_id} Credential management: the CLI does not mint, list or revoke API tokens or connected apps; swarm login / swarm logout manage its own sign-in.
GET /api/v1/ready Readiness probe for orchestrators (Kubernetes); it answers 503 when not ready, and swarm overview shows the leader's /health.
POST /api/v1/waitlist Public form on the landing and business pages; admins read it (CL10).
POST /v1/chat/completions Alias of /api/v1/chat/completions (swarm infer).