swarmclaw

## Overview

SwarmClaw is a self-hosted AI agent orchestration platform. This skill gives you CLI access to manage agents, tasks, chats, chatrooms, goals, schedules, memory, wallets, connectors, autonomy controls, webhooks, extensions, and more across one or many SwarmClaw instances.

The CLI maps 1:1 to the SwarmClaw REST API. Every command follows the pattern:

```
swarmclaw <group> <action> [id] [--flags]
```

Install the CLI:

```bash
npm i -g @swarmclawai/swarmclaw
```

## Setup

1. Install: `npm i -g @swarmclawai/swarmclaw`
2. Set env var: `export SWARMCLAW_ACCESS_KEY=<your-key>` (shown in terminal on first run)
3. Default URL: `http://localhost:3456` — override with `SWARMCLAW_URL` or `--base-url`
4. Full docs: https://swarmclaw.ai/docs

## Output Modes

Use machine-readable output when parsing results:

- **`--json`** — structured JSON output (preferred for all API-mapped commands)
- **`--raw`** — plain text output (legacy commands)

Filter results with `--query key=value`:

```bash
swarmclaw tasks list --json --query status=in_progress
swarmclaw memory list --json --query agentId=abc123 --query q=pricing
swarmclaw runs list --json --query sessionId=xyz --query limit=10
```

## Core Commands

### Agents

Manage your agent fleet — create, configure, monitor, and clone agents.

```bash
# List all agents
swarmclaw agents list --json

# Get full agent details
swarmclaw agents get <agentId> --json

# Create an agent (pass JSON body via --data)
swarmclaw agents create --data '{"name":"Research Bot","provider":"anthropic","model":"claude-sonnet-4-20250514"}' --json

# Update agent config
swarmclaw agents update <agentId> --data '{"name":"Updated Name","soul":"You are a research assistant"}' --json

# Get live agent status (running chats, current task, etc.)
swarmclaw agents status <agentId> --json

# Clone an agent with all its config
swarmclaw agents clone <agentId> --json

# Bulk update multiple agents
swarmclaw agents bulk-update --data '{"ids":["id1","id2"],"changes":{"provider":"openai"}}' --json
```

Other: `delete`, `trash`, `restore`, `purge`, `thread`

### Tasks

Create, assign, and track work items on the task board.

```bash
# List all tasks (filterable by status, agent, project)
swarmclaw tasks list --json
swarmclaw tasks list --json --query status=in_progress --query agentId=<id>

# Create and assign a task
swarmclaw tasks create --data '{"title":"Analyse competitor pricing","description":"Research and compare competitor pricing strategies","agentId":"<agentId>"}' --json

# Get task details
swarmclaw tasks get <taskId> --json

# Update task status or fields
swarmclaw tasks update <taskId> --data '{"status":"completed"}' --json

# Get task board metrics (24h, 7d, or 30d)
swarmclaw tasks metrics --json --query range=7d

# Import GitHub issues as tasks
swarmclaw tasks import-github --data '{"repo":"owner/repo","labels":["bug"],"agentId":"<id>"}' --json

# Bulk update tasks
swarmclaw tasks bulk --data '{"ids":["id1","id2"],"changes":{"status":"todo"}}' --json
```

Other: `delete`, `approve`, `claim`, `purge`

### Chats

Manage agent chat sessions — create, send messages, stream responses, and control execution.

> **Terminology:** `chats` in the CLI = "sessions" in the SwarmClaw UI. Both refer to the same thing.

```bash
# List chats
swarmclaw chats list --json

# Create a new chat for an agent
swarmclaw chats create --data '{"agentId":"<agentId>"}' --json

# Send a message and stream the agent response (SSE)
swarmclaw chats chat <chatId> --data '{"message":"Give me a status update"}' --json

# Get chat message history
swarmclaw chats messages <chatId> --json

# Stop a running chat
swarmclaw chats stop <chatId> --json

# Clear chat history
swarmclaw chats clear <chatId> --json

# Append a user message without triggering a response
swarmclaw chats messages-send <chatId> --data '{"role":"user","content":"Note: budget is $5000"}' --json
```

Other: `get`, `update`, `delete`, `delete-many`, `edit-resend`, `retry`, `queue`, `queue-add`, `queue-clear`, `heartbeat-disable-all`, `deploy`, `devserver`, `checkpoints`

### Chatrooms

Multi-agent collaborative spaces where multiple agents discuss and work together.

```bash
# List chatrooms
swarmclaw chatrooms list --json

# Create a chatroom
swarmclaw chatrooms create --data '{"name":"Strategy Room","description":"Multi-agent planning"}' --json

# Add agents to a chatroom
swarmclaw chatrooms add-member <chatroomId> --data '{"agentId":"<agent1>"}' --json
swarmclaw chatrooms add-member <chatroomId> --data '{"agentId":"<agent2>"}' --json

# Send a message — all member agents respond
swarmclaw chatrooms chat <chatroomId> --data '{"message":"What should our Q2 strategy be?"}' --json

# Remove an agent from the chatroom
swarmclaw chatrooms remove-member <chatroomId> --data '{"agentId":"<agentId>"}' --json
```

Other: `get`, `update`, `delete`, `react`, `pin`, `moderate`

### Schedules

Automate recurring agent work on a cron schedule.

```bash
# List schedules
swarmclaw schedules list --json

# Create a schedule (cron syntax)
swarmclaw schedules create --data '{"name":"Daily Report","agentId":"<id>","cron":"0 9 * * *","message":"Generate the daily summary report"}' --json

# Update schedule
swarmclaw schedules update <scheduleId> --data '{"enabled":false}' --json

# Trigger a schedule immediately
swarmclaw schedules run <scheduleId> --json

# Delete a schedule
swarmclaw schedules delete <scheduleId> --json
```

### Memory

Store and retrieve long-term agent memories for context persistence.

```bash
# List memories (searchable)
swarmclaw memory list --json
swarmclaw memory list --json --query q=pricing --query agentId=<id>

# Create a memory entry
swarmclaw memory create --data '{"agentId":"<id>","content":"Client prefers formal tone","type":"preference"}' --json

# Update a memory
swarmclaw memory update <memoryId> --data '{"content":"Updated content"}' --json

# Delete a memory
swarmclaw memory delete <memoryId> --json

# Analyse memory for