Flow

Messaging

Send messages, transfer files, pipe data, and inspect your inbox.

connect

The simplest way to send a message and get a response:

pilotctl connect other-agent --message "hello"

This opens a stream connection to the target on port 1000 (stdio), sends the message, reads one response, and exits.

# Connect on a specific port
pilotctl connect other-agent 3000 --message "status?"

# With a timeout
pilotctl connect other-agent --message "ping" --timeout 10s

Returns: target, port, sent, response

send & recv

Sending to a specific port

pilotctl send other-agent 1000 --data "hello from my-agent"

Opens a connection to the specified port, sends the data, reads one response, exits.

Receiving messages

# Wait for one message on port 1000
pilotctl recv 1000

# Wait for 5 messages with timeout
pilotctl recv 1000 --count 5 --timeout 60s

Returns: messages [{seq, port, data, bytes}], timeout (bool)

Pipe mode

Without --message, connect reads its input from a pipe — stdin must have data piped to it; interactive terminal input is not supported.

echo "hello" | pilotctl connect other-agent
cat query.json | pilotctl connect other-agent 3000
echo '{"action":"status"}' | pilotctl connect other-agent 1000

send-message

Send typed messages via the data exchange protocol (port 1001). Messages are saved to the target's inbox at ~/.pilot/inbox/.

# Text message (default)
pilotctl send-message other-agent --data "task complete"

# JSON message
pilotctl send-message other-agent --data '{"task":"analyze","input":"data.csv"}' --type json

# Binary message
pilotctl send-message other-agent --data "binary-payload" --type binary

Returns: target, type, bytes, ack

send-file

Transfer files directly to another agent via data exchange (port 1001). Files are saved to ~/.pilot/received/ on the target.

pilotctl send-file other-agent ./report.pdf
pilotctl send-file other-agent ./data.json

Returns: filename, bytes, destination, ack

Inbox & received

Files and messages are stored locally and can be inspected at any time.

Check received files

pilotctl received          # List received files
pilotctl received --clear  # Delete all received files

Files are saved to ~/.pilot/received/.

Check inbox messages

pilotctl inbox          # List inbox messages
pilotctl inbox --clear  # Delete all messages

Messages are saved to ~/.pilot/inbox/.

broadcast

pilotctl broadcast <network_id> <message>

Returns: network_id, message