[FEAT] Add CLI feature to fetch and install agents from Swarms market…

docs/mkdocs.yml

@@ -365,6 +365,7 @@ nav:
       - YAML Configuration: "swarms/cli/cli_yaml_guide.md"
       - LLM Council CLI: "swarms/cli/cli_llm_council_guide.md"
       - Heavy Swarm CLI: "swarms/cli/cli_heavy_swarm_guide.md"
+      - Marketplace CLI: "swarms/cli/cli_marketplace_guide.md"
       - CLI Multi-Agent Commands: "examples/cli_multi_agent_quickstart.md"
       - CLI Examples: "swarms/cli/cli_examples.md"
 

docs/swarms/cli/cli_marketplace_guide.md

@@ -0,0 +1,217 @@
+# Swarms CLI Marketplace Guide
+
+The Swarms CLI marketplace commands allow you to search, browse, and install agents from the [Swarms Marketplace](https://swarms.world).
+
+## Prerequisites
+
+1. **API Key**: Set your `SWARMS_API_KEY` environment variable:
+   ```bash
+   export SWARMS_API_KEY="your-api-key-here"
+   ```
+   Get your API key at: [https://swarms.world/platform/api-keys](https://swarms.world/platform/api-keys)
+
+2. **Install Swarms**:
+   ```bash
+   pip install swarms
+   ```
+
+## Commands Overview
+
+| Command | Description |
+|---------|-------------|
+| `swarms marketplace` | Show marketplace help |
+| `swarms marketplace list` | List available agents |
+| `swarms marketplace search` | Search for agents |
+| `swarms marketplace info <id>` | View agent details |
+| `swarms marketplace install <id>` | Install agent locally |
+
+## Command Reference
+
+### List Agents
+
+List all available agents in the marketplace:
+
+```bash
+swarms marketplace list
+```
+
+**Options:**
+- `--limit <n>`: Maximum results (default: 20, max: 100)
+- `--category <cat>`: Filter by category
+- `--free-only`: Show only free agents
+
+**Examples:**
+```bash
+# List first 10 agents
+swarms marketplace list --limit 10
+
+# List free agents only
+swarms marketplace list --free-only
+
+# List agents in finance category
+swarms marketplace list --category finance
+```
+
+### Search Agents
+
+Search for agents by keyword:
+
+```bash
+swarms marketplace search --query "keyword"
+```
+
+**Options:**
+- `--query <text>`: Search keyword (searches name, description, tags)
+- `--category <cat>`: Filter by category
+- `--free-only`: Show only free agents
+- `--limit <n>`: Maximum results
+
+**Examples:**
+```bash
+# Search for trading agents
+swarms marketplace search --query "trading"
+
+# Search in finance category
+swarms marketplace search --query "analysis" --category "finance"
+
+# Search free agents only
+swarms marketplace search --query "automation" --free-only
+```
+
+### View Agent Details
+
+Get detailed information about a specific agent:
+
+```bash
+swarms marketplace info <agent-id>
+```
+
+**Example:**
+```bash
+swarms marketplace info a2e3d0d3-9b6a-40a3-9904-000f2e1d03e3
+```
+
+This displays:
+- Agent name and description
+- Category and language
+- Price (free or paid)
+- Tags and requirements
+- Use cases
+
+### Install Agent
+
+Download and install an agent to your local directory:
+
+```bash
+swarms marketplace install <agent-id>
+```
+
+**Options:**
+- `--output-dir <path>`: Directory to save the agent (default: current directory)
+
+**Examples:**
+```bash
+# Install to current directory
+swarms marketplace install a2e3d0d3-9b6a-40a3-9904-000f2e1d03e3
+
+# Install to specific directory
+swarms marketplace install a2e3d0d3-9b6a-40a3-9904-000f2e1d03e3 --output-dir ./my_agents
+```
+
+The installed file includes:
+- Agent metadata as docstring
+- Requirements as comments
+- Agent code or template
+
+## Available Categories
+
+- `finance`
+- `research`
+- `coding`
+- `content`
+- `data-analysis`
+- `automation`
+- `customer-service`
+- `healthcare`
+- `legal`
+- `marketing`
+- `education`
+- `general`
+
+## Python API
+
+You can also use the marketplace programmatically:
+
+```python
+from swarms.utils.agent_marketplace import (
+    query_agents,
+    get_agent_by_id,
+    install_agent,
+    list_available_categories,
+)
+
+# List categories
+categories = list_available_categories()
+
+# Search agents
+result = query_agents(search="trading", category="finance", limit=10)
+agents = result["agents"]
+
+# Get agent details
+agent = get_agent_by_id("agent-uuid-here")
+
+# Install agent
+result = install_agent(agent_id="agent-uuid-here", output_dir="./agents")
+print(f"Installed to: {result['file_path']}")
+```
+
+## Typical Workflow
+
+1. **Search** for agents matching your needs:
+   ```bash
+   swarms marketplace search --query "customer service"
+   ```
+
+2. **Review** the list and note the agent ID
+
+3. **Get details** about a specific agent:
+   ```bash
+   swarms marketplace info <agent-id>
+   ```
+
+4. **Install** the agent:
+   ```bash
+   swarms marketplace install <agent-id> --output-dir ./agents
+   ```
+
+5. **Use** the agent in your code:
+   ```python
+   from agents.my_agent import agent
+   result = agent.run("Your task here")
+   ```
+
+## Troubleshooting
+
+### API Key Error
+```
+Swarms API key is not set
+```
+**Solution:** Set your `SWARMS_API_KEY` environment variable or add it to your `.env` file.
+
+### Agent Not Found
+```
+Agent with ID 'xxx' not found
+```
+**Solution:** Verify the agent ID is correct using `swarms marketplace list`.
+
+### Rate Limit Exceeded
+```
+HTTP 429: Too Many Requests
+```
+**Solution:** The API has a limit of 500 requests per day. Wait until midnight UTC for reset.
+
+## Support
+
+- Documentation: [https://docs.swarms.world](https://docs.swarms.world)
+- Marketplace: [https://swarms.world](https://swarms.world)
+- Issues: [https://github.com/kyegomez/swarms/issues](https://github.com/kyegomez/swarms/issues)

docs/swarms/cli/cli_reference.md

@@ -16,6 +16,7 @@ The Swarms CLI is a comprehensive command-line interface for managing and execut
   - [setup-check Command](#setup-check-command)
   - [llm-council Command](#llm-council-command)
   - [heavy-swarm Command](#heavy-swarm-command)
+  - [marketplace Command](#marketplace-command)
   - [features Command](#features-command)
 - [Error Handling](#error-handling)
 - [Examples](#examples)
@@ -63,6 +64,7 @@ swarms <command> [options]
 | `setup-check` | Run comprehensive environment setup check | None |
 | `llm-council` | Run LLM Council with multiple agents collaborating on a task | `--task` |
 | `heavy-swarm` | Run HeavySwarm with specialized agents for complex task analysis | `--task` |
+| `marketplace` | Search, browse, and install agents from Swarms Marketplace | Subcommand |
 
 ## Global Arguments
 
@@ -341,6 +343,60 @@ HeavySwarm includes specialized agents for different aspects of analysis:
 - Comprehensive report generation
 - Multi-faceted problem solving
 
+### `marketplace` Command
+
+Search, browse, and install agents from the [Swarms Marketplace](https://swarms.world).
+
+```bash
+swarms marketplace <action> [options]
+```
+
+#### Actions
+
+| Action | Description |
+|--------|-------------|
+| `search` | Search for agents by keyword |
+| `list` | List available agents |
+| `info <id>` | View agent details |
+| `install <id>` | Install agent locally |
+
+#### Arguments
+
+| Argument | Type | Default | Description |
+|----------|------|---------|-------------|
+| `--query` | `str` | None | Search keyword for agent names/descriptions |
+| `--category` | `str` | None | Filter by category |
+| `--free-only` | `bool` | `False` | Show only free agents |
+| `--limit` | `int` | `20` | Maximum results (1-100) |
+| `--output-dir` | `str` | `.` | Directory for installed agents |
+
+**Examples:**
+```bash
+# Show marketplace help
+swarms marketplace
+
+# List available agents
+swarms marketplace list --limit 10
+
+# Search for agents
+swarms marketplace search --query "trading" --category "finance"
+
+# View agent details
+swarms marketplace info a2e3d0d3-9b6a-40a3-9904-000f2e1d03e3
+
+# Install agent to directory
+swarms marketplace install a2e3d0d3-9b6a-40a3-9904-000f2e1d03e3 --output-dir ./agents
+```
+
+**Available Categories:**
+`finance`, `research`, `coding`, `content`, `data-analysis`, `automation`, `customer-service`, `healthcare`, `legal`, `marketing`, `education`, `general`
+
+**Prerequisites:**
+- Set `SWARMS_API_KEY` environment variable
+- Get your API key at: [https://swarms.world/platform/api-keys](https://swarms.world/platform/api-keys)
+
+For detailed documentation, see [CLI Marketplace Guide](cli_marketplace_guide.md).
+
 ### `features` Command
 
 Display all available CLI features and actions in a comprehensive, formatted table.