Skip to main content
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:
Verify the install — the banner that prints is more than decoration:
You’ll see a panel like this:
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:
  1. Picking a project directory
  2. Picking a WORKSPACE_DIR (where agents read and write files)
  3. Adding API keys for any providers you have access to
  4. Writing a .env file
  5. Validating the result
Run it:
The wizard handles missing pieces gracefully — leave a key blank if you don’t have one yet. 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:
This pings each configured provider, checks Python version, validates dependencies, and tells you exactly what’s wrong if anything is.

​
3. Your First Conversation: swarms chat

The fastest way to talk to a model:
That’s it. The CLI builds an Agent with autonomous looping enabled (max_loops="auto"), drops you into an interactive REPL, and streams responses back. Type exit or hit Ctrl-C to leave — your session state is autosaved so you can resume later. Customize the persona:
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:
Key flags worth memorizing: 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:
Restrict to one provider:
Fuzzy-search by name (substring matches first, then difflib fuzzy matches):
Get detailed info about a specific model — context window, capabilities, pricing per million tokens:
Output:
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:
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:
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:
Each worker reasons for --loops-per-agent iterations on its sub-question, which gives meaningfully deeper output than a single LLM call. With high loop counts this gets expensive — check costs first with swarms models --info <name> to know what you’re paying per million tokens. For non-deterministic exploration:

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

llm-council runs the same task across multiple models and aggregates their responses. It’s the right shape when you want disagreement surfaced — adversarial verification, due-diligence reviews, or “is this consensus actually consensus?” questions:
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:
Run it:
Markdown — drop a folder of .md files, each with YAML frontmatter:
Load all agents in the folder concurrently:
Markdown loading is the most ergonomic format if you’re building a library of reusable agents — each file is self-describing and easy to share via git.

​
10. The tips Engine

The CLI ships with ~75 categorized tips covering every command and flag. The banner rotates one per invocation, but you can also pull them on demand:
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: Pipe a task in from stdin:
Scope API keys per project with direnv: drop a .envrc per project, and swarms auto-loads the project’s .env because of how python-dotenv resolves the cwd. Long autonomous loops inside tmux: detach with Ctrl-b d and the agent keeps running. Combined with --autosave, you can disconnect for hours and resume the session later. Watch a model think:
Save and resume an agent’s memory:
Cap context for long sessions:
When the agent approaches 90% of that budget, its built-in compressor summarizes older history automatically. Attach an MCP tool server:
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:
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, every CLI flag maps to an Agent class parameter documented in the API Reference.
A few good third commands to try right now:
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, heavy-swarm, 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