Swarmclaw 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:

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

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.

# 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.

# 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.

# 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.

# 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.

# 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.

# 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 dedup/prune candidates
swarmclaw memory maintenance --json

# Run the maintenance (dedupe/prune)
swarmclaw memory maintenance-run --json

Other:

get

graph

Goals

Hierarchical goal management — organization, team, project, agent, and task-level goals with parent-child chains.

# List all goals
swarmclaw goals list --json

# Create a goal
swarmclaw goals create --data '{"title":"Increase revenue 20%","level":"organization","description":"Q2 revenue target"}' --json

# Get goal details
swarmclaw goals get <goalId> --json

# Update a goal
swarmclaw goals update <goalId> --data '{"status":"in_progress"}' --json

# Delete a goal
swarmclaw goals delete <goalId> --json

Knowledge

Manage knowledge sources — manual text, files, and URLs that ground agent responses with citations.

# List all knowledge entries
swarmclaw knowledge list --json

# Search knowledge
swarmclaw knowledge list --json --query q=pricing

# Create a manual knowledge entry
swarmclaw knowledge create --data '{"title":"Pricing Policy","content":"Standard pricing is...","kind":"manual","tags":["pricing"]}' --json

# Upload a file as knowledge
swarmclaw knowledge upload ./docs/handbook.pdf --json

# Get full source detail (metadata + indexed chunks)
swarmclaw knowledge source-get <sourceId> --json

# List knowledge sources with summaries
swarmclaw knowledge sources --json

# Re-sync a file/URL source
swarmclaw knowledge source-sync <sourceId> --json

# Archive a source
swarmclaw knowledge source-archive <sourceId> --data '{"reason":"outdated"}' --json

# Restore an archived source
swarmclaw knowledge source-restore <sourceId> --json

# Mark a source as superseded by another
swarmclaw knowledge source-supersede <sourceId> --data '{"supersededBySourceId":"<newSourceId>"}' --json

# Get knowledge hygiene summary (stale, duplicate, broken sources)
swarmclaw knowledge hygiene --json

# Run hygiene maintenance (auto-sync stale, archive duplicates)
swarmclaw knowledge hygiene-run --json

Other:

get

update

delete

source-create

source-update

source-delete

Search

Global cross-resource search across agents, tasks, chats, schedules, webhooks, and skills.

swarmclaw search query --json --query q=pricing

System

System health, version, and usage information.

# Health check (lightweight, safe for polling)
swarmclaw system status --json

# Check current version and updates
swarmclaw system version --json

# View resource usage
swarmclaw system usage --json

More Commands

These groups are available but used less frequently by agents. Use

swarmclaw <group> --help

list

get

create

update

delete

start

stop

repair

health

doctor

incidents

reflections

estop

estop-set

guardian-restore

list

resolve

list

get

create

update

delete

trigger

history

list

get

create

update

delete

send

approve

transactions

balance-history

list

get

create

update

delete

configs

ollama

models

models-set

list

create

update

delete

health

list

get

create

delete

list

get

create

update

delete

list

create

clear

mark-read

delete

list

set

install

marketplace

settings-get

settings-set

builtins

list

get

create

update

delete

upload

sources

source-get

source-create

source-update

source-delete

source-archive

source-restore

source-supersede

source-sync

hygiene

hygiene-run

list

get

create

update

delete

import

list

promote

dismiss

delete

review-counts

list

draft

approve

reject

list

create

update

delete

heartbeat

list

export

import

get

update

list

get

events

list

--query entityType=

--query action=

status

start

stop

health-check

list

--query lines=200

--query level=INFO

clear

doctor

check-provider

list

get

create

update

delete

revisions

list

get

delete

delete-many

search

preview

install

discover

gateway-status

deploy-*

remote-*

skills

sync

Rules

1. Always verify an agent ID exists by running

   agents list

   before creating tasks for it.
2. Never pass the access key as a CLI argument in visible output — rely on the

   SWARMCLAW_ACCESS_KEY

   env var.
3. If the SwarmClaw instance is unreachable, run

   swarmclaw setup doctor --json

   and report the findings before retrying.
4. When the user says "dispatch work", "get X agent to do Y", or "assign this to", use

   tasks create

   to assign the work.
5. When the user asks "what's running", "agent status", or "what are my agents doing", combine output from

   agents list

   and

   chats list

   to give a full picture.
6. For complex multi-step orchestration, create individual tasks rather than chaining commands.
7. Prefer

   --json

   output mode for all commands. Use

   --raw

   only for legacy commands that don't support

   --json

   .
8. Do not run commands that modify or delete agents without explicit user confirmation.
9. Use

   system status

   for quick health checks — it's lightweight and safe for repeated polling.
10. Use

    search query --query q=<term>

    to discover resources across agents, tasks, chats, schedules, and skills.
11. The CLI group

    chats

    = "sessions" in the SwarmClaw UI. The legacy

    sessions

    alias is no longer available; always use

    chats

    .
12. Use

    autonomy estop-set

    to engage emergency stop across all autonomous agents when safety action is needed.

Examples

Dispatch work to another agent

User says: "Get my research agent to analyse competitor pricing"

swarmclaw agents list --json
# Find the research agent's ID from the output
swarmclaw tasks create --data '{"title":"Analyse competitor pricing","description":"Research and compare competitor pricing strategies, identify gaps and opportunities","agentId":"<research-agent-id>"}' --json

Then confirm the task was created and the agent will pick it up.

Check fleet status

User says: "What are all my agents doing right now?"

swarmclaw agents list --json
swarmclaw chats list --json
swarmclaw tasks list --json --query status=in_progress

Then summarize which agents are idle, which have active chats, and any tasks in progress.

Run diagnostics

User says: "Something seems wrong with SwarmClaw"

swarmclaw system status --json
swarmclaw setup doctor --json

Check the health summary first (fast), then run full diagnostics if issues are found.

Multi-agent chatroom collaboration

User says: "Get my strategy and research agents to brainstorm Q2 plans together"

swarmclaw agents list --json
# Identify the strategy and research agent IDs
swarmclaw chatrooms create --data '{"name":"Q2 Strategy Brainstorm"}' --json
swarmclaw chatrooms add-member <chatroomId> --data '{"agentId":"<strategy-agent-id>"}' --json
swarmclaw chatrooms add-member <chatroomId> --data '{"agentId":"<research-agent-id>"}' --json
swarmclaw chatrooms chat <chatroomId> --data '{"message":"Brainstorm our Q2 growth strategy. Consider market trends, competitor moves, and our current strengths."}' --json

Schedule recurring work

User says: "Have my reporting agent send a daily summary every morning at 9am"

swarmclaw agents list --json
# Find the reporting agent's ID
swarmclaw schedules create --data '{"name":"Daily Morning Summary","agentId":"<reporting-agent-id>","cron":"0 9 * * *","message":"Generate and send the daily summary report covering key metrics, alerts, and action items from the last 24 hours"}' --json

Emergency stop all autonomous agents

User says: "Stop everything now!"

swarmclaw autonomy estop-set --data '{"engaged":true}' --json

Then confirm the emergency stop is engaged and all autonomous execution has halted.

Set up a goal hierarchy

User says: "Create a Q2 revenue goal and link my sales agent's tasks to it"

swarmclaw goals create --data '{"title":"Increase Q2 revenue 20%","level":"organization","description":"Hit $1.2M ARR by end of Q2"}' --json
# Use the returned goalId to link agent tasks
swarmclaw tasks list --json --query agentId=<sales-agent-id>
swarmclaw tasks update <taskId> --data '{"goalId":"<goalId>"}' --json

Discovery

This skill covers the most-used commands. The full CLI has 50+ command groups. To explore:

swarmclaw --help                    # List all command groups
swarmclaw <group> --help            # List commands in a group
swarmclaw <group> <action> --help   # Show flags for a specific command