Skip to content

CLI reference#

swarm is an argparse-based CLI. 39 subcommands, organised into 9 command groups.

Install (if developing from source):

pip install -e ml_team/
swarm --version
# swarm 0.11.0

Or via pip once we publish:

pip install swarm-agent

Global flags#

All commands accept:

Flag Env var Default Purpose
--api URL SWARM_API http://localhost:8000 swarm API base URL
--token TOKEN SWARM_TOKEN loaded from ~/.swarm/auth.json Bearer token
--format FMT — table table / json / yaml
--verbose — off Full stack traces on error
--quiet — off Suppress non-error output

Auth#

swarm login [--email E] [--password P] [--api URL]
swarm logout
swarm whoami                          # prints current user + role
swarm health                          # pings /livez

Pipelines#

swarm pipelines list [--state STATE] [--template T] [--limit N]
swarm pipelines run \
  --problem "Problem statement" \
  --dataset data.csv \
  [--template fast_prototype | default_ml_pipeline | parallel_research] \
  [--compliance none | rbi_free_ai | hipaa | eu_ai_act_high_risk] \
  [--name run_name]
swarm pipelines status <run_id> [--follow]
swarm pipelines cancel <run_id>
swarm pipelines resume <run_id>
swarm pipelines events <run_id> [--kind tool_call|llm_call|error|...]
swarm pipelines artifacts <run_id>

Agents#

swarm agents list [--team algorithm|data|...]
swarm agents get <name>               # full definition
swarm agents tools                    # catalogue of tools any agent can call
swarm agents invoke <name> --input '<json>'

Deployments#

swarm deployments list [--model M]
swarm deployments package --run-id <id> --name <model> --version <v>
swarm deployments shadow-start \
  --model <m> --challenger <v2> --champion <v1> \
  --sample-rate 0.1 --duration 24h
swarm deployments shadow-status <model>
swarm deployments compare --model <m> --champion <v1> --challenger <v2>
swarm deployments promote --model <m> --challenger <v2>
swarm deployments rollback --model <m> --to-version <v>
swarm deployments retire --model <m> --version <v>
swarm deployments audit --model <m> --from-version <v1> --to-version <v2>
swarm deployments set-baseline --model <m> --version <v> --run-id <id>
swarm deployments approvals list [--pending]
swarm deployments approvals approve <gate_id> [--comment "..."]
swarm deployments approvals reject <gate_id> --reason "..."

Plugins#

swarm plugins list
swarm plugins install <path>
swarm plugins uninstall <name>
swarm plugins reload <name>
swarm plugins info <name>

Features (feature flags)#

swarm features list
swarm features get <name>
swarm features set <name> <value>     # on / off / <custom_string>
swarm features reset <name>

Cron#

swarm cron list
swarm cron create \
  --name <name> --schedule <spec> \
  --task retrain|drift_check|audit_pdf|custom \
  --config '<json>'
swarm cron get <id>
swarm cron update <id> [--schedule] [--enabled] [--config]
swarm cron delete <id>
swarm cron run <id>                   # run-now
swarm cron runs <id> [--limit N]

Batch#

swarm batch list
swarm batch submit \
  --input <path.jsonl> \
  --processor inference|echo|custom \
  --config '<json>' \
  [--concurrency N]
swarm batch status <run_id>
swarm batch results <run_id> [--limit N]
swarm batch resume <run_id>
swarm batch stats <run_id>

Audit#

swarm audit generate --run-id <id> [--profile P] [--template T] [--output O]
swarm audit rollup --model <m> --from <date> --to <date> [--profile P] --output <path>
swarm audit bundle --run-id <id> --output <path.tar.gz>
swarm audit verify <pdf_path>         # validates tamper-evident manifest

LLM#

swarm llm ping                        # pings each configured provider + tier
swarm llm models                      # list available models per provider

Reports#

swarm reports costs --from <date> --to <date> [--group-by provider|agent|model]
swarm reports usage --from <date> --to <date>

Datasets#

swarm datasets list
swarm datasets profile <name>

Programmatic use#

For Python, the same commands are available as library calls:

from ml_team.cli import api_client

client = api_client()                    # reads ~/.swarm/auth.json
run = client.pipelines.run(
    problem_statement="Classify irises",
    dataset_path="iris.csv",
    template="fast_prototype",
)
print(run.run_id)

Or directly with httpx using a JWT:

import httpx
resp = httpx.post(
    "http://localhost:8000/api/v1/pipelines",
    headers={"Authorization": f"Bearer {token}"},
    json={...},
)

Shell completion#

eval "$(swarm --bash-completion)"
# Permanent:
echo 'eval "$(swarm --bash-completion)"' >> ~/.bashrc

eval "$(swarm --zsh-completion)"

swarm --fish-completion > ~/.config/fish/completions/swarm.fish

Exit codes#

Code Meaning
0 Success
1 Generic error (network, parse, unexpected)
2 Invalid arguments
3 Authentication failed
4 Permission denied (403)
5 Resource not found (404)
6 Resource conflict (409 — e.g. plugin manifest tampered)
7 Rate limit exceeded (429)
8 API server error (5xx)

Useful for shell scripting + CI:

if ! swarm pipelines status <id> --quiet; then
    echo "Pipeline not reachable; exit code $?"
fi

Next#