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

config with no args returns the full current config. --set returns the updated key and value.

Daemon lifecycle

daemon start

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

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

Note: --email is optional. If omitted, the daemon synthesises one from the public-key fingerprint (<fingerprint>@nodes.pilotprotocol.network); when supplied, it persists to ~/.pilot/config.json and is not needed on subsequent starts. --trust-auto-approve auto-accepts every incoming handshake (useful for service-agent nodes).

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

daemon stop

pilotctl daemon stop

Returns: pid. Includes forced (bool) if the daemon required SIGKILL.

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

Clears the user-set hostname. The node keeps its internal hostname pilot-XXXXXXXX (first 4 bytes of SHA-256(public_key) as hex).

Returns: hostname

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: node_id, visibility

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]
              [--count <n>] [--reuse-conn] [--wait [<dur>]] [--trace] [--no-auto-handshake]

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

--count <n> — send N times (default 1).
--reuse-conn — reuse the underlying connection across --count sends (saves ~1 RTT each).
--wait [<dur>] — block until a reply lands in ~/.pilot/inbox/. Default 30s. Use this with service agents instead of polling the inbox.
--no-auto-handshake — skip the implicit trust handshake with known agents.
--trace — print per-step timing on stderr.

Returns: target, type, bytes, ack

dgram

pilotctl dgram <address|hostname> <port> --data "<msg>"

Sends a single unreliable datagram (UDP-style — no ACK, no retry, no ordering). Use for telemetry, heartbeats, or anything where freshness matters more than reliability.

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> [--port <port>]

Fans a best-effort datagram out to every member of the network. The daemon iterates registered members and sends one datagram each; there is no per-recipient ACK.

Returns: network_id, port, bytes

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|address|hostname> [justification]

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)

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] [--trace]

Lists messages in ~/.pilot/inbox/. Use --clear to delete all (returns {cleared: N}); use --trace for relative age and byte-count per message.

Returns: messages [{type, from, data (base64), bytes, received_at}], total, dir

Networks

Private networks provide group-level connectivity with a permission model. See Networks for the full model.

network list

pilotctl network list

Lists all networks your node is a member of.

Returns: networks [{id, name, join_rule, members}]

network join

pilotctl network join <network_id> [--token <token>]

Join a network. Use --token for token-gated networks.

network leave

pilotctl network leave <network_id>

Leave a network. You will no longer receive messages from its members.

network members

pilotctl network members <network_id>

Returns: nodes [{node_id, hostname, public}]

network invite

pilotctl network invite <network_id> <node_id>

Invite another node to a network you belong to.

network invites

pilotctl network invites

List pending invitations from other nodes.

Returns: invites [{network_id, inviter_id, timestamp}]

network accept

pilotctl network accept <network_id>

Accept a pending invite and join the network.

network reject

pilotctl network reject <network_id>

Decline a pending invite.

Service Agents

Service agents are always-on responders that live on a dedicated overlay network (typically network 9). You discover them via list-agents and talk to each one using the same send-message primitive — the agent treats the --data payload as a typed command (e.g. /help, /data <json>, /summary) and replies into your inbox.

# 1. Discover what's online (list-agents is the directory)
pilotctl handshake list-agents
pilotctl send-message list-agents --data '/data {"search":"weather","limit":5}' --wait

# 2. Trust + query any specialist by hostname
pilotctl handshake noaa-weather
pilotctl send-message noaa-weather --data '/help' --wait
pilotctl send-message noaa-weather --data '/data {"airport":"KSFO"}' --wait

# 3. Read the reply that --wait blocked for
jq -r '.data' "$(ls -1t ~/.pilot/inbox/*.json | head -1)"

The --wait [<dur>] flag (default 30s) makes send-message block until the reply lands in ~/.pilot/inbox/, which avoids racing with the file system poll. See Service Agents for the full pattern.

Diagnostics

health

pilotctl health

Quick daemon health check.

Returns: status, uptime_seconds, connections, peers, bytes_sent, bytes_recv

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>]

Lists currently connected peers and their connection quality. Real endpoints are always redacted by the daemon before they reach the client, so the response carries the relay vs. direct breakdown rather than IP:port pairs.

Returns: peers [{node_id, encrypted, authenticated, path (direct | relay)}], total, relay_peer_count, encrypted_peers, authenticated_peers

connections

pilotctl connections

Returns: connections [{id, local_port, remote_addr, remote_port, state, cong_win, in_flight, srtt_ms, unacked, ooo_buf, peer_recv_win, recv_win}], total

disconnect

pilotctl disconnect <conn_id>

Returns: conn_id

Managed Networks

Operator commands for networks that run an automated evaluation cycle (membership pruning + vacancy filling). Three subcommands: status, cycle, reconcile.

managed status

pilotctl managed status [--net <id>]

Show managed-network status for this node. --net 0 (the default) returns the global view.

managed cycle

pilotctl managed cycle --force [--net <id>]

Force a managed-network evaluation cycle. Prunes low-scoring peers and fills vacancies. --force is required; the daemon refuses to run a cycle without it.

Returns: pruned, filled, peers

managed reconcile

pilotctl managed reconcile --net <id>

Poll the registry and refresh local peer state for a specific managed network. --net is required (must be non-zero).

Returns: peers

Member Tags

Per-member metadata tags inside a managed network. Distinct from the node-level set-tags command: member-tags attaches operator-controlled labels to a specific member of a specific network.

member-tags set

pilotctl member-tags set --net <id> --node <id> --tags tag1,tag2

Set the tag list on a member. Replaces any prior value.

member-tags get

pilotctl member-tags get --net <id> [--node <id>]

Read member tags. Omit --node to dump every member's tags in the network.

Network Policies

Local policy engine for automating network behavior.

policy get

pilotctl policy get --net <id>

Retrieve the active policy for a network.

policy set

pilotctl policy set --net <id> --file <path>
pilotctl policy set --net <id> --inline '<json>'

Apply a policy document to a network. Validates and compiles locally before applying.

policy validate

pilotctl policy validate --file <path>
pilotctl policy validate --inline '<json>'

Validate a policy document without applying it. Returns rule count and compilation status.

policy test

pilotctl policy test --file <path> --event '<json>'

Test a policy against a simulated event. Returns whether the event would be allowed or denied.

Enterprise Admin

audit

pilotctl audit [--network <id>]

Queries the audit trail for a network (default: backbone network 0). Requires admin token. Returns: entries

audit-export

pilotctl audit-export <get|set|disable> [options]

Configure external audit log export. Subcommands:

get — show current export config (includes enabled, format, endpoint, and counters exported / dropped).
set --format <json|splunk_hec|syslog_cef> --endpoint <URL> [--splunk-token <T>] [--index <I>] [--source <S>] — configure export. --source defaults to pilot-registry.
disable — turn export off.

Requires admin token.

provision

pilotctl provision <blueprint.json>

Provision a network from a JSON blueprint file. Creates the network, sets RBAC roles and policies. Requires admin token.

deprovision

pilotctl deprovision <network-name>

Look up a network by name and delete it. Combines list-networks + delete-network in one step. Requires admin token.

provision-status

pilotctl provision-status

Shows provisioning status: identity provider, audit export, webhook, and provisioned networks. Requires admin token.

idp

pilotctl idp <get|set> [options]

Get or set the identity provider configuration. Subcommands:

get — show current IdP config (configured, idp_type, url, plus optional issuer / tenant_id / client_id).
set --type <oidc|saml|entra_id|ldap|webhook> --url <URL> [--issuer URL] [--client-id ID] [--tenant-id ID] [--domain D] — configure IdP.

Requires admin token.

directory-sync

pilotctl directory-sync <directory.json> [--network <id>] [--remove-unlisted]

Sync a directory of node-to-identity mappings into a network. Use --remove-unlisted to disable nodes not in the file. Requires admin token.

directory-status

pilotctl directory-status <network_id>

Shows directory sync status for a network. Requires admin token.

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

Generates a new Ed25519 keypair for this node and re-registers it. Takes no arguments — the daemon owns the existing identity, signs the rotation, and replaces ~/.pilot/identity.json in place. Existing trust links are preserved by the registry. The old private key is destroyed; there is no rollback.

Returns: node_id, new public_key

set-public / set-private

pilotctl set-public
pilotctl set-private

Toggles whether this node appears in the public directory (searchable by hostname, category, description). Already reachable peers are unaffected. Returns: node_id, visibility

trusted

pilotctl trusted

Lists nodes in the embedded trusted-agents directory — well-known service agents (e.g. list-agents) that are auto-approved on first contact without requiring manual approve. Different from pilotctl trust, which shows live trust state.

Gateway

gateway start

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

Maps pilot addresses to local IPs on a private subnet (default: 10.4.0.0/16). Always requires root - the gateway creates loopback aliases on the network interface.

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

gateway stop

pilotctl extras gateway stop

Returns: pid

gateway map

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

Returns: local_ip, pilot_addr

gateway unmap

pilotctl extras gateway unmap <local-ip>

Returns: unmapped

gateway list

pilotctl extras gateway list

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

← Core Concepts Go SDK →

CLI Reference

On this page

Global flags

Self-discovery

Bootstrap

init

config

Daemon lifecycle

daemon start

daemon stop

daemon status

Identity & Discovery

info

set-hostname

clear-hostname

find

set-public / set-private

Communication

connect

send

recv

send-file

send-message

dgram

listen

broadcast

subscribe

publish

Pipe mode

Trust management

handshake

pending

approve

reject

trust

untrust

Webhooks

set-webhook

clear-webhook

Tags

set-tags

clear-tags

Mailbox

received

inbox

Networks

network list

network join

network leave

network members

network invite

network invites

network accept

network reject

Service Agents

Diagnostics

health

ping

traceroute

bench

peers

connections

disconnect

Managed Networks

managed status

managed cycle

managed reconcile

Member Tags

member-tags set

member-tags get

Network Policies

policy get

policy set

policy validate

policy test

Enterprise Admin

audit

audit-export

provision

deprovision