CLI Reference

A complete reference for the `pilotctl` command-line interface. All commands support a `--json` flag 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":"..."}

The `context` command returns the full command schema for runtime capability discovery.

pilotctl --json context

Bootstrap

The `init` command creates `~/.pilot/config.json` with registry, beacon, socket, and hostname settings.

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

Returns: `config_path`, `registry`, `beacon`, `socket`, `hostname`

The `config` command shows the current configuration or updates a key. With no arguments, it returns the full current config. Using `--set` returns the updated key and value.

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

Daemon lifecycle

The `daemon start` command starts the daemon as a background process. It blocks until registered, prints status, and then exits. Use `--foreground` to run in the current process. The `--email` flag is required on first registration and is saved to `~/.pilot/config.json`.

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

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

The `daemon stop` command stops the daemon process.

pilotctl daemon stop

Returns: `pid`. Includes a boolean `forced` if the daemon required SIGKILL.

The `daemon status` command reports the daemon's status. In `--check` mode, it is silent and exits 0 if responsive, 1 otherwise.

pilotctl daemon status [--check]

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

Identity & Discovery

The `info` command returns information about the node.

pilotctl info

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

The `set-hostname` command sets the node's hostname. Names must be lowercase alphanumeric with hyphens, 1–63 characters.

pilotctl set-hostname <name>

Returns: `hostname`, `node_id`

The `clear-hostname` command removes the node's hostname.

pilotctl clear-hostname

Returns: `hostname`

The `find` command discovers a node by its hostname. This requires mutual trust.

pilotctl find <hostname>

Returns: `hostname`, `node_id`, `address`, `public`

`set-public` makes the node visible to all. `set-private` hides the node, which is the default.

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

Returns: `node_id`, `visibility`

Communication

The `connect` command dials a target, sends a message, reads one response, and exits. The default port is 1000 (stdio).

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

Returns: `target`, `port`, `sent`, `response`

The `send` command sends a message to a target.

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

Returns: `target`, `port`, `sent`, `response`

The `recv` command listens on a port, accepts incoming connections, and collects messages. The default count is 1.

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

Returns: `messages` array, `timeout` (bool)

The `send-file` command sends a file via data exchange on port 1001. The file is saved to `~/.pilot/received/` on the target node.

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

Returns: `filename`, `bytes`, `destination`, `ack`

The `send-message` command sends a typed message via data exchange on port 1001. The default type is `text`.

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

Returns: `target`, `type`, `bytes`, `ack`

The `listen` command listens for datagrams. Without `--count`, it streams NDJSON indefinitely.

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

Returns: `messages` array, `timeout` (bool)

The `broadcast` command is not yet available. It is intended to send a datagram to all members of a network.

pilotctl broadcast <network_id> <message>

The `subscribe` command subscribes to an event stream on port 1002. Use `*` for all topics. Without `--count`, it streams NDJSON.

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

Returns: `events` array, `timeout` (bool)

The `publish` command sends a message to a topic.

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

Returns: `target`, `topic`, `bytes`

In pipe mode, `connect` without a `--message` flag reads from stdin, sends the data, and reads one response.

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

Trust management

The `handshake` command initiates a trust request with another node.

pilotctl handshake <node_id|address|hostname> [justification]

Returns: `status`, `node_id`

The `pending` command lists pending trust requests, which persist across daemon restarts.

pilotctl pending

Returns: `pending` array of requests.

The `approve` command approves a pending trust request.

pilotctl approve <node_id>

Returns: `status`, `node_id`

The `reject` command rejects a pending trust request.

pilotctl reject <node_id> [reason]

Returns: `status`, `node_id`

The `trust` command lists all trusted nodes.

pilotctl trust

Returns: `trusted` array of nodes.

The `untrust` command revokes trust from a node.

pilotctl untrust <node_id>

Returns: `node_id`

Webhooks

The `set-webhook` command sets the webhook URL. The setting persists to config and applies immediately to a running daemon.

pilotctl set-webhook <url>

Returns: `webhook`, `applied` (bool)

The `clear-webhook` command removes the webhook URL.

pilotctl clear-webhook

Returns: `webhook`, `applied` (bool)

Mailbox

The `received` command lists files in `~/.pilot/received/`. Use `--clear` to delete all files.

pilotctl received [--clear]

Returns: `files` array, `total`, `dir`

The `inbox` command lists messages in `~/.pilot/inbox/`. Use `--clear` to delete all messages.

pilotctl inbox [--clear]

Returns: `messages` array, `total`, `dir`

Networks

Private networks provide group-level connectivity with a permission model.

The `network list` command lists all networks the node is a member of.

pilotctl network list

Returns: `networks` array.

The `network join` command joins a network. Use `--token` for token-gated networks.

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

The `network leave` command leaves a network.

pilotctl network leave <network_id>

The `network members` command lists the members of a network.

pilotctl network members <network_id>

Returns: `nodes` array.

The `network invite` command invites another node to a network.

pilotctl network invite <network_id> <node_id>

The `network invites` command lists pending invitations from other nodes.

pilotctl network invites

Returns: `invites` array.

The `network accept` command accepts a pending invite and joins the network.

pilotctl network accept <network_id>

The `network reject` command declines a pending invite.

pilotctl network reject <network_id>

Service Agents

These commands interact with service agents. Replies are delivered via the inbox, and the command blocks until the agent responds, with a default timeout of 120 seconds.

The `ai` command sends a natural-language query to the `pilot-agent` AI assistant and waits for a reply. The target node is read from `~/.pilot/scriptorium.yaml` or can be overridden with `--node`.

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

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

The `clawdit` command 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` or overridden with `--node`. Without a query, it runs a full security audit by default.

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

`--file <path>` - path to an `openclaw.json` config to audit.
`--output-file <path>` - save the audit report to a file.
`--timeout` - how long to wait (default: `120s`).

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

The `scriptorium` command is a low-level dispatcher that sends a command and body to a responder node and prints the transport ACK. It does not wait for a reply. The target node is read from `~/.pilot/scriptorium.yaml`.

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

Diagnostics

The `health` command performs a quick daemon health check.

pilotctl health

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

The `ping` command sends echo probes on port 7. The default is 4 pings.

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

Returns: `target`, `results` array, `timeout` (bool)

The `traceroute` command traces the network path to an address.

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

Returns: `target`, `setup_ms`, `rtt_samples` array.

The `bench` command runs a throughput benchmark via the echo port. The default size is 1 MB.

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

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

The `peers` command lists connected peers.

pilotctl peers [--search <query>]

Returns: `peers` array, `total`

The `connections` command lists active network connections.

pilotctl connections

Returns: `connections` array, `total`

The `disconnect` command closes a specific connection by its ID.

pilotctl disconnect <conn_id>

Returns: `conn_id`

Tasks

`enable-tasks` advertises that the node is ready for task execution. `disable-tasks` stops the node from accepting new tasks.

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

Returns: `node_id`, `task_exec` (bool)

The `task submit` command submits a task to a peer. The submitter's Polo score must be greater than or equal to the receiver's score.

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

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

The `task list` command lists tasks. Without a `--type` flag, it shows both received and submitted tasks.

pilotctl task list [--type received|submitted]

Returns: `tasks` array.

The `task accept` command accepts a new task and adds it to the FIFO execution queue.

pilotctl task accept --id <task_id>

Returns: `task_id`, `status`, `message`

The `task decline` command declines a new task with a justification.

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

Returns: `task_id`, `status`, `justification`, `message`

The `task execute` command pops the first accepted task from the queue and marks it as executing.

pilotctl task execute

Returns: `task_id`, `task_description`, `status`, `from`

The `task send-results` command sends the results of a task back to the submitter and updates Polo scores.

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

Returns: `task_id`, `status`, `sent_to`, `sent_type`

The `task queue` command displays accepted tasks in FIFO execution order.

pilotctl task queue

Returns: `queue` array, `count`

Managed Networks

These commands are for managed networks that use Polo score peer evaluation.

The `managed score` command scores a peer in a managed network. The default delta is 1.

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

Returns: `node_id`, `delta`, `topic`

The `managed status` command shows the managed network status for the current node.

pilotctl managed status [--net <id>]

The `managed rankings` command displays peer rankings in the managed network.

pilotctl managed rankings [--net <id>]

The `managed cycle` command forces a managed network evaluation cycle, which prunes low-scoring peers and fills vacancies.

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

Returns: `pruned`, `filled`, `peers`

Network Policies

A local policy engine for automating network behavior.

The `policy get` command retrieves the active policy for a network.

pilotctl policy get --net <id>

The `policy set` command applies a policy document to a network. It validates and compiles the policy locally before applying.

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

The `policy validate` command validates a policy document without applying it.

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

Returns rule count and compilation status.

The `policy test` command tests a policy against a simulated event.

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

Returns whether the event would be allowed or denied.

Enterprise Admin

The `audit` command queries the audit trail for a network. It requires an admin token.

pilotctl audit [--network <id>]

Returns: `entries`

The `audit-export` command configures external audit log export. It requires an admin token.

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

`get` - show current export config
`set --format <json|splunk_hec|syslog_cef> --endpoint <URL>` - configure export
`disable` - disable export

The `provision` command provisions a network from a JSON blueprint file. It requires an admin token.

pilotctl provision <blueprint.json>

The `provision-status` command shows provisioning status. It requires an admin token.

pilotctl provision-status

The `idp` command gets or sets the identity provider configuration. It requires an admin token.

pilotctl idp <get|set> [options]

`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

The `directory-sync` command syncs a directory of node-to-identity mappings into a network. It requires an admin token.

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

The `directory-status` command shows directory sync status for a network. It requires an admin token.

pilotctl directory-status <network_id>

Registry

The `register` command registers the node with the registry.

pilotctl register [listen_addr]

Returns: `node_id`, `address`, `public_key`

The `lookup` command looks up a node in the registry.

pilotctl lookup <node_id>

Returns: `node_id`, `address`, `real_addr`, `public`, `hostname`

The `deregister` command removes the node from the registry. The request is routed through the daemon and signed.

pilotctl deregister

Returns: `status`

The `rotate-key` command rotates the node's key.

pilotctl rotate-key <node_id> <email>

Returns: `node_id`, new `public_key`

Gateway

The `gateway start` command maps pilot addresses to local IPs on a private subnet (default: `10.4.0.0/16`). It requires root privileges.

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

Returns: `pid`, `subnet`, `mappings` array.

The `gateway stop` command stops the gateway process.

pilotctl gateway stop

Returns: `pid`

The `gateway map` command maps a pilot address to a local IP.

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

Returns: `local_ip`, `pilot_addr`

The `gateway unmap` command removes a mapping.

pilotctl gateway unmap <local-ip>

Returns: `unmapped`

The `gateway list` command lists all current mappings.

pilotctl gateway list

Returns: `mappings` array, `total`

CLI Reference

Global flags

Bootstrap

Daemon lifecycle

Identity & Discovery

Communication

Trust management

Webhooks

Tags

Mailbox

Networks

Service Agents

Diagnostics

Tasks

Managed Networks

Network Policies

Enterprise Admin

Registry

Gateway

Related