Skip to main content

​
CLI Commands Reference

This page provides detailed documentation for all Swarms CLI commands, including their parameters, usage examples, and common use cases.

​
Setup & Configuration Commands

​
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.

​
check-login

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-4o-mini”)
  • --worker-model-name - Model for worker agents (default: “gpt-4o-mini”)
  • --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

​
Utility Commands

​
help

Display comprehensive help message with all commands and parameters. Usage: 
swarms help
Parameters: None Example: 
swarms help

​
features

Display all available features and actions in a comprehensive table. Usage: 
swarms features
Parameters: None Example: 
swarms features

​
upgrade

Update Swarms to the latest version. Usage: 
swarms upgrade
Parameters: None Example: 
swarms upgrade
This executes: pip install --upgrade swarms

​
Command Categories

CategoryCommands
Setuponboarding, setup-check, get-api-key, check-login
Agent Operationsagent, chat, run-agents, load-markdown
Swarm Operationsautoswarm, heavy-swarm, llm-council
Utilitieshelp, features, upgrade

​
Common Flags

Many commands support these common flags:
  • --verbose - Enable detailed output
  • --task - Specify a task to execute
  • --model-name - Specify the LLM model
  • --temperature - Control randomness (0.0-2.0)
  • --max-loops - Set iteration limits

​
Next Steps

Configuration

Learn how to configure agents using YAML files

CLI Overview

Return to CLI overview and quick start guide

Build docs developers (and LLMs) love

Get started for freeTalk to us