CLI Reference

Agent Swarm provides a CLI for managing the swarm, running agents, and development.

Installation

# Run directly with bunx
bunx @desplega.ai/agent-swarm <command>

# Or install globally
bun install -g @desplega.ai/agent-swarm
agent-swarm <command>

Commands

setup

Configure Claude Code to connect to the swarm.

bunx @desplega.ai/agent-swarm setup
bunx @desplega.ai/agent-swarm setup --dry-run

This sets up the MCP configuration in Claude Code so it can communicate with the Agent Swarm API.

mcp

Start the MCP API server.

bunx @desplega.ai/agent-swarm mcp

The server runs on port 3013 by default (configurable via PORT env var).

worker

Run a worker agent.

bunx @desplega.ai/agent-swarm worker
bunx @desplega.ai/agent-swarm worker --system-prompt "You are a Python specialist"
bunx @desplega.ai/agent-swarm worker --system-prompt-file ./prompts/specialist.txt

lead

Run a lead agent.

bunx @desplega.ai/agent-swarm lead
bunx @desplega.ai/agent-swarm lead --system-prompt "You are a project coordinator"

Development Commands

These are available when developing Agent Swarm locally:

# Start MCP server
bun run start        # STDIO transport
bun run start:http   # HTTP transport

# Development with hot reload
bun run dev          # STDIO
bun run dev:http     # HTTP

# MCP Inspector (debug tools)
bun run inspector:http

# Run worker/lead locally
bun run worker
bun run lead

# Hook handler
bun run hook

# Linting and formatting
bun run lint
bun run lint:fix
bun run format

# Type checking
bun run tsc:check

# Build binaries
bun run build:binary      # x64
bun run build:binary:arm64  # ARM64

# Docker
bun run docker:build:worker
bun run docker:run:worker
bun run docker:run:lead

# Generate MCP docs
bun run docs:mcp

artifact

Manage agent artifacts — serve static files or Hono apps via localtunnel.

# Serve a directory as a public artifact
agent-swarm artifact serve ./my-report --name my-report

# Serve a Hono app (must export default Hono instance)
agent-swarm artifact serve ./server.ts --name dashboard

# List active artifacts
agent-swarm artifact list

# Stop an artifact
agent-swarm artifact stop my-report

Subcommands:

Subcommand	Description
`serve <path>`	Serve a directory or script via localtunnel
`list`	List active artifacts from the service registry
`stop <name>`	Stop an artifact and close its tunnel

Options for serve:

Option	Description
`--name <name>`	Name for the artifact (derived from path if omitted)
`--port <port>`	Local port to use
`--no-auth`	Disable authentication
`--subdomain <sub>`	Request a specific localtunnel subdomain

Artifacts are registered in the service registry and automatically cleaned up when the session ends (via the Stop hook).

Dashboard UI

The React-based monitoring dashboard is in the new-ui/ directory:

cd new-ui
bun install
bun run dev

Opens at http://localhost:5173. Provides real-time visibility into:

Agent status and activity
Task list and progress
Inter-agent chat messages
Service registry
Usage and cost tracking

Getting Started — Set up your first swarm
Environment Variables — Configuration reference for all env vars
MCP Tools Reference — Complete reference for all swarm MCP tools
Deployment Guide — Production deployment options

CLI Reference

On this page