Swarms CLI Tutorial

If you can use git, curl, or gh, you already know how to use the Swarms CLI. This tutorial walks through every command in order, from a clean install to running a four-agent debate on a real task. By the end you’ll be productive without ever leaving the terminal. We’ll cover:

Installing and verifying the CLI
Scaffolding a project with swarms init
Talking to a single agent with swarms chat
Running one-shot tasks with swarms agent
Discovering models with the new swarms models command
Auto-generating swarms with swarms autoswarm
Running deep multi-agent analyses with swarms heavy-swarm and swarms llm-council
Loading whole teams from YAML and markdown files
Power-user tricks: streaming, autosave, MCP servers, environment scoping
The rotating swarms tips engine and how to use it
Recovering from errors — the CLI’s built-in classifier and typo-corrector

1. Install and Verify

The CLI ships with the main package. One line installs both:

pip install -U swarms

Verify the install — the banner that prints is more than decoration:

swarms --help

Every invocation starts with a panel like this, followed here by the full command reference. (Running swarms with no command prints the banner and then a usage error, because a command is required.)

╭─ 👾 Swarms ──────────────────────────────────────────────╮
│  ▄     ▄    Swarms  v15.0.3                              │
│  ▀█████▀    OpenAI +1 more · Multi-Agent Framework       │
│  █▀███▀█    ~/Desktop/research/swarms                    │
│  ███████    https://github.com/kyegomez/swarms           │
│  ▀█   █▀                                                 │
│                                                          │
│ ───────────────────────────────────────────────────────  │
│  ⚡ Pro tip: Start chatting instantly with swarms chat   │
╰────────────────────────────────────  swarms --help  ─────╯
 🪄 Hint: Use --temperature 0.1 for deterministic responses

The second line (“OpenAI +1 more”) detects which provider keys are set in your environment. If it says “No API key found”, that’s your next step. The randomized tip lines (⚡ Pro tip, 🪄 Hint, etc.) rotate on every invocation. They are not noise — they surface real CLI capabilities you might have missed.

2. Scaffold a Project: `swarms init`

init is the interactive wizard. It walks you through:

Picking a project directory
Picking a WORKSPACE_DIR (where agents read and write files)
Adding API keys for the providers you pick from a numbered list (and, optionally, a SWARMS_API_KEY)
Writing a .env file
Validating the result

Run it:

swarms init

The wizard handles missing pieces gracefully — leave a key blank if you don’t have one yet. It overwrites any existing .env in the project directory. When it finishes you’ll have:

<project_dir>/.env — your API keys
<project_dir>/workspace/ — the workspace directory

After it finishes, the CLI prints a contextual “next step” tip based on the success state. That same engine fires after setup-check passes, suggesting your real first command (usually swarms chat). To verify the environment at any time:

swarms setup-check --verbose

This checks your Python version, whether at least one provider key is set, whether key dependencies import, and whether .env and WORKSPACE_DIR exist. The checks are local — no provider is contacted, so an invalid key still passes.

3. Your First Conversation: `swarms chat`

The fastest way to talk to a model:

swarms chat

That’s it. The CLI builds an Agent on gpt-5.1 (change it with --model-name) with autonomous looping enabled (max_loops="auto") and drops you into an interactive REPL. Responses print once each is complete — swarms chat does not enable streaming or autosave by default. Type exit, quit, bye, or q, or press Enter on an empty line, to leave the session. Customize the persona:

swarms chat \
  --name "Tutor" \
  --system-prompt "You are a patient Python tutor for absolute beginners" \
  --task "Walk me through how list comprehensions work"

The --task flag seeds the first message; from there the conversation is interactive.

4. One-Shot Agents: `swarms agent`

When you don’t want a REPL — say, in a shell script or CI job — use swarms agent:

swarms agent \
  --name "MarketAnalyst" \
  --description "Researches and summarizes equity markets" \
  --system-prompt "You are an equity research analyst. Always cite sources." \
  --task "Give me a one-paragraph thesis on NVIDIA over the next 12 months" \
  --model-name "claude-sonnet-4-6" \
  --temperature 0.1 \
  --max-loops 1

Key flags worth memorizing:

Flag	What it does
`--max-loops auto`	Let the agent decide when it’s done (autonomous mode)
`--streaming-on`	Stream tokens to the terminal as they arrive
`--verbose`	Show every internal step the agent takes
`--autosave --saved-state-path state.json`	Save agent state to disk (written, not reloaded by later runs)
`--mcp-url <url>`	Auto-discover and use tools from an MCP server
`--marketplace-prompt-id <id>`	Pull a pre-built system prompt from the marketplace

Combine --streaming-on --verbose to watch the model think token by token.

5. Discover Models: `swarms models`

Before you change --model-name, you need to know what to put there. The CLI ships a model-discovery command backed by the LiteLLM registry, so the list stays current as providers ship new models. List every model, grouped by provider:

swarms models

Restrict to one provider:

swarms models --provider anthropic

Fuzzy-search by name (substring matches first, then difflib fuzzy matches):

swarms models --search opus

Get detailed info about a specific model — context window, capabilities, pricing per million tokens:

swarms models --info claude-sonnet-4-6

The output is a table with these rows, filled from LiteLLM’s model map:

claude-sonnet-4-6
┌───────────────────┬─────────┐
│ Provider          │ …       │
│ Mode              │ …       │
│ Max input tokens  │ …       │
│ Max output tokens │ …       │
│ Input cost        │ … / 1M  │
│ Output cost       │ … / 1M  │
│ Cache read cost   │ … / 1M  │
│ Function calling  │ ✓ or —  │
│ Vision            │ ✓ or —  │
│ System messages   │ ✓ or —  │
│ Streaming         │ ✓ or —  │
└───────────────────┴─────────┘

The values depend on the LiteLLM version you have installed; a model newer than your LiteLLM release may not be listed. If you mistype a model name, the --info command suggests the closest matches.

6. Auto-Generate a Swarm: `swarms autoswarm`

Don’t know which architecture fits your task? Let the CLI design one:

swarms autoswarm \
  --task "Produce a competitive analysis of the AI chip market" \
  --model "gpt-5.4"

The CLI calls a planning LLM, generates a complete swarm spec, writes a ready-to-run Python file to disk, and (by default) executes it. Add --no-run to inspect the file before running:

swarms autoswarm \
  --task "Build me a multi-agent customer support pipeline" \
  --model "gpt-5.4" \
  --no-run \
  -o ./customer_support_swarm.py

The generated file is plain Python — read it, edit it, version-control it.

7. Heavy Analysis: `swarms heavy-swarm`

For research-grade depth, heavy-swarm decomposes the task into specialist questions, dispatches them to multiple worker agents in parallel, then synthesizes a final answer:

swarms heavy-swarm \
  --task "What are the second-order consequences of widespread AI coding assistants on the software job market?" \
  --worker-model-name "claude-sonnet-4-6" \
  --question-agent-model-name "gpt-5.4"

In Swarms 15.0.3, swarms heavy-swarm fails on every invocation. The CLI always passes loops_per_agent and random_loops_per_agent to the HeavySwarm constructor, which no longer accepts them, so it raises TypeError and the CLI prints a “HeavySwarm Error” panel. --loops-per-agent and --random-loops-per-agent have no counterpart in HeavySwarm any more. Run it from Python instead:

from swarms import HeavySwarm

swarm = HeavySwarm(
    question_agent_model_name="gpt-5.4",
    worker_model_name="claude-sonnet-4-6",
    variant="default",  # or "medium", "heavy"
    max_loops=1,
)
result = swarm.run(
    "What are the second-order consequences of widespread AI coding assistants on the software job market?"
)

See HeavySwarm for every parameter. Deep runs get expensive, so check costs first with swarms models --info <name>.

8. Multi-Model Debate: `swarms llm-council`

llm-council runs the same task across four council members — gpt-5.1, gemini-2.5-flash, anthropic/claude-sonnet-4-5, and xai/grok-4-1-fast-reasoning — which then review and rank each other’s anonymized answers. You need OpenAI, Google, Anthropic, and xAI keys for the default council. It’s the right shape when you want disagreement surfaced — adversarial verification, due-diligence reviews, or “is this consensus actually consensus?” questions:

swarms llm-council \
  --task "Should our team adopt Rust for our next backend service?" \
  --verbose

The council’s chairman synthesizes the members’ positions, highlighting where they agree and where they diverge.

9. Load a Team from a File

For repeatable workflows, define agents in a YAML or markdown file and load them with one command. YAML — agents.yaml:

agents:
  - agent_name: Researcher
    model_name: gpt-5.4
    system_prompt: You research a topic thoroughly with citations.
  - agent_name: Writer
    model_name: claude-sonnet-4-6
    system_prompt: You turn research into engaging prose.

swarm_architecture:
  name: Research-Brief-Swarm
  description: Research a topic, then write a brief from the research
  swarm_type: SequentialWorkflow
  task: Write a 500-word brief on the future of robotic surgery

Run it:

swarms run-agents --yaml-file agents.yaml

Markdown — keep each agent in its own .md file with YAML frontmatter:

---
name: SecurityReviewer
description: Reviews code for security issues
model_name: claude-sonnet-4-6
temperature: 0.1
---
You are a senior security engineer. Find vulnerabilities and explain them
in terms a junior developer can understand.

Load and validate an agent file:

swarms load-markdown --markdown-path ./agents/security_reviewer.md

The command builds the agent and prints a summary table; it does not run it. In Swarms 15.0.3, passing a directory fails with Unsupported file type, so load one file at a time. Markdown files are still a good format for a library of reusable agents — each file is self-describing and easy to share via git.

10. The `tips` Engine

The CLI ships with 83 categorized tips covering every command and flag. The banner rotates one per invocation, but you can also pull them on demand:

swarms tips              # one random tip
swarms tips --count 5    # five distinct random tips
swarms tips --category pro            # one CLI power-user trick
swarms tips --category models --all   # every tip about --model-name

Categories available: commands, agents, swarms, models, pro, trivia, env, community. Use swarms tips --all to dump every tip in every category — useful as a cheat-sheet to print and pin next to your terminal. The prefix labels (⚡ Pro tip:, 💡 Did you know:, 🪄 Hint:, 🔥 Hot tip:, and four others) are randomized per render. It’s intentional — varied prefixes catch your eye when a tip is genuinely useful.

11. Power-User Tricks

A few patterns that pay off in real use: Pass a file’s contents as the task: the CLI does not read stdin, so expand the file in your shell:

swarms agent \
  --name Summarizer \
  --description "Summarizes documents" \
  --system-prompt "Summarize for a non-technical audience." \
  --task "$(cat notes.txt)"

Scope API keys per project: swarms loads the nearest .env, searching upward from the current directory, so each project directory can carry its own keys. Variables already exported in your shell win over the file. Long autonomous loops inside tmux: detach with Ctrl-b d and the agent keeps running; reattach later to see the result. Watch a model think:

swarms agent ... --streaming-on --verbose

Persist an agent’s state to disk:

swarms agent ... --autosave --saved-state-path ./research.json

--saved-state-path is a write target only — nothing in the CLI loads it back on a later run, so pointing a new invocation at the same path does not resume the earlier session. A relative path is written inside the agent’s workspace directory, $WORKSPACE_DIR/agents/<agent-name>-<id>/. Cap context for long sessions:

swarms agent ... --context-length 32000

When the agent approaches 90% of that budget, its built-in compressor summarizes older history automatically. Attach an MCP tool server:

swarms agent ... --mcp-url http://localhost:8000/sse

The agent auto-discovers every tool the server exposes — no Python glue needed.

12. Errors and Recovery

When something goes wrong, the CLI doesn’t just dump a stack trace. It classifies the error and prints targeted recovery hints:

A 401 Unauthorized from a provider → “Run swarms init or swarms get-api-key”
A model_not_found error → “Find a valid model with swarms models --search <name>”
A missing WORKSPACE_DIR → “Run swarms init to scaffold one”
A 429 RateLimit → “Slow down, use a smaller --model-name, or retry in a minute”
A network timeout → “Run swarms setup-check --verbose to validate connectivity”
A ModuleNotFoundError → “Try swarms upgrade or pip install -U swarms”

If you mistype a command, the CLI suggests the closest match:

$ swarms agnt --task hi
─── Error ───
Unknown command 'agnt'
Available commands: init, onboarding, ...
Did you mean swarms agent?

This uses Python’s difflib.get_close_matches against the command list, so corrections work even for two-character typos.

13. Where to Go Next

You now have everything you need for daily use. A few directions to grow into:

Build a reusable agent library — Use markdown frontmatter to define agents once and load them from any project with swarms load-markdown.
Compose pipelines as YAML — swarms run-agents --yaml-file lets you commit the entire workflow to git.
Wire MCP tools — Any tool exposed via an MCP server (filesystem, web search, database) becomes available to any agent through --mcp-url.
Read the API reference — When you’re ready to leave the CLI for Python code, most swarms agent flags map to an Agent class parameter documented in the API Reference.

A few good third commands to try right now:

swarms tips --category pro
swarms models --search sonnet
swarms llm-council --task "Summarize the case for and against AGI by 2035"

That’s the CLI in 2,000 words. The shortest path to feeling fluent is to install it, run swarms init, then alternate between swarms chat for ideation and swarms agent --task '...' for one-shot work. Everything else — autoswarm, llm-council, YAML loading — composes from the same primitives once you’re comfortable with the basics.

Commands Reference

Every command, every flag, with examples

Configuration

YAML, markdown, and environment configuration

Quickstart Tutorial

A hands-on multi-agent workflow you can build right now

API Reference

Map every CLI flag back to its Python API counterpart

Getting Started

Core Concepts

Agent Development

Reasoning Agents

Multi-Agent Architectures

Deployment & Operations

Integrations

CLI Reference

Changelog

Swarms CLI Tutorial

1. Install and Verify

2. Scaffold a Project: `swarms init`

3. Your First Conversation: `swarms chat`

4. One-Shot Agents: `swarms agent`

5. Discover Models: `swarms models`

6. Auto-Generate a Swarm: `swarms autoswarm`

7. Heavy Analysis: `swarms heavy-swarm`

8. Multi-Model Debate: `swarms llm-council`

9. Load a Team from a File

10. The `tips` Engine

11. Power-User Tricks

12. Errors and Recovery

13. Where to Go Next

Commands Reference

Configuration

Quickstart Tutorial

API Reference

​1. Install and Verify

​2. Scaffold a Project: swarms init

​3. Your First Conversation: swarms chat

​4. One-Shot Agents: swarms agent

​5. Discover Models: swarms models

​6. Auto-Generate a Swarm: swarms autoswarm

​7. Heavy Analysis: swarms heavy-swarm

​8. Multi-Model Debate: swarms llm-council

​9. Load a Team from a File

​10. The tips Engine

​11. Power-User Tricks

​12. Errors and Recovery

​13. Where to Go Next

​Related

Commands Reference

Configuration

Quickstart Tutorial

API Reference

1. Install and Verify

2. Scaffold a Project: `swarms init`

3. Your First Conversation: `swarms chat`

4. One-Shot Agents: `swarms agent`

5. Discover Models: `swarms models`

6. Auto-Generate a Swarm: `swarms autoswarm`

7. Heavy Analysis: `swarms heavy-swarm`

8. Multi-Model Debate: `swarms llm-council`

9. Load a Team from a File

10. The `tips` Engine

11. Power-User Tricks

12. Errors and Recovery

13. Where to Go Next

Related