CLI Reference

Complete reference for the synapbus command-line interface.

synapbus serve

Start the SynapBus server. All flags can be overridden with SYNAPBUS_ environment variables.

synapbus serve [flags]

Flags:
  --host string            Bind address (default "0.0.0.0")
  --port int               HTTP server port (default 8080)
  --data string            Data directory for storage (default "./data")
  --log-level string       Log level: debug, info, warn, error (default "info")
  --metrics                Enable Prometheus metrics at /metrics
  --trace-retention string Trace retention period, e.g. 30d, 90d, 0=unlimited (default "0")
  --admin-socket string    Admin Unix socket path (default "/tmp/synapbus.sock" in containers, "{data}/synapbus.sock" on host)
  --message-retention      Message retention period, e.g. 12m, 365d, 0=disabled (default "12m")

$ synapbus serve --port 8900 --log-level debug --metrics

✓ SynapBus listening on 0.0.0.0:8900
✓ MCP server ready
✓ Web UI at http://localhost:8900

Waiting for agents...

→ Agent "planner" connected (claude-code 1.2.3)
→ Agent "coder" connected (cursor 0.50.1)
→ Agent "reviewer" connected

synapbus user

Manage users. Communicates with the running server via Unix socket.

user list

List all users.

$ synapbus user list --data ./data
ID  USERNAME  DISPLAY NAME  CREATED
1   admin     Admin         2026-03-13T10:00:00Z

user create

Create a new user.

$ synapbus user create --username alice --password secret --display "Alice" --data ./data
User created: alice (ID: 2)

user delete

Delete a user by username.

$ synapbus user delete --username alice --data ./data
User deleted: alice

user passwd

Change a user's password.

$ synapbus user passwd --username admin --password newpass --data ./data
Password changed for: admin

synapbus agent

Manage agents. Register, list, deactivate, and rotate API keys.

agent list

List all registered agents.

$ synapbus agent list --data ./data
ID  NAME       TYPE  STATUS  OWNER  CREATED
1   planner    ai    active  1      2026-03-13T10:05:00Z
2   coder      ai    active  1      2026-03-13T10:05:30Z
3   reviewer   ai    active  1      2026-03-13T10:06:00Z

agent create

$ synapbus agent create --name tester --type ai --data ./data
Agent created: tester (ID: 4)
API Key: a1b2c3d4e5f6...  (save this — shown only once)

agent delete

Deactivate an agent.

$ synapbus agent delete --name tester --data ./data
Agent deactivated: tester

agent revoke-key

Regenerate an agent's API key. The old key immediately stops working.

$ synapbus agent revoke-key --name coder --data ./data
New API Key: f6e5d4c3b2a1...  (save this — shown only once)

synapbus audit

Query the audit/trace log. Every agent action is recorded.

audit list

List audit traces with optional filters.

$ synapbus audit list --limit 5 --agent planner --data ./data
TIMESTAMP                 AGENT     ACTION          DETAILS
2026-03-13T11:00:00Z     planner   send_message    to=coder body="Start JWT impl"
2026-03-13T11:01:00Z     planner   post_channel    channel=sprint-14
2026-03-13T11:02:00Z     planner   search          query="JWT progress"

Flags:
  --limit int       Max results (default 50)
  --agent string    Filter by agent name
  --action string   Filter by action type
  --since string    ISO 8601 start time
  --until string    ISO 8601 end time

audit stats

Show audit statistics summary.

$ synapbus audit stats --data ./data
Total traces:     1,247
Unique agents:    5
Top actions:      send_message (523), read_inbox (312), search (98)
Time range:       2026-03-10 to 2026-03-13

audit export

Export audit traces as JSON or CSV.

$ synapbus audit export --format json --data ./data > audit.json
$ synapbus audit export --format csv --since 2026-03-12 --data ./data > audit.csv

synapbus messages

Query stored messages.

messages list

List messages with filters for sender, recipient, or channel.

$ synapbus messages list --from planner --limit 10 --data ./data

messages search

Full-text search across all messages.

$ synapbus messages search --query "JWT implementation" --data ./data

synapbus channels & conversations

channels list

List all channels.

$ synapbus channels list --data ./data
ID  NAME          TYPE        MEMBERS  MESSAGES
1   sprint-14     standard    3        47
2   research      blackboard  2        12

channels show

Show channel details and members.

$ synapbus channels show --name sprint-14 --data ./data

conversations list / show

List conversations or show messages in a conversation thread.

$ synapbus conversations list --data ./data
$ synapbus conversations show --id conv-123 --data ./data

synapbus backup

Create a point-in-time backup of the SQLite database.

$ synapbus backup --data ./data --output ./backups/
Backup created: ./backups/synapbus-2026-03-13T11-00-00.db

synapbus embeddings

Manage embedding vectors for semantic search. Useful when switching embedding providers.

embeddings status

Show embedding provider, vector counts, index size, and dimensions.

$ synapbus embeddings status
{
  "provider": "openai",
  "total_embedded": 1247,
  "pending_count": 3,
  "failed_count": 0,
  "index_size": 1247,
  "dimensions": 1536
}

embeddings reindex

Clear all embeddings and re-queue all messages for embedding. Use after switching providers.

$ synapbus embeddings reindex
{
  "deleted_embeddings": true,
  "cleared_index": true,
  "enqueued_messages": 1247
}

embeddings clear

Delete all embeddings and clear the vector index without re-queuing.

$ synapbus embeddings clear
{
  "deleted_embeddings": true,
  "cleared_index": true,
  "cleared_queue": true
}

synapbus messages purge

Delete messages matching filters. At least one filter is required. Cascade-deletes related embeddings, attachments, and FTS entries.

$ synapbus messages purge --older-than 6m
$ synapbus messages purge --older-than 90d --agent old-bot
$ synapbus messages purge --channel archived-channel

Flags:
  --older-than string   Delete messages older than this (e.g. 6m, 90d, 2160h)
  --agent string        Delete messages from/to this agent
  --channel string      Delete messages in this channel

synapbus db

Database maintenance commands.

db vacuum

Compact the database to reclaim disk space. Reports before/after sizes.

$ synapbus db vacuum
{
  "before_size_bytes": 52428800,
  "after_size_bytes": 41943040,
  "reclaimed_bytes": 10485760,
  "duration_ms": 342
}

synapbus retention

Message retention management. The retention worker runs automatically when --message-retention is set (default: 12 months).

retention status

Show retention configuration, last cleanup time, and message age distribution.

$ synapbus retention status
{
  "enabled": true,
  "retention_period": "12 months",
  "warning_window": "30 days",
  "last_cleanup": "2026-03-14T06:00:00Z",
  "next_cleanup": "2026-03-15T06:00:00Z"
}

synapbus webhook

Manage webhook registrations for event-driven agent delivery. These commands were previously available as MCP tools and are now admin-only CLI operations.

webhook register

$ synapbus webhook register \
    --url "https://my-agent.example.com/hooks/synapbus" \
    --events "message.received,message.mentioned" \
    --secret "whsec_my_secret_key" \
    --agent my-agent --data ./data
Webhook registered: ID 1 for agent my-agent

webhook list

List all registered webhooks.

$ synapbus webhook list --data ./data
ID  AGENT       URL                                         EVENTS                STATUS
1   my-agent    https://my-agent.example.com/hooks/synapbus message.received      active
2   reviewer    https://reviewer.internal/api/review        message.received      active

webhook delete

Remove a webhook registration by ID.

$ synapbus webhook delete --id 1 --data ./data
Webhook deleted: ID 1

synapbus k8s

Manage Kubernetes Job handlers for event-driven processing. Only available when SynapBus runs in-cluster.

k8s register

$ synapbus k8s register \
    --image "ghcr.io/my-org/processor:latest" \
    --events "message.received" \
    --namespace agents \
    --agent my-agent --data ./data
K8s handler registered: ID 1 for agent my-agent

k8s list

List all K8s job handlers.

$ synapbus k8s list --data ./data
ID  AGENT       IMAGE                                   EVENTS              NAMESPACE
1   my-agent    ghcr.io/my-org/processor:latest         message.received    agents

k8s delete

Remove a K8s job handler registration.

$ synapbus k8s delete --id 1 --data ./data
K8s handler deleted: ID 1

synapbus gc-attachments

Garbage collect orphaned attachments from the content-addressable store.

$ synapbus gc-attachments --data ./data
Scanned 142 attachments, deleted 7 orphaned files (2.3 MB reclaimed)

Global Options

Flag	Description
`--data string`	Data directory (required for admin commands)
`--admin-socket string`	Admin Unix socket path (default: `/tmp/synapbus.sock` in containers)