swarms/docs/swarms/cli/cli_reference.md

Swarms CLI Reference

The Swarms CLI is a comprehensive command-line interface for managing and executing Swarms agents and multi-agent architectures. This reference documents all available commands, arguments, and features.

Table of Contents

• Installation

• Basic Usage

• Commands Reference

• Global Arguments

• Command-Specific Arguments

• Error Handling

• Examples

• Configuration

Installation

The CLI is included with the Swarms package installation:

pip install swarms

Basic Usage

swarms <command> [options]

Commands Reference

Core Commands

Command	Description	Required Arguments
onboarding	Start interactive onboarding process	None
help	Display help message	None
get-api-key	Open API key portal in browser	None
check-login	Verify login status and initialize cache	None
run-agents	Execute agents from YAML configuration	--yaml-file
load-markdown	Load agents from markdown files	--markdown-path
agent	Create and run custom agent	--name, --description, --system-prompt, --task
auto-upgrade	Update Swarms to latest version	None
book-call	Schedule strategy session	None
autoswarm	Generate and execute autonomous swarm	--task, --model

Global Arguments

All commands support these global options:

Argument	Type	Default	Description
--verbose	bool	False	Enable verbose output
--help, -h	bool	False	Show help message

Command-Specific Arguments

run-agents Command

Execute agents from YAML configuration files.

python -m swarms.cli.main run-agents [options]

Argument	Type	Default	Required	Description
--yaml-file	str	"agents.yaml"	No	Path to YAML configuration file

Example:

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

load-markdown Command

Load agents from markdown files with YAML frontmatter.

python -m swarms.cli.main load-markdown [options]

Argument	Type	Default	Required	Description
--markdown-path	str	None	Yes	Path to markdown file or directory
--concurrent	bool	True	No	Enable concurrent processing for multiple files

Example:

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

agent Command

Create and run a custom agent with specified parameters.

python -m swarms.cli.main agent [options]

Required Arguments

Argument	Type	Description
--name	str	Name of the custom agent
--description	str	Description of the custom agent
--system-prompt	str	System prompt for the custom agent
--task	str	Task for the custom agent to execute

Optional Arguments

Argument	Type	Default	Description
--model-name	str	"gpt-4"	Model name for the custom agent
--temperature	float	None	Temperature setting (0.0-2.0)
--max-loops	int	None	Maximum number of loops for the agent
--auto-generate-prompt	bool	False	Enable auto-generation of prompts
--dynamic-temperature-enabled	bool	False	Enable dynamic temperature adjustment
--dynamic-context-window	bool	False	Enable dynamic context window
--output-type	str	None	Output type (e.g., 'str', 'json')
--verbose	bool	False	Enable verbose mode for the agent
--streaming-on	bool	False	Enable streaming mode for the agent
--context-length	int	None	Context length for the agent
--retry-attempts	int	None	Number of retry attempts for the agent
--return-step-meta	bool	False	Return step metadata from the agent
--dashboard	bool	False	Enable dashboard for the agent
--autosave	bool	False	Enable autosave for the agent
--saved-state-path	str	None	Path for saving agent state
--user-name	str	None	Username for the agent
--mcp-url	str	None	MCP URL for the agent

Example:

swarms agent \
  --name "Trading Agent" \
  --description "Advanced trading agent for market analysis" \
  --system-prompt "You are an expert trader..." \
  --task "Analyze market trends for AAPL" \
  --model-name "gpt-4" \
  --temperature 0.1 \
  --max-loops 5

autoswarm Command

Generate and execute an autonomous swarm configuration.

python -m swarms.cli.main autoswarm [options]

Argument	Type	Default	Required	Description
--task	str	None	Yes	Task description for the swarm
--model	str	None	Yes	Model name to use for the swarm

Example:

swarms autoswarm --task "analyze this data" --model "gpt-4"

Error Handling

The CLI provides comprehensive error handling with formatted error messages:

Error Types

Error Type	Description	Resolution
FileNotFoundError	Configuration file not found	Check file path and permissions
ValueError	Invalid configuration format	Verify YAML/markdown syntax
SwarmCLIError	Custom CLI-specific errors	Check command arguments and API keys
API Key Error	Authentication issues	Verify API key configuration
Context Length Error	Model context exceeded	Reduce input size or use larger model

Error Display Format

Errors are displayed in formatted panels with:

• Error Title: Clear error identification

• Error Message: Detailed error description

• Help Text: Suggested resolution steps

• Color Coding: Red borders for errors, yellow for warnings

Examples

Basic Agent Creation

# Create a simple agent
swarms agent \
  --name "Code Reviewer" \
  --description "AI code review assistant" \
  --system-prompt "You are an expert code reviewer..." \
  --task "Review this Python code for best practices" \
  --model-name "gpt-4" \
  --temperature 0.1

Loading Multiple Agents

# Load agents from markdown directory
swarms load-markdown \
  --markdown-path ./my_agents/ \
  --concurrent

Running YAML Configuration

# Execute agents from YAML file
swarms run-agents \
  --yaml-file production_agents.yaml

Autonomous Swarm Generation

# Generate swarm for complex task
swarms autoswarm \
  --task "Create a comprehensive market analysis report for tech stocks" \
  --model "gpt-4"

Configuration

YAML Configuration Format

For run-agents command, use this YAML structure:

agents:
  - name: "Research Agent"

    description: "Research and analysis specialist"
    model_name: "gpt-4"
    system_prompt: "You are a research specialist..."
    temperature: 0.1
    max_loops: 3
    
  - name: "Analysis Agent"

    description: "Data analysis expert"
    model_name: "gpt-4"
    system_prompt: "You are a data analyst..."
    temperature: 0.2
    max_loops: 5

Markdown Configuration Format

For load-markdown command, use YAML frontmatter:

---
name: Research Agent
description: AI research specialist
model_name: gpt-4
temperature: 0.1
max_loops: 3
---

You are an expert research agent specializing in...

Advanced Features

Progress Indicators

The CLI provides rich progress indicators for long-running operations:

• Spinner Animations: Visual feedback during execution

• Progress Bars: For operations with known completion states

• Status Updates: Real-time operation status

Concurrent Processing

Multiple markdown files can be processed concurrently:

• Parallel Execution: Improves performance for large directories

• Resource Management: Automatic thread management

• Error Isolation: Individual file failures don't affect others

Auto-upgrade System

swarms auto-upgrade

Automatically updates Swarms to the latest version with:

• Version checking

• Dependency resolution

• Safe update process

Interactive Onboarding

swarms onboarding

Guided setup process including:

• API key configuration

• Environment setup

• Basic agent creation

• Usage examples

Troubleshooting

Common Issues

1. API Key Not Set

   export OPENAI_API_KEY="your-api-key-here"
   

2. File Permissions

   chmod 644 agents.yaml
   

3. Model Not Available

   • Verify model name spelling

   • Check API key permissions

   • Ensure sufficient quota

Debug Mode

Enable verbose output for debugging:

swarms <command> --verbose

Integration

CI/CD Integration

The CLI can be integrated into CI/CD pipelines:

# GitHub Actions example
- name: Run Swarms Agents

  run: |
        swarms run-agents --yaml-file ci_agents.yaml

Scripting

Use in shell scripts:

#!/bin/bash
# Run multiple agent configurations
swarms run-agents --yaml-file agents1.yaml
swarms run-agents --yaml-file agents2.yaml

Performance Considerations

Consideration	Recommendation
Concurrent Processing	Use --concurrent for multiple files
Model Selection	Choose appropriate models for task complexity
Context Length	Monitor and optimize input sizes
Rate Limiting	Respect API provider limits

Security

Security Aspect	Recommendation
API Key Management	Store keys in environment variables
File Permissions	Restrict access to configuration files
Input Validation	CLI validates all inputs before execution
Error Sanitization	Sensitive information is not exposed in errors

Support

For additional support:

Support Option	Link
Community	Discord
Issues	GitHub Issues
Strategy Sessions	Book a Call