[GUIDE]

kyegomez · Oct 10, 2024 · 860fab1 · 860fab1
1 parent 56fa6f5
commit 860fab1
Show file tree

Hide file tree

Showing 3 changed files with 308 additions and 3 deletions.
diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml
@@ -234,6 +234,7 @@ nav:
     - Unlocking Efficiency and Cost Savings in Healthcare; How Swarms of LLM Agents Can Revolutionize Medical Operations and Save Millions: "guides/healthcare_blog.md"
     - Understanding Agent Evaluation Mechanisms: "guides/agent_evals.md"
     - Agent Glossary: "swarms/glossary.md"
+    - The Ultimate Technical Guide to the Swarms CLI; A Step-by-Step Developers Guide: "swarms/cli/cli_guide.md"
   - Corporate:
     - Hiring: "corporate/hiring.md"
 
diff --git a/docs/swarms/cli/cli_guide.md b/docs/swarms/cli/cli_guide.md
@@ -0,0 +1,307 @@
+# 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.
+
diff --git a/swarms/cli/main.py b/swarms/cli/main.py
@@ -119,9 +119,6 @@ def main():
 
     args = parser.parse_args()
 
-    # Debug print to verify the command
-    print(f"Command received: {args.command}")
-
     show_ascii_art()
 
     # Determine which command to run