CLI Commands Reference

This page provides detailed documentation for all Swarms CLI commands, including their parameters, usage examples, and common use cases. For a guided walkthrough, see the CLI Tutorial. For an end-to-end multi-agent workflow you can build right now, see the Quickstart Tutorial.

Setup & Configuration Commands

init

Interactive project-scaffolding wizard. Creates a .env file with your API keys, a workspace directory, and runs validation. It does not create an agents.yaml. Usage:

swarms init [--dir <path>]

Parameters:

--dir (optional) — Project directory (default: prompted interactively)

What it does:

Prompts for a project directory (skipped when --dir is given; Enter uses the current directory)
Prompts for a WORKSPACE_DIR location (default: <project_dir>/workspace) and creates it
Shows a table of nine providers (OpenAI, Anthropic, Google, Groq, Mistral, Together AI, Cohere, xAI, OpenRouter). Enter their numbers separated by commas, all, or press Enter to skip, then paste each key at a hidden prompt
Optionally collects a SWARMS_API_KEY, needed for --marketplace-prompt-id
Writes .env to the project directory: WORKSPACE_DIR, the keys you entered, and commented-out placeholders for the rest
Validates the result: at least one provider key, the workspace directory, and the .env file

swarms init overwrites an existing .env in the project directory. Keys already exported in your shell are reported but are only written to the new file if you type them again.

Example:

swarms init                    # fully interactive
swarms init --dir ./my-project # skip the directory prompt

On success, the CLI prints a contextual “next step” tip suggesting your real first command.

onboarding

Run a comprehensive environment setup check to verify your Swarms installation. onboarding prints a note and then runs exactly the same checks as setup-check. Usage:

swarms onboarding [--verbose]

Parameters:

--verbose (optional) - Show detailed diagnostics and version detection steps

Example:

swarms onboarding --verbose

Checks performed:

Python version (requires 3.10+)
Swarms version (the installed version; no update check)
API keys: passes if at least one of OPENAI_API_KEY, ANTHROPIC_API_KEY, GOOGLE_API_KEY, or COHERE_API_KEY is set
Dependencies: tries to import torch, transformers, litellm, and rich. torch and transformers are not Swarms dependencies, so this row warns unless you installed them yourself
Environment file: a non-empty .env in the current directory
Workspace directory: WORKSPACE_DIR is set and exists. Importing Swarms creates ./agent_workspace and sets the variable when it is unset, so this check normally passes

All checks are local. Nothing is sent to a provider, so a key that is set but invalid still passes.

setup-check

Runs the environment checks listed under onboarding. When every check passes, it prints a next-step tip. Usage:

swarms setup-check [--verbose]

Parameters:

--verbose (optional) - Enable detailed output

Example:

swarms setup-check --verbose

get-api-key

Open your browser to retrieve API keys from the Swarms platform. Usage:

swarms get-api-key

Parameters: None Example:

swarms get-api-key

This opens https://swarms.world/platform/api-keys in your default browser.

Writes a local login marker and reports success. It does not contact the Swarms platform or validate any key: the first run writes logged_in to ~/.cache/swarms/auth (mode 0600), and later runs find that file and print “Authentication verified”. Use swarms setup-check to see which API keys are set. Usage:

swarms check-login

Parameters: None Example:

swarms check-login

Agent Creation & Execution Commands

agent

Create and run a custom agent with specified parameters. The task parameter is optional - if not provided, the CLI creates the agent and prints its configuration without running it (it does not start an interactive REPL). Use swarms chat if you want a live interactive session. Usage:

swarms agent \
  --name <agent_name> \
  --description <description> \
  --system-prompt <prompt> \
  [--task <task>] \
  [OPTIONS]

Required Parameters:

--name - Name of the agent
--description - Description of the agent’s purpose
--system-prompt - System prompt defining agent behavior (can use --marketplace-prompt-id instead)

Optional Parameters:

--task - Task to execute (if omitted, the agent is created but not run)
--model-name - LLM model to use (default: “gpt-5.4”, the Agent class default; the --help table’s “default: gpt-4” is out of date)
--temperature - Temperature setting (0.0-2.0)
--max-loops - Maximum loops (integer or “auto” for autonomous). Any other value exits with an error
--interactive - After the first response to --task, keep prompting you for follow-up input (default: off, despite the --help text)
--no-interactive - Disable interactive mode (already the default)
--verbose - Enable verbose output
--streaming-on - Stream tokens to the terminal
--context-length - Context window size
--retry-attempts - Number of LLM retry attempts
--return-step-meta - Accepted but has no effect; Agent has no such parameter
--dashboard - Print the agent’s configuration dashboard when it is created
--autosave - Save agent state to disk after runs
--saved-state-path - File name for saved state. A relative path is written inside the agent’s workspace directory, $WORKSPACE_DIR/agents/<agent-name>-<id>/
--user-name - Username for the agent
--mcp-url - MCP server URL to load tools from
--marketplace-prompt-id - Fetch the system prompt from the Swarms marketplace (requires SWARMS_API_KEY); replaces --system-prompt
--auto-generate-prompt - Build the system prompt from the agent’s name, description, and existing prompt
--dynamic-temperature-enabled - Vary temperature between loops
--dynamic-context-window - Enable the dynamic context window. Agent turns this on by default, but swarms agent passes False unless you give the flag
--output-type - Output type (e.g., “str”, “json”)

Examples: Create an agent with a task:

swarms agent \
  --name "Trading Agent" \
  --description "Advanced trading analysis agent" \
  --system-prompt "You are an expert trader with deep knowledge of financial markets" \
  --task "Analyze the current market trends for tech stocks" \
  --model-name "gpt-5.4" \
  --temperature 0.1

Create an agent without running it (no task; the CLI prints its configuration and exits):

swarms agent \
  --name "Assistant" \
  --description "General purpose assistant" \
  --system-prompt "You are a helpful assistant"

With autonomous loops:

swarms agent \
  --name "Research Agent" \
  --description "Autonomous research agent" \
  --system-prompt "You are a research expert" \
  --task "Research the latest AI developments" \
  --max-loops "auto" \
  --verbose

chat

Start an interactive chat agent with optimized defaults for conversation. The agent runs with max_loops="auto", temperature=1.0, dynamic temperature, and a dynamic context window. After each answer it prompts for your next message. Type exit, quit, bye, or q, or press Enter on an empty line, to end the session. Usage:

swarms chat [OPTIONS]

Optional Parameters:

--name - Agent name (default: “Swarms Agent”)
--description - Agent description (default: “A Swarms agent that can chat with the user”)
--system-prompt - Custom system prompt
--model-name - LLM model to use (default: “gpt-5.1”)
--task - Initial task/message to start the conversation

Other agent flags, such as --temperature or --max-loops, are ignored by chat. Examples: Start a basic chat:

swarms chat

With custom configuration:

swarms chat \
  --name "ChatBot" \
  --system-prompt "You are a friendly and helpful assistant" \
  --task "Hello, I need help with Python programming"

run-agents

Execute agents from a YAML configuration file. Usage:

swarms run-agents [--yaml-file <path>]

Parameters:

--yaml-file - Path to YAML configuration file (default: “agents.yaml”)

Example:

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

The file must contain a swarm_architecture section with a task: the command builds a SwarmRouter from the agents and runs that task. See the Configuration page for YAML file format.

load-markdown

Load agents from markdown files with YAML frontmatter, and print a table of the agents it built. The agents are not run, and they exist only for the duration of the command, so this is mainly a way to validate agent files. Usage:

swarms load-markdown --markdown-path <path> [--concurrent]

Required Parameters:

--markdown-path - Path to markdown file or directory

Optional Parameters:

--concurrent - Concurrent processing defaults to true and there is no --no-concurrent flag, so this is currently always on whether or not the flag is passed

Example: Load from a single file:

swarms load-markdown --markdown-path ./agent.md

In Swarms 15.0.3, passing a directory to --markdown-path fails with Unsupported file type, because the CLI hands the directory string to a loader that expects a list of files. Pass one .md file at a time, or load a folder from Python with AgentLoader.

Markdown Format:

---
name: Agent Name
description: Agent Description
model_name: gpt-5.4
temperature: 0.1
---
Your system prompt content here...

The loader reads name, description, model_name (or model), temperature, max_loops, mcp_url, and streaming_on from the frontmatter. The body becomes the system prompt.

Swarm Operations Commands

autoswarm

Generate and execute an autonomous swarm configuration based on a task. The command asks the model for a swarm spec, always writes it to disk as a ready-to-run Python file, and then runs it unless you pass --no-run. Usage:

swarms autoswarm --task <task> --model <model>

Required Parameters:

--task - Task description for the swarm
--model - Model name for swarm generation (e.g., “gpt-5.4”). It has no default; omitting it fails with “Model name cannot be empty”

Optional Parameters:

-o, --output - Output file path for the generated Python script
-d, --output-dir - Directory to create the generated Python script in (created if missing; ignored when -o is given)
--no-run - Only write the generated Python file; do not execute the swarm

Without -o, the file is named autoswarm_<swarm-name>.py, in --output-dir or the current directory. Example:

swarms autoswarm \
  --task "Analyze customer feedback and generate insights" \
  --model "gpt-5.4"

Write the generated swarm to disk without running it:

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

heavy-swarm

Run HeavySwarm with specialized agents for complex task analysis. HeavySwarm breaks down tasks into questions and uses worker agents to process them.

swarms heavy-swarm fails on every invocation in Swarms 15.0.3. The CLI always passes loops_per_agent and random_loops_per_agent to the HeavySwarm constructor, which no longer accepts them, so construction 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. Until the CLI is fixed, use the Python API:

from swarms import HeavySwarm

swarm = HeavySwarm(
    question_agent_model_name="gpt-5.4",
    worker_model_name="gpt-5.4",
    variant="default",  # or "medium", "heavy"
    max_loops=1,
)
result = swarm.run("Analyze the current market trends in renewable energy")

See HeavySwarm for every parameter.

Usage:

swarms heavy-swarm --task <task> [OPTIONS]

Required Parameters:

--task - Task for HeavySwarm to process

Optional Parameters:

--loops-per-agent - Number of execution loops per agent (default: 1). Not accepted by HeavySwarm; see the warning above
--question-agent-model-name - Model for question generation (default: “gpt-5.4”)
--worker-model-name - Model for worker agents (default: “gpt-5.4”)
--random-loops-per-agent - Enable random loops (1-10 range). Not accepted by HeavySwarm; see the warning above
--verbose - Enable verbose output

Examples: Basic usage:

swarms heavy-swarm \
  --task "Analyze the current market trends in renewable energy"

With custom configuration:

swarms heavy-swarm \
  --task "Analyze market trends" \
  --question-agent-model-name "gpt-5.4-mini" \
  --worker-model-name "claude-sonnet-4-6" \
  --verbose

llm-council

Run the LLM Council where multiple agents collaborate on a task, providing different perspectives and evaluating responses. The CLI uses the default council: four members on gpt-5.1, gemini-2.5-flash, anthropic/claude-sonnet-4-5, and xai/grok-4-1-fast-reasoning each answer, review and rank each other’s anonymized answers, and a gpt-5.1 chairman synthesizes the final response. Set keys for OpenAI, Google, Anthropic, and xAI before running it. See LLM Council. Usage:

swarms llm-council --task <task> [--verbose]

Required Parameters:

--task - Task or question for the council to process

Optional Parameters:

--verbose - Show verbose output (default: False; the CLI’s --verbose flag is off unless passed, regardless of LLMCouncil’s own internal default)

Examples: Basic usage:

swarms llm-council \
  --task "What is the best approach to implementing a microservices architecture?"

With verbose output:

swarms llm-council \
  --task "Analyze the pros and cons of different database solutions" \
  --verbose

Discovery Commands

models

List, search, and inspect every LLM model available through LiteLLM. The catalog stays in sync as providers ship new models — no CLI update required. Usage:

swarms models [--provider <name>] [--search <pattern>] [--info <model>]

Parameters:

--provider <name> — Restrict the list to one provider (e.g. anthropic, openai, groq). The provider is the prefix before / in the model name, or inferred from names such as gpt-*, claude*, and gemini*
--search <pattern> — Substring + fuzzy search by model name (up to 40 results)
--info <model> — Show context window, capabilities, and per-1M-token pricing

The flags do not combine: --info takes precedence over --search, which takes precedence over --provider. The catalog is LiteLLM’s model map, so it reflects the LiteLLM version you have installed. Examples: List every model, grouped by provider:

swarms models

Filter to one provider:

swarms models --provider anthropic

Fuzzy-search:

swarms models --search opus

Detailed info — useful before swapping a model in another command:

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

If you mistype the model name in --info, the CLI suggests the closest matches.

tips

Display random tips and tricks for using the CLI. The startup banner picks one tip per invocation; this command lets you pull them on demand. Usage:

swarms tips [--count <n>] [--category <name>] [--all]

Parameters:

--count <n> — Number of distinct random tips to print (default: 1)
--category <name> — Restrict to one of: commands, agents, swarms, models, pro, trivia, env, community
--all — Print every tip in the selected category (or every category if none given)

Examples: One random tip:

swarms tips

Five distinct random tips:

swarms tips --count 5

A power-user trick:

swarms tips --category pro

Every CLI trick, as a printable cheat-sheet:

swarms tips --category pro --all

Every tip in every category:

swarms tips --all

The prefix labels (⚡ Pro tip:, 💡 Did you know:, 🪄 Hint:, 🔥 Hot tip:, etc.) are randomized per render for visual variety.

Utility Commands

upgrade

Update Swarms to the latest version. Usage:

swarms upgrade

Parameters: None Example:

swarms upgrade

This executes: pip install --upgrade swarms, using whichever pip is first on your PATH.

Command Categories

Category	Commands
Setup	`init`, `onboarding`, `setup-check`, `get-api-key`, `check-login`
Agent Operations	`agent`, `chat`, `run-agents`, `load-markdown`
Swarm Operations	`autoswarm`, `heavy-swarm`, `llm-council`
Discovery	`models`, `tips`
Utilities	`upgrade`

Global Help

-h/--help is available on the CLI as a whole:

swarms --help              # full command and flag reference

The CLI uses a single flat argument parser (not per-command subparsers), so swarms <command> --help prints the same full reference table rather than a filtered, command-specific view. The --help table is hand-written and lags the parser: it omits the tips and models commands and their flags (--count, --category, --all, --search, --info, --provider) as well as the autoswarm flags -o, -d, and --no-run, and it lists stale defaults for --model-name and --interactive. This page reflects the parser. Every flag is accepted by every command, but each command only reads the flags documented for it here. Running swarms with no command prints the banner followed by an argparse usage error.

Common Flags

Many commands support these common flags:

--verbose — Enable detailed output
--task — Specify a task to execute
--model-name — Specify the LLM model for agent and chat (see swarms models for the catalog)
--temperature — Control randomness (0.0-2.0)
--max-loops — Set iteration limits (integer or auto)

Error Recovery

If a command fails, the CLI classifies the error and prints targeted recovery hints. For example:

401 Unauthorized → suggests swarms init or swarms get-api-key
model_not_found → suggests swarms models --search <name>
Missing WORKSPACE_DIR → suggests swarms init
429 RateLimit → suggests using a smaller --model-name
Network timeout → suggests swarms setup-check --verbose

Mistyped command names get a “Did you mean…” suggestion via fuzzy matching.

Next Steps

CLI Tutorial

A complete, hands-on tour of every command in order

Quickstart Tutorial

Build a real multi-agent workflow step by step

Configuration

YAML, markdown, and environment configuration

CLI Overview

Return to the CLI overview

Getting Started

Core Concepts

Agent Development

Reasoning Agents

Multi-Agent Architectures

Deployment & Operations

Integrations

CLI Reference

Changelog

CLI Commands

CLI Commands Reference

Setup & Configuration Commands

init

onboarding

setup-check

get-api-key

Agent Creation & Execution Commands

agent

chat

run-agents

load-markdown

Swarm Operations Commands

autoswarm

heavy-swarm

llm-council

Discovery Commands

models

tips

Utility Commands

upgrade

Command Categories

Global Help

Common Flags

Error Recovery

Next Steps

CLI Tutorial

Quickstart Tutorial

Configuration

CLI Overview

​CLI Commands Reference

​Setup & Configuration Commands

​init

​onboarding

​setup-check

​get-api-key

​check-login

​Agent Creation & Execution Commands

​agent

​chat

​run-agents

​load-markdown

​Swarm Operations Commands

​autoswarm

​heavy-swarm

​llm-council

​Discovery Commands

​models

​tips

​Utility Commands

​upgrade

​Command Categories

​Global Help

​Common Flags

​Error Recovery

​Next Steps

CLI Tutorial

Quickstart Tutorial

Configuration

CLI Overview

CLI Commands Reference

Setup & Configuration Commands

init

onboarding

setup-check

get-api-key

check-login

Agent Creation & Execution Commands

agent

chat

run-agents

load-markdown

Swarm Operations Commands

autoswarm

heavy-swarm

llm-council

Discovery Commands

models

tips

Utility Commands

upgrade

Command Categories

Global Help

Common Flags

Error Recovery

Next Steps