From 39aa18f4adb61220f8168624289c24ebbc7203da Mon Sep 17 00:00:00 2001 From: pstayet Date: Thu, 23 Jul 2026 15:03:31 -0700 Subject: [PATCH] fix(cli): correct stale help text that contradicts actual behavior MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Every change is a string-only edit to embedded help/usage text (or the machine-readable `pilotctl context` catalog) where the text contradicted the implementation. Each was verified against the code before editing: - quickstart: help claimed it "detects whether the daemon is already running" — cmdQuickstart is a bare fmt.Print of a static banner. Help (and the context-catalog entry) now describe the static 3-step cheat-sheet. - updates: help said --count default 5; cmdUpdates uses flagInt(flags, "count", 10). - init: help marked --registry as required; every cmdInit flag is optional with a default (registry 34.71.57.205:9000), and --socket was undocumented. - network: dispatch handles `reject` and `role` but help omitted both. - network create: help showed positional `create `; the command requires --name (also fixed the stale context-catalog args, which listed nonexistent --managed/--policy flags). - skills: dispatch handles disable/enable/set-mode, which help omitted; disable/enable accept only `all` (per-skill is unimplemented); the fixed toolchain list was replaced with wording matching skillinject, whose manifest is fetched at runtime; the "To re-enable" hint printed a command form that errors out (missing `all`). - trusted: cmdTrusted rejects everything except `trusted list`, but help/usage showed bare `trusted`. - send-file: help claimed a 256 MiB frame cap; dataexchange DefaultMaxFrameSize is 1<<30 (1 GiB), env-overridable within [64 KiB, 2 GiB). - bench: help said --timeout default 30s; cmdBench uses 120s. - gateway: "requires root for ports <1024" — pilot-gateway shells out to `ifconfig lo0 alias` / `ip addr add` for loopback aliasing, which needs root regardless of port. - daemon -dataexchange-b64: flag help said data_b64 is written "alongside" data; the dataexchange service's if/else writes data_b64 in place of data. - top-level help: `dgram` exists in the dispatch and had per-command help but was missing from the command listing. docs/cli-reference.md regenerated via scripts/gen-cli-reference.sh (it is an auto-generated capture of `pilotctl --help`; CI enforces it). Verified: gofmt clean; go build ./cmd/... ok; go test ./cmd/pilotctl ok. Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_0142ryqVGEmJN66VZtCC7wFD --- cmd/daemon/main.go | 2 +- cmd/pilotctl/main.go | 67 ++++++++++++++++++++++++++---------------- cmd/pilotctl/skills.go | 2 +- docs/cli-reference.md | 9 ++++-- 4 files changed, 49 insertions(+), 31 deletions(-) diff --git a/cmd/daemon/main.go b/cmd/daemon/main.go index 43b2d088..5d39d4fc 100644 --- a/cmd/daemon/main.go +++ b/cmd/daemon/main.go @@ -88,7 +88,7 @@ func main() { hostname := flag.String("hostname", "", "hostname for discovery (lowercase alphanumeric + hyphens, max 63 chars)") noEcho := flag.Bool("no-echo", false, "disable built-in echo service (port 7)") noDataExchange := flag.Bool("no-dataexchange", false, "disable built-in data exchange service (port 1001)") - dataExchangeB64 := flag.Bool("dataexchange-b64", false, "include raw base64 payload (`data_b64`) alongside `data` in inbox messages — needed only for binary payloads (e.g. zlib-compressed envelopes)") + dataExchangeB64 := flag.Bool("dataexchange-b64", false, "write inbox message payloads as a raw base64 `data_b64` field in place of the UTF-8 `data` field — needed only for binary payloads (e.g. zlib-compressed envelopes)") noEventStream := flag.Bool("no-eventstream", false, "disable built-in event stream service (port 1002)") webhookURL := flag.String("webhook", "", "HTTP(S) endpoint for event notifications (empty = disabled)") adminToken := flag.String("admin-token", "", "admin token for network operations") diff --git a/cmd/pilotctl/main.go b/cmd/pilotctl/main.go index be88c34b..c9333746 100644 --- a/cmd/pilotctl/main.go +++ b/cmd/pilotctl/main.go @@ -889,7 +889,7 @@ Examples: Measure throughput to a remote node via the echo port. Flags: - --timeout overall deadline (default: 30s) + --timeout overall deadline (default: 120s) Examples: pilotctl bench my-agent @@ -1049,14 +1049,16 @@ Flags: --check silent health check — exits 0 if daemon is responsive, 1 otherwise useful in scripts: pilotctl daemon status --check || pilotctl daemon start `, - "init": `Usage: pilotctl init --registry [flags] + "init": `Usage: pilotctl init [flags] Initialize the local pilot config at ~/.pilot/config.json. +All flags are optional; unset values are written with their defaults. Flags: - --registry registry address (required) + --registry registry address (default: 34.71.57.205:9000) --beacon beacon address - --hostname hostname to register + --hostname hostname to register (default: none) + --socket daemon socket path (default: /tmp/pilot.sock) `, "network": `Usage: pilotctl network [flags] @@ -1064,18 +1066,20 @@ Manage overlay networks. Subcommands: list list networks this node belongs to - create create a new network + create --name create a new network join join a network leave leave a network members list members of a network invite invite a node to a network invites list pending invitations accept accept an invitation + reject reject an invitation delete delete a network (owner only) rename rename a network (owner only) promote promote a member to admin demote demote an admin to member kick remove a member from a network + role show a member's role in a network policy show or set network policy `, @@ -1105,7 +1109,7 @@ See also: pilotctl pending — incoming requests waiting for your approval pilotctl handshake — initiate trust with a new peer pilotctl untrust — revoke trust with a node `, - "trusted": `Usage: pilotctl trusted + "trusted": `Usage: pilotctl trusted list List nodes in the embedded trusted-agents directory (service agents that are auto-approved on first contact, without requiring manual pilotctl approve). @@ -1307,7 +1311,7 @@ Flags (one-shot mode): Show the latest Pilot Protocol changelog entries from the release feed. Flags: - --count number of entries to show (default: 5) + --count number of entries to show (default: 10) --scope filter by scope tag (e.g. protocol, cli, networks) `, "context": `Usage: pilotctl context [command] @@ -1322,16 +1326,22 @@ name. With a command name (e.g. 'pilotctl context send-message' or `, "skills": `Usage: pilotctl skills [subcommand] -Manage the SKILL.md files the daemon installs for each detected agent tool -(Claude Code, OpenClaw, PicoClaw). The skill file teaches the agent how to -use pilotctl without manual setup. +Manage the SKILL.md files the daemon installs for each detected agent +toolchain (the supported set is fetched at runtime from the pilot-skills +repository). The skill file teaches the agent how to use pilotctl without +manual setup. Subcommands: status [--verbose] (default) per-tool install state; --verbose adds per-file detail paths print install paths only — one per line, shell-friendly check run one reconcile pass right now (re-installs if missing/outdated) + disable all remove every managed file + persist the opt-out + (only 'all' is accepted; per-skill disable is not yet implemented) + enable all re-enable (auto mode) + run one reconcile pass + (only 'all' is accepted; per-skill enable is not yet implemented) + set-mode auto|manual|disabled persist the reconcile mode to ~/.pilot/config.json -The daemon reconciles skill files every 15 minutes automatically. +The daemon reconciles skill files every 15 minutes automatically (in auto mode). `, "broadcast": `Usage: pilotctl broadcast [flags] @@ -1356,8 +1366,9 @@ Publish a message to a topic on a remote node. "send-file": `Usage: pilotctl send-file [--timeout ] [--prefer-direct] Send a file to a remote node via the data-exchange stream. Files are -capped at 256 MiB (the data-exchange frame ceiling) unless both daemons -have raised PILOT_DATAEXCHANGE_MAX_FRAME — see the dataexchange package. +capped at 1 GiB (the default data-exchange frame ceiling) unless both +daemons have changed PILOT_DATAEXCHANGE_MAX_FRAME (accepted range +64 KiB to 2 GiB) — see the dataexchange package. Flags: --timeout give up if the receiver does not ACK within this @@ -1401,11 +1412,12 @@ Reliability caveats (current implementation): "quickstart": `Usage: pilotctl quickstart -Guided 3-step getting-started walkthrough. Re-run after each step — it detects -whether the daemon is already running and points you to the next action: - 1. start the daemon pilotctl daemon start - 2. discover specialists pilotctl send-message list-agents --data '...' --wait - 3. handshake + query one pilotctl handshake ; pilotctl send-message ... +Print a fixed 3-step getting-started cheat-sheet (DISCOVER, TRUST, TALK) +plus the one-time setup commands (init + daemon start). Static output — +it does not inspect daemon state: + 1. DISCOVER — pilotctl send-message list-agents --data '...' --wait + 2. TRUST — pilotctl handshake + 3. TALK — pilotctl send-message --data "Hello, world!" --wait `, "verify": `Usage: pilotctl verify [status] [flags] @@ -1475,7 +1487,7 @@ Getting started: pilotctl quickstart 3-command getting-started flow Bootstrap: - pilotctl init --registry [--hostname ] [--beacon ] + pilotctl init [--registry ] [--hostname ] [--beacon ] [--socket ] pilotctl config [--set key=value] Daemon lifecycle: @@ -1503,6 +1515,7 @@ Communication commands: pilotctl recv [--count ] [--timeout ] pilotctl send-file pilotctl send-message --data [--type text|json|binary] [--count ] [--reuse-conn] [--wait ] + pilotctl dgram --data pilotctl subscribe [--count ] [--timeout ] pilotctl publish --data @@ -1513,7 +1526,7 @@ Trust commands: pilotctl untrust pilotctl pending pilotctl trust [--search ] live trust state (peers you trust) - pilotctl trusted embedded directory of auto-approved service agents + pilotctl trusted list embedded directory of auto-approved service agents pilotctl prefer-direct prefer a direct tunnel over the relay (daemon v1.12+) Identity & recovery: @@ -1542,6 +1555,8 @@ Agent tool discovery: pilotctl skills [status] show where the daemon installs SKILL.md per detected agent tool pilotctl skills paths print only the install paths (shell-friendly) pilotctl skills check run one reconcile pass right now + pilotctl skills enable|disable all turn skill injection on/off (only 'all' is implemented) + pilotctl skills set-mode auto|manual|disabled persist the reconcile mode App store (install + call local capability apps; full help: pilotctl appstore help): pilotctl appstore catalogue list apps available for one-command install @@ -1557,7 +1572,7 @@ Updates: Operator / admin (run 'pilotctl extras' or 'pilotctl context' for the full list): pilotctl extras network / managed / policy / member-tags / enterprise / low-level plumbing - pilotctl extras gateway start|stop|map|unmap|list IP gateway (requires root for ports <1024) + pilotctl extras gateway start|stop|map|unmap|list IP gateway (requires root — creates loopback interface aliases) Diagnostic commands: pilotctl info @@ -2132,8 +2147,8 @@ func contextCatalog() map[string]interface{} { }, "quickstart": map[string]interface{}{ "args": []string{}, - "description": "Guided 3-step getting-started walkthrough (start daemon → discover agents → handshake + query). Re-run after each step; detects daemon state", - "returns": "quickstart [{step, title, command, description, done}]", + "description": "Print a fixed 3-step getting-started cheat-sheet (discover agents → handshake → send a message) plus one-time setup commands. Static output; does not inspect daemon state", + "returns": "static banner text (no JSON structure)", }, "update": map[string]interface{}{ "args": []string{"[status|enable|disable]", "[--pin ]"}, @@ -2257,7 +2272,7 @@ func contextCatalog() map[string]interface{} { "returns": "node_id", }, "trusted": map[string]interface{}{ - "args": []string{}, + "args": []string{"list"}, "description": "List the embedded trusted-agents directory — well-known service agents (list-agents, weather, etc.) auto-approved on first contact. For live trust state use 'trust'", "returns": "agents [{hostname, node_id}], total", }, @@ -2321,8 +2336,8 @@ func contextCatalog() map[string]interface{} { "returns": "network_id, status", }, "network create": map[string]interface{}{ - "args": []string{"", "[--managed]", "[--policy ]"}, - "description": "Create a new network. Use --managed for policy-governed networks", + "args": []string{"--name ", "[--join-rule open|token|invite]", "[--token ]", "[--enterprise]", "[--rules |--rules-file ]"}, + "description": "Create a new network. Pass --rules/--rules-file for policy-governed (managed) networks", "returns": "network_id, name, managed (bool)", }, diff --git a/cmd/pilotctl/skills.go b/cmd/pilotctl/skills.go index c0218edc..e8f95bd0 100644 --- a/cmd/pilotctl/skills.go +++ b/cmd/pilotctl/skills.go @@ -362,7 +362,7 @@ func cmdSkillsDisable(args []string) { } else { fmt.Println() fmt.Println("Opt-out persisted at ~/.pilot/config.json — future ticks are no-ops.") - fmt.Println("To re-enable: pilotctl skills enable") + fmt.Println("To re-enable: pilotctl skills enable all") } } diff --git a/docs/cli-reference.md b/docs/cli-reference.md index 2920a8d1..c7faf121 100644 --- a/docs/cli-reference.md +++ b/docs/cli-reference.md @@ -16,7 +16,7 @@ Getting started: pilotctl quickstart 3-command getting-started flow Bootstrap: - pilotctl init --registry [--hostname ] [--beacon ] + pilotctl init [--registry ] [--hostname ] [--beacon ] [--socket ] pilotctl config [--set key=value] Daemon lifecycle: @@ -44,6 +44,7 @@ Communication commands: pilotctl recv [--count ] [--timeout ] pilotctl send-file pilotctl send-message --data [--type text|json|binary] [--count ] [--reuse-conn] [--wait ] + pilotctl dgram --data pilotctl subscribe [--count ] [--timeout ] pilotctl publish --data @@ -54,7 +55,7 @@ Trust commands: pilotctl untrust pilotctl pending pilotctl trust [--search ] live trust state (peers you trust) - pilotctl trusted embedded directory of auto-approved service agents + pilotctl trusted list embedded directory of auto-approved service agents pilotctl prefer-direct prefer a direct tunnel over the relay (daemon v1.12+) Identity & recovery: @@ -83,6 +84,8 @@ Agent tool discovery: pilotctl skills [status] show where the daemon installs SKILL.md per detected agent tool pilotctl skills paths print only the install paths (shell-friendly) pilotctl skills check run one reconcile pass right now + pilotctl skills enable|disable all turn skill injection on/off (only 'all' is implemented) + pilotctl skills set-mode auto|manual|disabled persist the reconcile mode App store (install + call local capability apps; full help: pilotctl appstore help): pilotctl appstore catalogue list apps available for one-command install @@ -98,7 +101,7 @@ Updates: Operator / admin (run 'pilotctl extras' or 'pilotctl context' for the full list): pilotctl extras network / managed / policy / member-tags / enterprise / low-level plumbing - pilotctl extras gateway start|stop|map|unmap|list IP gateway (requires root for ports <1024) + pilotctl extras gateway start|stop|map|unmap|list IP gateway (requires root — creates loopback interface aliases) Diagnostic commands: pilotctl info