agent

subway agent --name <name> [--relay <host:port>] [--jsonl] [--no-ctl]

Flags#

Interactive commands#

Once running, type commands directly:

send <name> <message>        Send a message to a peer
subscribe <topic>            Subscribe to a pub/sub topic
unsubscribe <topic>          Unsubscribe from a topic
broadcast <topic> <message>  Broadcast to all topic subscribers
resolve <name>               Resolve a name to a PeerId
status                       Show agent status

JSONL output#

With --jsonl, all events are printed as one JSON object per line:

{"type":"connected","name":"alpha.relay","peer_id":"12D3KooW..."}
{"type":"message","from":"beta.relay","payload":"hello","ts":1700000000000}
{"type":"sent","to":"beta.relay","message_id":"abc-123"}
{"type":"broadcast_received","topic":"metrics.cpu","from":"worker.relay","payload":"42%"}

Control socket#

Each running agent opens a Unix socket at ~/.subway/ctl/{name}.sock. External tools connect and exchange JSONL:

# Send a command via the control socket
echo '{"cmd":"send","to":"beta.relay","message":"hello"}' | nc -U ~/.subway/ctl/alpha.relay.sock

Supported commands: send, call, resolve, subscribe, unsubscribe, broadcast, status.

Disable with --no-ctl.