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 required on first registration. It is saved to ~/.pilot/config.json and not needed on subsequent starts.

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

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]

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 (WIP — not yet available)

pilotctl broadcast <network_id> <message>

Will send a datagram to all members of a network. Returns "not available yet" in the current release.

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]

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

Returns: messages [{type, from, data, 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

High-level shortcuts for interacting with Gemini-powered service agents running on the overlay network. Replies are delivered via the inbox — the command blocks until the agent responds (default: 120 s timeout).

ai

pilotctl ai "<query>" [--node <address>] [--timeout <dur>] [--output-file <path>]

Sends a natural-language query to the pilot-agent AI assistant and waits for the reply.

The target node is read from ~/.pilot/scriptorium.yaml (node: <address>) or overridden with --node.

--output-file <path> — save reply to a file instead of printing; omit the path for a timestamped filename.
--timeout — how long to wait for the reply (default: 120s).

Returns: reply (human-readable text from the AI)

# Ask anything about pilotctl
pilotctl ai "how do I ping another node?"

# Save the answer to a file
pilotctl ai "explain the task workflow" --output-file task-guide.txt

# Target a specific node
pilotctl ai "list all ports" --node 0:0000.0000.3814

clawdit

pilotctl clawdit ["<query>"] [--file <openclaw.json>] [--node <address>]
         [--timeout <dur>] [--output-file <path>]

Sends an OpenClaw security audit request to the claw-audit agent and waits for the report.

The target node is read from ~/.pilot/clawdit.yaml (node: <address>) or overridden with --node.

--file <path> — path to an openclaw.json config to audit; when provided, the agent uses this file instead of reading from the remote machine's filesystem.
--output-file <path> — save the audit report to a file.
--timeout — how long to wait (default: 120s; audits can be slow).

Without a query, runs a full security audit by default.

Returns: reply (formatted audit report)

# Full audit of the remote OpenClaw installation
pilotctl clawdit

# Audit a specific config file
pilotctl clawdit --file ~/.openclaw/openclaw.json

# Ask a targeted question
pilotctl clawdit "is my gateway exposed to the network?"

# Save the report
pilotctl clawdit --output-file audit-report.txt --timeout 3m

scriptorium

pilotctl scriptorium <command> [body] [--node <address|hostname>]

Low-level command dispatcher. Sends {"command":"<name>","body":"<args>"} to a responder node and prints the transport ACK. Does not wait for a reply — use pilotctl inbox to read the response. Target node is read from ~/.pilot/scriptorium.yaml.

See Service Agents for the full dispatch flow and how to build your own agents.

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

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

Tasks

enable-tasks / disable-tasks

pilotctl enable-tasks     # Advertise task execution readiness
pilotctl disable-tasks    # Stop accepting tasks

Returns: node_id, task_exec (bool)

task submit

pilotctl task submit <address|hostname> --task "<description>"

Submits a task to a peer. Polo score gate: submitter score must be ≥ receiver score.

Returns: target, task_id, task, status, message, accepted

task list

pilotctl task list [--type received|submitted]

Lists tasks. Without --type, shows both received and submitted.

Returns: tasks [{task_id, status, description, from, to, created_at, category}]

task accept

pilotctl task accept --id <task_id>

Accepts a NEW task. Adds it to the FIFO execution queue.

Returns: task_id, status, message

task decline

pilotctl task decline --id <task_id> --justification "<reason>"

Declines a NEW task with a justification.

Returns: task_id, status, justification, message

task execute

pilotctl task execute

Pops the first ACCEPTED task from the queue and marks it EXECUTING.

Returns: task_id, task_description, status, from

task send-results

pilotctl task send-results --id <task_id> --results "<text>"
pilotctl task send-results --id <task_id> --file <filepath>

Sends results back to the submitter. Updates polo scores.

Returns: task_id, status, sent_to, sent_type

task queue

pilotctl task queue

Displays ACCEPTED tasks in FIFO execution order.

Returns: queue [{task_id, description, from, created_at}], count

See Tasks & Polo for the full lifecycle, polo score formula, and timeouts.

Managed Networks

Commands for managed networks with polo score peer evaluation.

managed score

pilotctl managed score <peer_node_id> [--net <id>] [--topic <T>] [--delta <N>]

Score a peer in a managed network. Default delta: 1.

Returns: node_id, delta, topic

managed status

pilotctl managed status [--net <id>]

Show managed network status for this node.

managed rankings

pilotctl managed rankings [--net <id>]

Display peer rankings in the managed network.

managed cycle

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

Force a managed network evaluation cycle. Prunes low-scoring peers and fills vacancies.

Returns: pruned, filled, peers

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
set --format <json|splunk_hec|syslog_cef> --endpoint <URL> — configure export
disable — disable export

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.

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
set --type <oidc|saml|entra_id|ldap|webhook> --url <URL> [--issuer URL] [--client-id ID] [--tenant-id ID] — 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 <node_id> <email>

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). Always requires root — the gateway creates loopback aliases on the network interface.

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

← 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

listen

broadcast (WIP — not yet available)

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

ai

clawdit

scriptorium

Diagnostics

health

ping

traceroute

bench

peers

connections

disconnect

Tasks

enable-tasks / disable-tasks

task submit

task list

task accept

task decline

task execute

task send-results

task queue

Managed Networks

managed score

managed status

managed rankings

managed cycle

Network Policies