# The Ultimate Technical Guide to the swarms CLI: A Step-by-Step Developer’s Guide

Welcome to the definitive technical guide for using the swarms Command Line Interface (CLI). The swarms CLI enables developers, engineers, and business professionals to seamlessly manage and run swarms of agents from the command line. This guide will walk you through the complete process of installing, configuring, and using the swarms CLI to orchestrate intelligent agents for your needs.

By following this guide, you will not only understand how to install and use the swarms CLI but also learn about real-world use cases, including how the CLI is used to automate tasks across various industries, from finance to marketing, operations, and beyond.

Explore the official [swarms GitHub repository](https://github.com/kyegomez/swarms), dive into the comprehensive documentation at [swarms Docs](https://docs.swarms.world), and explore the vast marketplace of agents on [swarms.ai](https://swarms.ai) to kickstart your journey with swarms!

---

## 1. Installing the swarms CLI

Before we explore the swarms CLI commands, let’s get it installed and running on your machine.

### 1.1. Installation Using `pip`

For most users, the simplest way to install the swarms CLI is through `pip`:

```bash
pip3 install -U swarms
```

This command installs the latest version of the swarms CLI package, ensuring that you have the newest features and fixes.

### 1.2. Installation Using `Poetry`

Alternatively, if you are using `Poetry` as your Python package manager, you can add the swarms package like this:

```bash
poetry add swarms
```

Once installed, you can run the swarms CLI directly using:

```bash
poetry run swarms help
```

This command shows all the available options and commands, as we will explore in-depth below.

---

## 2. Understanding swarms CLI Commands

With the swarms CLI installed, the next step is to explore its key functionalities. Here are the most essential commands:

### 2.1. `onboarding`: Setup Your Environment

The `onboarding` command guides you through setting up your environment and configuring the agents for your swarms.

```bash
swarms onboarding
```

This is the first step when you begin working with the swarms platform. It helps to:

- Authenticate your swarms account.
- Download any necessary configurations.
- Ensure everything is in place to launch agents seamlessly.

### 2.2. `help`: Learn Available Commands

Running `help` displays the various commands you can use:

```bash
swarms help
```

This command will output a helpful list like the one shown below, including detailed descriptions of each command.

```plaintext
swarms CLI - Help

Commands:
onboarding    : Starts the onboarding process
help          : Shows this help message
get-api-key   : Retrieves your API key from the platform
check-login   : Checks if you're logged in and starts the cache
read-docs     : Redirects you to swarms cloud documentation
run-agents    : Run your Agents from your agents.yaml
```

### 2.3. `get-api-key`: Access API Integration

One of the key functionalities of the swarms platform is integrating your agents with the swarms API. To retrieve your unique API key for communication, use this command:

```bash
swarms get-api-key
```

Your API key is essential to enable agent workflows and access various services through the swarms platform.

### 2.4. `check-login`: Verify Authentication

Use the `check-login` command to verify if you're logged in and ensure that your credentials are cached:

```bash
swarms check-login
```

This ensures seamless operation, allowing agents to execute tasks securely on the swarms platform without needing to log in repeatedly.

### 2.5. `read-docs`: Explore Official Documentation

Easily access the official documentation with this command:

```bash
swarms read-docs
```

You’ll be redirected to the swarms documentation site, [swarms Docs](https://docs.swarms.world), where you'll find in-depth explanations, advanced use-cases, and more.

### 2.6. `run-agents`: Orchestrate Agents

Perhaps the most important command in the CLI is `run-agents`, which allows you to execute your agents as defined in your `agents.yaml` configuration file.

```bash
swarms run-agents --yaml-file agents.yaml
```

If you want to specify a custom configuration file, just pass in the YAML file using the `--yaml-file` flag.

---

## 3. Working with the `agents.yaml` Configuration File

The `agents.yaml` file is at the heart of your swarms setup. This file allows you to define the structure and behavior of each agent you want to run. Below is an example YAML configuration for two agents.

### 3.1. Example `agents.yaml` Configuration:

```yaml
agents:
  - agent_name: "Financial-Advisor-Agent"
    model:
      model_name: "gpt-4o-mini"
      temperature: 0.3
      max_tokens: 2500
    system_prompt: |
      You are a highly knowledgeable financial advisor with expertise in tax strategies, investment management, and retirement planning.
      Provide concise and actionable advice based on the user's financial goals and situation.
    max_loops: 1
    autosave: true
    dashboard: false
    verbose: true
    dynamic_temperature_enabled: true
    saved_state_path: "financial_advisor_state.json"
    user_name: "finance_user"
    retry_attempts: 2
    context_length: 200000
    return_step_meta: false
    output_type: "str"
    task: "I am 35 years old with a moderate risk tolerance. How should I diversify my portfolio for retirement in 20 years?"

  - agent_name: "Stock-Market-Analysis-Agent"
    model:
      model_name: "gpt-4o-mini"
      temperature: 0.25
      max_tokens: 1800
    system_prompt: |
      You are an expert stock market analyst with a deep understanding of technical analysis, market trends, and long-term investment strategies.
      Provide well-reasoned investment advice, taking current market conditions into account.
    max_loops: 2
    autosave: true
    dashboard: false
    verbose: true
    dynamic_temperature_enabled: false
    saved_state_path: "stock_market_analysis_state.json"
    user_name: "market_analyst"
    retry_attempts: 3
    context_length: 150000
    return_step_meta: true
    output_type: "json"
    task: "Analyze the current market trends for tech stocks and suggest the best long-term investment options."

  - agent_name: "Marketing-Strategy-Agent"
    model:
      model_name: "gpt-4o-mini"
      temperature: 0.4
      max_tokens: 2200
    system_prompt: |
      You are a marketing strategist with expertise in digital campaigns, customer engagement, and branding.
      Provide a comprehensive marketing strategy to increase brand awareness and drive customer acquisition for an e-commerce business.
    max_loops: 1
    autosave: true
    dashboard: false
    verbose: true
    dynamic_temperature_enabled: true
    saved_state_path: "marketing_strategy_state.json"
    user_name: "marketing_user"
    retry_attempts: 2
    context_length: 200000
    return_step_meta: false
    output_type: "str"
    task: "Create a 6-month digital marketing strategy for a new eco-friendly e-commerce brand targeting millennial consumers."

  - agent_name: "Operations-Optimizer-Agent"
    model:
      model_name: "gpt-4o-mini"
      temperature: 0.2
      max_tokens: 2000
    system_prompt: |
      You are an operations expert with extensive experience in optimizing workflows, reducing costs, and improving efficiency in supply chains.
      Provide actionable recommendations to streamline business operations.
    max_loops: 1
    autosave: true
    dashboard: false
    verbose: true
    dynamic_temperature_enabled: true
    saved_state_path: "operations_optimizer_state.json"
    user_name: "operations_user"
    retry_attempts: 1
    context_length: 200000
    return_step_meta: false
    output_type: "str"
    task: "Identify ways to improve the efficiency of a small manufacturing company’s supply chain to reduce costs by 15% within one year."
```

### 3.2. Explanation of Key Fields

- **agent_name**: The name of your agent (e.g., Financial-Analysis-Agent).
- **model**: Specifies which model to use. In this case, `gpt-4o-mini` is used.
  - **temperature**: Controls the randomness of the model’s responses.
  - **max_tokens**: The maximum number of tokens to generate.
- **system_prompt**: Defines the prompt that instructs the agent.
- **max_loops**: Limits the number of times the agent will retry tasks.
- **autosave**: Saves the agent's state automatically after each run.
- **dashboard**: Set to `true` or `false` depending on whether you want to enable the agent’s dashboard.
- **saved_state_path**: Path to save agent's state, enabling future runs to resume from the last state.
- **task**: The primary task or question that the agent will address.

### 3.3. Running Agents Using `agents.yaml`

After configuring the agents, you can execute them directly from the CLI:

```bash
swarms run-agents --yaml-file agents_config.yaml
```

This command will run the specified agents, allowing them to perform their tasks and return results according to your configuration.

---

## 4. Use Cases for the swarms CLI

Now that you have a solid understanding of the basic commands and the `agents.yaml` configuration, let's explore how the swarms CLI can be applied in real-world scenarios.

### 4.1. Financial Data Analysis

For financial firms or hedge funds, agents like the "Financial-Analysis-Agent" can be set up to automate complex financial analyses. You could have agents analyze market trends, recommend portfolio adjustments, or perform tax optimizations.

Example Task: Automating long-term investment analysis using historical stock data.

```bash
swarms run-agents --yaml-file finance_analysis.yaml
```

### 4.2. Marketing Automation

Marketing departments can utilize swarms agents to optimize campaigns, generate compelling ad copy, or provide detailed marketing insights. You can create a `Marketing-Agent` to process customer feedback, perform sentiment analysis, and suggest marketing strategies.

Example Task: Running multiple agents to analyze customer sentiment from recent surveys.

```bash
swarms run-agents --yaml-file marketing_agents.yaml
```

### 4.3. Operations and Task Management

Companies can create agents for automating internal task management. For example, you might have a set of agents responsible for managing deadlines, employee tasks, and progress tracking.

Example Task: Automating a task management system using swarms agents.

```bash
swarms run-agents --yaml-file operations_agents.yaml
```

---

## 5. Advanced Usage: Customizing and Scaling Agents

The swarms CLI is flexible and scalable. As your needs grow, you can start running agents across multiple machines, scale workloads dynamically, and even run multiple swarms in parallel.

### 5.1. Running Agents in Parallel

To run multiple agents concurrently, you can utilize different YAML configurations for each agent or group of agents. This allows for extensive scaling, especially when dealing with large datasets or complex workflows.

```bash
swarms run-agents --yaml-file agents_batch_1.yaml &
swar

ms run-agents --yaml-file agents_batch_2.yaml &
```

### 5.2. Integration with Other Tools

The swarms CLI integrates with many tools and platforms via APIs. You can connect swarms with external platforms such as AWS, Azure, or your custom cloud setup for enterprise-level automation.

---

## 6. Conclusion and Next Steps

The swarms CLI is a powerful tool for automating agent workflows in various industries, including finance, marketing, and operations. By following this guide, you should now have a thorough understanding of how to install and use the CLI, configure agents, and apply it to real-world use cases.

To further explore swarms, be sure to check out the official [swarms GitHub repository](https://github.com/kyegomez/swarms), where you can contribute to the framework or build your own custom agents. Dive deeper into the documentation at [swarms Docs](https://docs.swarms.world), and browse the extensive agent marketplace at [swarms.ai](https://swarms.ai).

With the swarms CLI, the future of automation is within reach.
