CLI Reference: Message Bus (bus)
Commands for the publish-subscribe message bus.
The message bus enables asynchronous agent-to-agent communication via topics. Agents publish messages to topics; other agents subscribe to topic patterns and receive messages via their mailbox.
ash bus publish
Publish a message to a topic.
ash bus publish <agent-id> <topic> <payload-json>
| Argument | Description |
|---|---|
agent-id | Publishing agent ID (must have bus.publish) |
topic | Topic string (e.g. tasks/created, results/batch-42) |
payload-json | JSON payload |
Example:
ash bus publish <agent-id> tasks/new '{"task_id": "abc", "priority": 1}'
ash bus subscribe
Subscribe an agent to a topic pattern.
ash bus subscribe <agent-id> <topic-pattern>
| Argument | Description |
|---|---|
agent-id | Subscribing agent ID (must have bus.subscribe) |
topic-pattern | Glob pattern matching topics (e.g. tasks/*, results/**) |
Example:
ash bus subscribe <agent-id> "tasks/*"
Messages published to any topic matching the pattern are delivered to the agent's mailbox.
ash bus unsubscribe
Remove a subscription.
ash bus unsubscribe <agent-id> <topic-pattern>
The exact topic-pattern string must match a previously registered subscription.
ash bus poll
Drain pending messages from an agent's mailbox.
ash bus poll <agent-id>
Returns all queued messages that have not yet been consumed by the agent. Messages are returned in delivery order.
Output per message:
| Field | Description |
|---|---|
topic | The topic the message was published to |
payload | JSON payload |
published_at | RFC3339 timestamp |
from_agent_id | Publisher's agent ID |
Topic naming conventions
- Use
/-separated hierarchical names:domain/entity/event - Wildcards in subscriptions:
*matches one segment,**matches multiple - Examples:
tasks/created,metrics/cpu/**,alerts/*