agentmatrix-cli

Command-line interface for AgentMatrix multi-agent orchestration service.

Install

npm install -g agentmatrix-cli

Configuration

agentmatrix config set server http://localhost:8088
agentmatrix config set apikey csp_your_api_key
agentmatrix config list

Config is stored in ~/.agentmatrix/config.json. You can also use --server and --apikey flags on any command to override.

Quick Start

# Create a team
agentmatrix team create --name my-team

# Add a Claude agent
agentmatrix agent add --team $TEAM_ID --id coder --type claude --model claude-opus-4-5

# Create a thread
agentmatrix thread create $TEAM_ID

# Send a message
agentmatrix message send $TEAM_ID $THREAD_ID coder "Hello, please help me review this code."

# Upload an attachment and send with it
agentmatrix attachment upload $TEAM_ID ./report.pdf
agentmatrix message send $TEAM_ID $THREAD_ID coder "Review this file" --attachment-ids $ATT_ID

# Broadcast to all agents
agentmatrix message broadcast $TEAM_ID $THREAD_ID "Team sync: what's your status?"

Global Options

| Flag | Description | |------|-------------| | --server <url> | Server URL (overrides config) | | --apikey <key> | API key (overrides config) | | --json | Output as JSON instead of formatted tables |

Commands

config

agentmatrix config set <key> <value>    # Set config value (server, apikey)
agentmatrix config get <key>            # Get config value
agentmatrix config list                 # List all config values

health

agentmatrix health                      # Check service health

team

agentmatrix team create --name <name> [--metadata <json>]
agentmatrix team list
agentmatrix team get <teamId>
agentmatrix team destroy <teamId>

agent

agentmatrix agent add --team <teamId> --id <agentId> [options]
  --type <type>              Agent type: claude, codex, openclaw, pi (default: claude)
  --template <templateId>    E2B template ID
  --model <model>            Model ID
  --prompt <text>            System prompt
  --allowed-tools <tools>    Comma-separated tool names
  --mcp-servers <json>       MCP server specs as JSON array
  --files <json>             File specs as JSON array
  --skills <ids>             Comma-separated skill IDs
  --timeout <seconds>        Sandbox timeout
  --env <json>               Environment variables as JSON
  --metadata <json>          Metadata as JSON

agentmatrix agent list --team <teamId>
agentmatrix agent get <agentId> --team <teamId>

agentmatrix agent update <agentId> --team <teamId> [options]
  --model <model>            Model ID
  --prompt <text>            System prompt
  --allowed-tools <tools>    Comma-separated tool names
  --env <json>               Environment variables as JSON
  --mcp-servers <json>       MCP server specs as JSON array
  --files <json>             File specs as JSON array
  --skills <ids>             Comma-separated skill IDs

agentmatrix agent remove <agentId> --team <teamId>

thread

agentmatrix thread create <teamId> [--metadata <json>]
agentmatrix thread list <teamId> [--limit <n>] [--offset <n>]
agentmatrix thread get <teamId> <threadId>
agentmatrix thread archive <teamId> <threadId>

message

agentmatrix message send <teamId> <threadId> <agentId> <text> [options]
  --timeout <ms>             Response timeout in milliseconds
  --async                    Send asynchronously (fire-and-forget)
  --request-id <id>          Custom correlation ID
  --attachment-ids <ids>     Comma-separated attachment IDs

agentmatrix message broadcast <teamId> <threadId> <text> [options]
  --timeout <ms>
  --async
  --request-id <id>
  --attachment-ids <ids>

agentmatrix message multicast <teamId> <threadId> <text> --agents <ids> [options]
  --agents <ids>             Comma-separated agent IDs (required)
  --timeout <ms>
  --async
  --request-id <id>
  --attachment-ids <ids>

agentmatrix message history <teamId> <threadId> [--limit <n>] [--offset <n>]

attachment

agentmatrix attachment upload <teamId> <filePath> [--name <filename>] [--content-type <type>]
agentmatrix attachment list <teamId>
agentmatrix attachment download-url <teamId> <attachmentId>
agentmatrix attachment delete <teamId> <attachmentId>

artifact

agentmatrix artifact list <teamId> <threadId> [--dir <subdir>]
agentmatrix artifact read <teamId> <threadId> <path>
agentmatrix artifact write <teamId> <threadId> <path> --content <text> | --file <filePath> [--encoding <utf-8|base64>]
agentmatrix artifact delete <teamId> <threadId> <path>
agentmatrix artifact archive <teamId> <threadId> [--output <file>]

skill

agentmatrix skill create <teamId> --name <name> --desc <description> [--file <zipPath>]
agentmatrix skill list <teamId>
agentmatrix skill get <teamId> <skillId>
agentmatrix skill update <teamId> <skillId> [--name <name>] [--desc <description>] [--file <zipPath>]
agentmatrix skill delete <teamId> <skillId>

volume

agentmatrix volume upload <volumeId> <filePath> [--name <filename>]
agentmatrix volume upload-url <volumeId> <filename>
agentmatrix volume sync <volumeId> <r2Key>

apikey

agentmatrix apikey create --name <teamName>
agentmatrix apikey list
agentmatrix apikey revoke <id>

admin

agentmatrix admin refresh-env           # Refresh env vars across all active agents

License

MIT