Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.swarms.world/llms.txt

Use this file to discover all available pages before exploring further.

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

​
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