CLI Reference

The swarmlord CLI deploys agents from config files. Define your agent in swarmlord.jsonc, write instructions in AGENTS.md, add skills and workspace files, then deploy with a single command.

Install

The CLI ships with the swarmlord npm package:

npm (global)

npm install -g swarmlord

npx (no install)

npx swarmlord <command>

bun

bunx swarmlord <command>

Project Structure

my-agent/
├── swarmlord.jsonc          # Agent configuration
├── AGENTS.md                # Always-loaded instructions
├── skills/                  # On-demand knowledge
│   ├── troubleshooting/
│   │   └── SKILL.md
│   └── data-analysis/
│       └── SKILL.md
├── files/                   # Pre-loaded workspace files
│   ├── data/
│   │   └── products.csv
│   └── templates/
│       └── report.html
└── .gitignore

Local path	Deployed to	Purpose
AGENTS.md	/workspace/AGENTS.md	Always-loaded system instructions
skills/<name>/SKILL.md	/workspace/.swarmlord/skills/<name>/SKILL.md	On-demand knowledge via the skill tool
files/*	/workspace/*	Pre-loaded workspace files

Config Format

swarmlord.jsonc is the agent configuration file. JSONC (JSON with comments) is supported.

{
    "$schema": "https://swarmlord.ai/config.json",
    "name": "support-bot",
    "description": "Handles customer support in Slack",
    "model": "anthropic/claude-sonnet-4-20250514",

    // Activation: exactly one of trigger or schedule
    "trigger": {
        "provider": "slack",
        "events": ["message", "app_mention"],
    },

    // Where results go (trigger-only)
    "outputs": [{ "provider": "slack", "action": "thread_reply" }],

    // Tool access
    "tools": {
        "bash": true,
        "websearch": true,
        "browser": false,
    },

    // Permissions
    "permission": { "*": "allow" },

    // Optional: custom prompt template with {{variable}} substitution
    "promptTemplate": "A user said: {{text}}\n\nRespond helpfully.",
}

Fields

Field	Type	Required	Description
name	string	Yes	Agent name. Lowercase alphanumeric with hyphens, 1-64 chars.
description	string	No	Human-readable description.
model	string	No	Model identifier (e.g. anthropic/claude-sonnet-4-20250514).
trigger	object	One of	Webhook-based activation.
trigger.provider	string	Yes	One of: slack, github, linear, generic.
trigger.events	string[]	No	Event types to listen for.
schedule	object	One of	Cron-based activation.
schedule.cron	string	Yes	Cron expression (e.g. 0 9 * * 1-5).
schedule.prompt	string	Yes	Prompt sent each time the cron fires.
outputs	array	No	Where results go. Only valid with trigger.
tools	object	No	Tool enable/disable map. Unmentioned tools keep defaults.
permission	object	No	Permission rules. Keys are tool names or *. Values: allow, deny, ask.
promptTemplate	string	No	Template for incoming events. Uses substitution from the trigger payload. If omitted, a provider-specific default is used.
instructions	string[]	No	Additional local files to append to AGENTS.md at deploy time.

Validation Rules

• name must match ^[a-z0-9]+(-[a-z0-9]+)*$
• Exactly one of trigger or schedule must be set
• outputs is only valid when trigger is set
• permission values must be "allow", "deny", or "ask"

Schedule Example

{
    "$schema": "https://swarmlord.ai/config.json",
    "name": "daily-digest",
    "model": "google/gemini-3-flash-preview",
    "schedule": {
        "cron": "0 9 * * 1-5",
        "prompt": "Check for new GitHub issues labeled 'bug' and summarize them.",
    },
    "tools": {
        "bash": true,
        "websearch": true,
        "browser": false,
    },
    "permission": { "*": "allow" },
}

Instructions (AGENTS.md)

AGENTS.md is always loaded into the agent's context at the start of every session. Use it for:

• System prompt and persona
• Behavioral guidelines
• Domain knowledge that applies to every conversation
• References to skills the agent should load for specific topics

# Support Bot

You are a support agent for Acme Corp.

## Guidelines

- Be concise and friendly
- Load the relevant skill before answering domain-specific questions
- Always check workspace files in /workspace/data/ for reference data
- If you can't resolve an issue, escalate with a clear summary

## Available Skills

- **troubleshooting** — use when diagnosing customer issues
- **data-analysis** — use when working with CSV/JSON data

Additional Instruction Files

Use the instructions array in swarmlord.jsonc to append local files to AGENTS.md at deploy time:

{
    "instructions": ["docs/api-reference.md", "docs/faq.md"],
}

These files are resolved relative to the project directory and concatenated onto AGENTS.md in the workspace bundle.

Skills

Skills are on-demand knowledge documents. Unlike AGENTS.md (always loaded), skills are only loaded when the agent calls the skill tool — keeping context lean until specialized knowledge is needed.

Creating a Skill

Each skill lives in skills/<name>/SKILL.md with required YAML frontmatter:

---
name: troubleshooting
description: Step-by-step playbook for diagnosing common customer issues
---

# Troubleshooting Playbook

## Network Issues

1. Ask for the customer's region
2. Check if the issue is region-specific
   ...

How Skills Work

1. At deploy time, skill names and descriptions are stored as metadata.
2. The skill tool appears in the agent's tool list with all available skill names.
3. When the agent calls skill({ name: "troubleshooting" }), the full SKILL.md content is loaded from the sandbox.
4. The agent now has that specialized knowledge in its context.

This means the agent sees a lightweight menu of skills (names + descriptions) but only pays the token cost of loading a skill when it's actually needed.

Validation

• The name in the YAML frontmatter must match the directory name
• description is required, max 1024 characters
• The directory name must be lowercase alphanumeric with hyphens

Workspace Files

Everything in the files/ directory is pre-loaded into the agent's sandbox at /workspace/:

files/
├── data/
│   └── sales.csv         → /workspace/data/sales.csv
├── templates/
│   └── report.html       → /workspace/templates/report.html
└── config.json           → /workspace/config.json

Use workspace files for reference data, templates, code to review, or any files the agent needs to work with.

Commands

swarmlord init

Scaffold a new agent project.

swarmlord init [directory] [options]

Option	Description
-n, --name <name>	Agent name (default: my-agent)
-t, --trigger <provider>	Trigger provider: slack, github, linear, generic
-s, --schedule <cron>	Cron expression for scheduled agents
-p, --prompt <prompt>	Schedule prompt (required with --schedule)
-m, --model <model>	Model identifier (default: google/gemini-3-flash-preview)
-y, --yes	Skip interactive prompts, use defaults

# Interactive
swarmlord init

# Non-interactive trigger agent
swarmlord init my-bot -n my-bot -t slack -y

# Non-interactive scheduled agent
swarmlord init daily-check -n daily-check -s "0 9 * * 1-5" -p "Check for new issues" -y

swarmlord deploy

Bundle and deploy agents to swarmlord cloud.

swarmlord deploy [name]

Detects agent directories automatically:

• If swarmlord.jsonc is in the current directory: deploys that single agent.
• If subdirectories contain swarmlord.jsonc: deploys all of them.
• Pass a name to deploy a specific subdirectory only.

On success, prints the webhook URL (for triggers) or schedule ID (for cron agents) and writes state to .swarmlord.

swarmlord run

Test an agent locally without deploying.

swarmlord run "<prompt>"

Bundles the current directory, creates an ephemeral cloud session, seeds the workspace, sends the prompt, and streams the response to your terminal. The session is cleaned up after completion.

swarmlord run "List all files in your workspace"
swarmlord run "Load the data-analysis skill, then analyze data/sales.csv"
swarmlord run "Review sample-app.ts for security issues"

swarmlord auth

Manage authentication.

swarmlord auth login    # Store API key
swarmlord auth logout   # Remove stored key

The CLI resolves API keys in order: SWARMLORD_API_KEY env var → stored auth file (~/.config/swarmlord/auth.json).

swarmlord list

List all deployed agents.

swarmlord list

swarmlord status

Show detailed status for a deployed agent.

swarmlord status <name>

swarmlord logs

Show recent sessions for a deployed agent.

swarmlord logs <name>

swarmlord pause / swarmlord resume

Disable or re-enable a deployed agent's trigger or schedule.

swarmlord pause <name>
swarmlord resume <name>

swarmlord destroy

Delete a deployed agent and clean up cloud resources.

swarmlord destroy <name> [-y]

Removes the D1 row, R2 workspace bundle, and local .swarmlord state entry.

Multi-Agent Repos

A single repo can contain multiple agents. Place each in its own subdirectory:

my-agents/
├── support-bot/
│   ├── swarmlord.jsonc
│   ├── AGENTS.md
│   └── skills/
├── daily-digest/
│   ├── swarmlord.jsonc
│   └── AGENTS.md
└── code-reviewer/
    ├── swarmlord.jsonc
    ├── AGENTS.md
    └── skills/

swarmlord deploy                # deploy all agents
swarmlord deploy support-bot    # deploy just one

Each agent gets its own entry in the .swarmlord state file.

Dev Loop

The recommended workflow:

1. swarmlord init — scaffold once
2. Edit AGENTS.md, skills/, files/
3. swarmlord run "test prompt" — test locally, see streamed output
4. Iterate — repeat steps 2-3 until the agent behaves well
5. swarmlord deploy — push to production
6. swarmlord logs — monitor live sessions