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. Usage:

swarms init [--dir <path>]

Parameters:

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

What it does:

Prompts for a project directory
Prompts for a WORKSPACE_DIR location
Walks through every supported LLM provider and collects API keys
Writes .env to the project directory
Validates the resulting environment

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. 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
API key configuration
Required dependencies (torch, transformers, litellm, rich)
Environment file (.env)
Workspace directory (WORKSPACE_DIR)

setup-check

Identical to onboarding. Runs comprehensive environment setup checks. 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.

Verify authentication status and initialize the authentication cache. 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 agent runs in interactive mode by default. 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, runs in interactive mode)
--model-name - LLM model to use (default: “gpt-4”)
--temperature - Temperature setting (0.0-2.0)
--max-loops - Maximum loops (integer or “auto” for autonomous)
--interactive - Enable interactive mode (default: True)
--no-interactive - Disable interactive mode
--verbose - Enable verbose output
--streaming-on - Enable streaming mode
--context-length - Context window size
--retry-attempts - Number of retry attempts
--return-step-meta - Return step metadata
--dashboard - Enable dashboard
--autosave - Enable autosave
--saved-state-path - Path for saving agent state
--user-name - Username for the agent
--mcp-url - MCP URL for the agent
--marketplace-prompt-id - Fetch system prompt from marketplace
--auto-generate-prompt - Enable auto-generation of prompts
--dynamic-temperature-enabled - Enable dynamic temperature adjustment
--dynamic-context-window - Enable dynamic context window
--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-4" \
  --temperature 0.1

Create an agent in interactive mode (no task):

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. Uses autonomous loops (max_loops="auto") by default. 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
--task - Initial task/message to start the conversation

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

See the Configuration page for YAML file format.

load-markdown

Load agents from markdown files with YAML frontmatter. Usage:

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

Required Parameters:

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

Optional Parameters:

--concurrent - Enable concurrent processing (default: True)

Examples: Load from a single file:

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

Load from a directory:

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

Markdown Format:

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

Swarm Operations Commands

autoswarm

Generate and execute an autonomous swarm configuration based on a task. Usage:

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

Required Parameters:

--task - Task description for the swarm
--model - Model name for swarm generation (e.g., “gpt-4”)

Example:

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

heavy-swarm

Run HeavySwarm with specialized agents for complex task analysis. HeavySwarm breaks down tasks into questions and uses worker agents to process them. 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)
--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)
--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" \
  --loops-per-agent 3 \
  --question-agent-model-name "gpt-4" \
  --worker-model-name "gpt-4" \
  --verbose

llm-council

Run the LLM Council where multiple agents collaborate on a task, providing different perspectives and evaluating responses. 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: True)

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)
--search <pattern> — Substring + fuzzy search by model name
--info <model> — Show context window, capabilities, and per-1M-token pricing

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-opus-4-7

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

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

Every command supports --help:

swarms --help              # top-level help
swarms agent --help        # flags for one command

Common Flags

Many commands support these common flags:

--verbose — Enable detailed output
--task — Specify a task to execute
--model-name — Specify the LLM model (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

​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