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

> Complete reference for all Swarms CLI commands with examples and parameters

# 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](/cli/tutorial). For an end-to-end multi-agent workflow you can build right now, see the [Quickstart Tutorial](/examples/cli/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:**

```bash theme={null}
swarms init [--dir <path>]
```

**Parameters:**

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

**What it does:**

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

**Example:**

```bash theme={null}
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:**

```bash theme={null}
swarms onboarding [--verbose]
```

**Parameters:**

* `--verbose` (optional) - Show detailed diagnostics and version detection steps

**Example:**

```bash theme={null}
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:**

```bash theme={null}
swarms setup-check [--verbose]
```

**Parameters:**

* `--verbose` (optional) - Enable detailed output

**Example:**

```bash theme={null}
swarms setup-check --verbose
```

***

### get-api-key

Open your browser to retrieve API keys from the Swarms platform.

**Usage:**

```bash theme={null}
swarms get-api-key
```

**Parameters:** None

**Example:**

```bash theme={null}
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:**

```bash theme={null}
swarms check-login
```

**Parameters:** None

**Example:**

```bash theme={null}
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:**

```bash theme={null}
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:

```bash theme={null}
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):

```bash theme={null}
swarms agent \
  --name "Assistant" \
  --description "General purpose assistant" \
  --system-prompt "You are a helpful assistant"
```

With autonomous loops:

```bash theme={null}
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:**

```bash theme={null}
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:

```bash theme={null}
swarms chat
```

With custom configuration:

```bash theme={null}
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:**

```bash theme={null}
swarms run-agents [--yaml-file <path>]
```

**Parameters:**

* `--yaml-file` - Path to YAML configuration file (default: "agents.yaml")

**Example:**

```bash theme={null}
swarms run-agents --yaml-file my_agents.yaml
```

See the [Configuration](/cli/configuration) page for YAML file format.

***

### load-markdown

Load agents from markdown files with YAML frontmatter.

**Usage:**

```bash theme={null}
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:

```bash theme={null}
swarms load-markdown --markdown-path ./agent.md
```

Load from a directory:

```bash theme={null}
swarms load-markdown --markdown-path ./agents/
```

**Markdown Format:**

```markdown theme={null}
---
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:**

```bash theme={null}
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:**

```bash theme={null}
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:**

```bash theme={null}
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:

```bash theme={null}
swarms heavy-swarm \
  --task "Analyze the current market trends in renewable energy"
```

With custom configuration:

```bash theme={null}
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:**

```bash theme={null}
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:

```bash theme={null}
swarms llm-council \
  --task "What is the best approach to implementing a microservices architecture?"
```

With verbose output:

```bash theme={null}
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:**

```bash theme={null}
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:

```bash theme={null}
swarms models
```

Filter to one provider:

```bash theme={null}
swarms models --provider anthropic
```

Fuzzy-search:

```bash theme={null}
swarms models --search opus
```

Detailed info — useful before swapping a model in another command:

```bash theme={null}
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:**

```bash theme={null}
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:

```bash theme={null}
swarms tips
```

Five distinct random tips:

```bash theme={null}
swarms tips --count 5
```

A power-user trick:

```bash theme={null}
swarms tips --category pro
```

Every CLI trick, as a printable cheat-sheet:

```bash theme={null}
swarms tips --category pro --all
```

Every tip in every category:

```bash theme={null}
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:**

```bash theme={null}
swarms upgrade
```

**Parameters:** None

**Example:**

```bash theme={null}
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`:

```bash theme={null}
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

<CardGroup cols={2}>
  <Card title="CLI Tutorial" icon="book-open" href="/cli/tutorial">
    A complete, hands-on tour of every command in order
  </Card>

  <Card title="Quickstart Tutorial" icon="rocket" href="/examples/cli/quickstart-tutorial">
    Build a real multi-agent workflow step by step
  </Card>

  <Card title="Configuration" icon="gear" href="/cli/configuration">
    YAML, markdown, and environment configuration
  </Card>

  <Card title="CLI Overview" icon="terminal" href="/cli/overview">
    Return to the CLI overview
  </Card>
</CardGroup>