Skip to main content

​
Swarms CLI Overview

The Swarms CLI is a powerful command-line interface that provides comprehensive tools for creating, managing, and executing AI agents and swarms. It offers an intuitive way to interact with the Swarms framework directly from your terminal.

​
Installation

The Swarms CLI is included with the main Swarms package:
To verify the installation:

​
Quick Start

Get started with these common commands:

​
Environment Setup

Check your environment configuration:
For detailed diagnostics:

​
Interactive Chat Agent

Start a chat session with an AI agent:
With a custom name and initial task:

​
Create a Custom Agent

Create and run a custom agent:
If --task is omitted, the CLI creates the agent and prints its configuration without running it — it does not drop you into a REPL. Use swarms chat for an interactive session.

​
Available Commands

The Swarms CLI provides the following command categories:

​
Setup & Configuration

  • init - Scaffold a new project with .env, workspace directory, and validation
  • onboarding - Run environment setup check
  • setup-check - Comprehensive environment diagnostics
  • get-api-key - Open the Swarms API key page in your browser
  • check-login - Write a local login marker (no credentials are checked)

​
Agent Operations

  • agent - Create and run custom agents
  • chat - Interactive chat agent with optimized defaults (default model gpt-5.1)
  • run-agents - Execute agents from YAML configuration
  • load-markdown - Load agents from markdown files

​
Swarm Operations

  • autoswarm - Generate and execute autonomous swarms
  • heavy-swarm - Run HeavySwarm for complex task analysis (currently broken in 15.0.3; see heavy-swarm)
  • llm-council - Run LLM Council with collaborative agents

​
Discovery

  • models - List, search, and inspect LLM models available via LiteLLM
  • tips - Show rotating tips and tricks for the CLI

​
Utilities

  • upgrade - Update Swarms to the latest version

​
Getting Help

For the full command and flag reference:
The --help table omits the tips and models commands and shows some stale defaults. The Commands Reference reflects the actual parser.

​
Environment Variables

The CLI uses several environment variables for configuration:
  • OPENAI_API_KEY - OpenAI API key
  • ANTHROPIC_API_KEY - Anthropic API key
  • GOOGLE_API_KEY - Google API key
  • COHERE_API_KEY - Cohere API key
  • GROQ_API_KEY - Groq API key
  • MISTRAL_API_KEY - Mistral API key
  • TOGETHER_API_KEY - Together AI API key
  • XAI_API_KEY - xAI / Grok API key (offered by swarms init)
  • OPENROUTER_API_KEY - OpenRouter API key (offered by swarms init)
  • SWARMS_API_KEY - Swarms platform key, required for --marketplace-prompt-id
  • WORKSPACE_DIR - Directory for agent state and logs (default: ./agent_workspace)
  • SWARMS_TELEMETRY_ON - Set to false to opt out of OpenTelemetry tracing, which is on by default
Set these in your .env file or export them directly. The CLI loads the nearest .env, searching upward from the current directory, and never overrides a variable you already exported:
Where things are stored: conversations save to ./conversations/, agent state and logs go to WORKSPACE_DIR, and ~/.swarms/ only caches MCP OAuth tokens.

​
Next Steps

Commands Reference

Explore all available CLI commands in detail

Configuration

Learn how to configure agents using YAML and environment variables

​
Resources