CLI Reference

Complete reference for pilotctl. All commands support --json for structured output.

Global flags

pilotctl --json <command> [args...]

Use --json with any command for structured output:

• Success: {"status":"ok","data":{...}}
• Error: {"status":"error","code":"...","message":"...","hint":"..."}

Self-discovery

pilotctl --json context

Returns the full command schema — use this to discover capabilities at runtime.

Bootstrap

init

pilotctl init --registry <addr> --beacon <addr> [--hostname <name>] [--socket <path>]

Creates ~/.pilot/config.json with registry, beacon, socket, and hostname settings.

Returns: config_path, registry, beacon, socket, hostname

config

pilotctl config                          # Show current config
pilotctl config --set registry=host:9000  # Update a key

Returns: current configuration as JSON.

Daemon lifecycle

daemon start

pilotctl daemon start [--registry <addr>] [--beacon <addr>] [--listen <addr>]
  [--identity <path>] [--owner <owner>] [--hostname <name>] [--public]
  [--no-encrypt] [--foreground] [--log-level <level>] [--log-format <fmt>]
  [--socket <path>] [--config <path>] [--webhook <url>]

Starts as a background process. Blocks until registered, prints status, then exits. Use --foreground to run in the current process.

Returns: node_id, address, pid, socket, hostname, log_file

daemon stop

pilotctl daemon stop

Returns: pid, forced (bool)

daemon status

pilotctl daemon status [--check]

--check mode: silent, exits 0 if responsive, 1 otherwise.

Returns: running, responsive, pid, pid_file, socket, node_id, address, hostname, uptime_secs, peers, connections

Identity & Discovery

info

pilotctl info

Returns: node_id, address, hostname, uptime_secs, connections, ports, peers, encrypt, bytes_sent, bytes_recv, per-connection stats, peer list with encryption status.

set-hostname

pilotctl set-hostname <name>

Names must be lowercase alphanumeric with hyphens, 1-63 characters.

Returns: hostname, node_id

clear-hostname

pilotctl clear-hostname

Returns: hostname, node_id

find

pilotctl find <hostname>

Discovers a node by hostname. Requires mutual trust.

Returns: hostname, node_id, address, public

set-public / set-private

pilotctl set-public      # Make this node visible to all
pilotctl set-private     # Hide this node (default)

Routes through the daemon (signs the request). Returns: status

Communication

connect

pilotctl connect <address|hostname> [port] --message "<msg>" [--timeout <dur>]

Dials the target, sends the message, reads one response, exits. Default port: 1000 (stdio).

Returns: target, port, sent, response

send

pilotctl send <address|hostname> <port> --data "<msg>" [--timeout <dur>]

Returns: target, port, sent, response

recv

pilotctl recv <port> [--count <n>] [--timeout <dur>]

Listens on a port, accepts incoming connections, collects messages. Default count: 1.

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

send-file

pilotctl send-file <address|hostname> <filepath>

Sends via data exchange (port 1001). Saved to ~/.pilot/received/ on the target.

Returns: filename, bytes, destination, ack

send-message

pilotctl send-message <address|hostname> --data "<text>" [--type text|json|binary]

Sends a typed message via data exchange (port 1001). Default type: text.

Returns: target, type, bytes, ack

listen

pilotctl listen <port> [--count <n>] [--timeout <dur>]

Listens for datagrams. Without --count: streams NDJSON indefinitely.

Returns: messages [{src_addr, src_port, data, bytes}], timeout (bool)

broadcast

pilotctl broadcast <network_id> <message>

Not yet available — custom networks are in development. Returns: network_id, message

subscribe

pilotctl subscribe <address|hostname> <topic> [--count <n>] [--timeout <dur>]

Subscribes to event stream (port 1002). Use * for all topics. Without --count: streams NDJSON.

Returns: events [{topic, data, bytes}], timeout (bool)

publish

pilotctl publish <address|hostname> <topic> --data "<message>"

Returns: target, topic, bytes

Pipe mode

echo "hello" | pilotctl connect <address|hostname> [port] [--timeout <dur>]

Without --message: reads from stdin (piped), sends it, reads one response.

Trust management

handshake

pilotctl handshake <node_id|hostname> "reason for connecting"

Returns: status, node_id

pending

pilotctl pending

Pending requests persist across daemon restarts.

Returns: pending [{node_id, justification, received_at}]

approve

pilotctl approve <node_id>

Returns: status, node_id

reject

pilotctl reject <node_id> "reason"

Returns: status, node_id

trust

pilotctl trust

Returns: trusted [{node_id, mutual, network, approved_at}]

untrust

pilotctl untrust <node_id>

Returns: node_id

Webhooks

set-webhook

pilotctl set-webhook <url>

Persists to config and applies immediately to a running daemon.

Returns: webhook, applied (bool)

clear-webhook

pilotctl clear-webhook

Returns: webhook, applied (bool)

Tags

set-tags

pilotctl set-tags <tag1> [tag2] [tag3]

Maximum 3 tags. Lowercase alphanumeric + hyphens, 1-32 characters each.

Returns: node_id, tags

clear-tags

pilotctl clear-tags

Returns: tags (empty array)

Mailbox

received

pilotctl received [--clear]

Lists files in ~/.pilot/received/. Use --clear to delete all.

Returns: files [{name, bytes, modified, path}], total, dir

inbox

pilotctl inbox [--clear]

Lists messages in ~/.pilot/inbox/. Use --clear to delete all.

Returns: messages [{type, from, data, received_at}], total, dir

Diagnostics

ping

pilotctl ping <address|hostname> [--count <n>] [--timeout <dur>]

Sends echo probes (port 7). Default: 4 pings.

Returns: target, results [{seq, bytes, rtt_ms, error}], timeout (bool)

traceroute

pilotctl traceroute <address> [--timeout <dur>]

Returns: target, setup_ms, rtt_samples [{rtt_ms, bytes}]

bench

pilotctl bench <address|hostname> [size_mb] [--timeout <dur>]

Throughput benchmark via echo port. Default: 1 MB.

Returns: target, sent_bytes, recv_bytes, send_duration_ms, total_duration_ms, send_mbps, total_mbps

peers

pilotctl peers [--search <query>]

Returns: peers [{node_id, endpoint, encrypted, authenticated}], total

connections

pilotctl connections

Returns: connections [{id, local_port, remote_addr, remote_port, state, bytes/segments/retransmissions/SACK stats}], total

disconnect

pilotctl disconnect <conn_id>

Returns: conn_id

Registry

register

pilotctl register [listen_addr]

Returns: node_id, address, public_key

lookup

pilotctl lookup <node_id>

Returns: node_id, address, real_addr, public, hostname

deregister

pilotctl deregister

Routes through daemon (signed). Returns: status

rotate-key

pilotctl rotate-key <node_id> <owner>

Returns: node_id, new public_key

Gateway

gateway start

pilotctl gateway start [--subnet <cidr>] [--ports <list>] [<pilot-addr>...]

Maps pilot addresses to local IPs on a private subnet (default: 10.4.0.0/16). Requires root for ports below 1024.

Returns: pid, subnet, mappings [{local_ip, pilot_addr}]

gateway stop

pilotctl gateway stop

Returns: pid

gateway map

pilotctl gateway map <pilot-addr> [local-ip]

Returns: local_ip, pilot_addr

gateway unmap

pilotctl gateway unmap <local-ip>

Returns: unmapped

gateway list

pilotctl gateway list

Returns: mappings [{local_ip, pilot_addr}], total