Skip to content

Commit 3b5e4f9

Browse files
TeoSlayerTeoSlayer
authored
feat(docs): auto-generated CLI reference + drift-guard CI (PILOT-54) (#227)
docs/cli-reference.md is now produced by scripts/gen-cli-reference.sh which runs the freshly-built pilotctl and captures --help verbatim into a fenced markdown block. A new CI workflow regenerates the file on every PR and fails if the committed copy diverges, so adding a new command or flag without updating docs becomes a red status check instead of silent drift.
1 parent 9189a23 commit 3b5e4f9

3 files changed

Lines changed: 177 additions & 0 deletions

File tree

‎.github/workflows/cli-reference-check.yml‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
name: cli-reference-check
2+
3+
# PILOT-54: regenerates docs/cli-reference.md from `pilotctl --help` and
4+
# fails if the committed copy is stale. Stops doc drift from being a
5+
# silent contributor problem — drift becomes a CI red.
6+
7+
on:
8+
push:
9+
branches: [main]
10+
pull_request:
11+
paths:
12+
- 'cmd/pilotctl/**'
13+
- 'docs/cli-reference.md'
14+
- 'scripts/gen-cli-reference.sh'
15+
- '.github/workflows/cli-reference-check.yml'
16+
17+
permissions:
18+
contents: read
19+
20+
jobs:
21+
check:
22+
name: docs/cli-reference.md up-to-date
23+
runs-on: ubuntu-latest
24+
steps:
25+
- uses: actions/checkout@v4
26+
- uses: actions/setup-go@v5
27+
with:
28+
go-version-file: go.mod
29+
- name: Regenerate
30+
run: scripts/gen-cli-reference.sh
31+
- name: Diff committed vs regenerated
32+
run: |
33+
if ! git diff --exit-code docs/cli-reference.md; then
34+
echo "::error::docs/cli-reference.md is stale. Run scripts/gen-cli-reference.sh and commit the result."
35+
exit 1
36+
fi

‎docs/cli-reference.md‎

Lines changed: 108 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,108 @@
1+
# pilotctl Reference
2+
3+
> **Auto-generated** from `pilotctl --help`. Do not edit by hand — CI regenerates
4+
> on every PR via `scripts/gen-cli-reference.sh` and fails if the committed copy
5+
> differs from a fresh `pilotctl --help` capture (PILOT-54).
6+
>
7+
> Source: [`cmd/pilotctl/main.go`](../cmd/pilotctl/main.go).
8+
9+
```text
10+
pilotctl — Pilot Protocol CLI
11+
12+
Global flags:
13+
--json Output structured JSON (for agent/programmatic use)
14+
15+
Getting started:
16+
pilotctl quickstart 3-command getting-started flow
17+
18+
Bootstrap:
19+
pilotctl init --registry <addr> [--hostname <name>] [--beacon <addr>]
20+
pilotctl config [--set key=value]
21+
22+
Daemon lifecycle:
23+
pilotctl daemon start [--config <path>] [--registry <addr>] [--beacon <addr>] [--email <addr>] [--webhook <url>] [--trust-auto-approve]
24+
pilotctl daemon stop
25+
pilotctl daemon status
26+
27+
Registry commands:
28+
pilotctl register [listen_addr]
29+
pilotctl lookup <node_id>
30+
pilotctl rotate-key
31+
pilotctl set-public
32+
pilotctl set-private
33+
pilotctl deregister
34+
35+
Discovery commands:
36+
pilotctl find <hostname>
37+
pilotctl set-hostname <hostname>
38+
pilotctl clear-hostname
39+
pilotctl set-tags <tag1> [tag2] ...
40+
pilotctl clear-tags
41+
42+
Communication commands:
43+
pilotctl connect <address|hostname> [port] [--message <msg>] [--timeout <dur>]
44+
pilotctl send <address|hostname> <port> --data <msg> [--timeout <dur>]
45+
pilotctl recv <port> [--count <n>] [--timeout <dur>]
46+
pilotctl send-file <address|hostname> <filepath>
47+
pilotctl send-message <address|hostname> --data <text> [--type text|json|binary] [--count <n>] [--reuse-conn] [--wait <dur>]
48+
pilotctl subscribe <address|hostname> <topic> [--count <n>] [--timeout <dur>]
49+
pilotctl publish <address|hostname> <topic> --data <message>
50+
51+
Trust commands:
52+
pilotctl handshake <node_id|hostname> [justification]
53+
pilotctl approve <node_id>
54+
pilotctl reject <node_id> [reason]
55+
pilotctl untrust <node_id>
56+
pilotctl pending
57+
pilotctl trust
58+
59+
Management commands:
60+
pilotctl connections
61+
pilotctl disconnect <conn_id>
62+
63+
Mailbox:
64+
pilotctl received [--clear]
65+
pilotctl inbox [--clear]
66+
67+
Service Agents:
68+
pilotctl send-message list-agents --data "list all agents"
69+
70+
Diagnostic commands:
71+
pilotctl info
72+
pilotctl health
73+
pilotctl peers [--search <query>]
74+
pilotctl ping <address|hostname> [--count <n>] [--timeout <dur>]
75+
pilotctl traceroute <address> [--timeout <dur>]
76+
pilotctl bench <address|hostname> [size_mb] [--timeout <dur>]
77+
pilotctl listen <port> [--count <n>] [--timeout <dur>]
78+
pilotctl broadcast <network_id> <message>
79+
pilotctl updates [--count <n>] [--scope <scope>] read https://teoslayer.github.io/pilot-changelog/feed.xml
80+
81+
Agent tool discovery:
82+
pilotctl context
83+
pilotctl skills [status] show where the daemon installs SKILL.md per detected agent tool
84+
pilotctl skills paths print only the install paths (shell-friendly)
85+
pilotctl skills check run one reconcile pass right now
86+
87+
Gateway (requires root for ports <1024):
88+
pilotctl gateway start [--subnet <cidr>] [--ports <list>] [<pilot-addr>...]
89+
pilotctl gateway stop
90+
pilotctl gateway map <pilot-addr> [local-ip]
91+
pilotctl gateway unmap <local-ip>
92+
pilotctl gateway list
93+
94+
Environment:
95+
PILOT_REGISTRY Registry address (default: 34.71.57.205:9000)
96+
PILOT_SOCKET Daemon socket path (default: /tmp/pilot.sock)
97+
98+
Version:
99+
pilotctl version
100+
101+
Config file: ~/.pilot/config.json
102+
103+
Companion binaries:
104+
daemon start / start --foreground exec the separately-shipped
105+
pilot-daemon binary; gateway start / map exec pilot-gateway. They
106+
are discovered (in order): $PILOT_DAEMON_BIN / $PILOT_GATEWAY_BIN,
107+
next to the pilotctl executable, then $PATH.
108+
```

‎scripts/gen-cli-reference.sh‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
#!/usr/bin/env bash
2+
# PILOT-54: regenerate docs/cli-reference.md from `pilotctl --help`.
3+
# Invoked by CI (.github/workflows/cli-reference-check.yml) to guard
4+
# against the reference doc drifting from the actual binary.
5+
set -euo pipefail
6+
7+
cd "$(dirname "$0")/.."
8+
9+
# Build a fresh pilotctl so the doc reflects HEAD, not whatever happens
10+
# to be on $PATH on the runner.
11+
if [ ! -x ./pilotctl ]; then
12+
go build -o ./pilotctl ./cmd/pilotctl
13+
fi
14+
15+
OUT=docs/cli-reference.md
16+
TMP="$(mktemp)"
17+
18+
{
19+
echo '# pilotctl Reference'
20+
echo ''
21+
echo '> **Auto-generated** from `pilotctl --help`. Do not edit by hand — CI regenerates'
22+
echo '> on every PR via `scripts/gen-cli-reference.sh` and fails if the committed copy'
23+
echo '> differs from a fresh `pilotctl --help` capture (PILOT-54).'
24+
echo '>'
25+
echo '> Source: [`cmd/pilotctl/main.go`](../cmd/pilotctl/main.go).'
26+
echo ''
27+
echo '```text'
28+
./pilotctl --help
29+
echo '```'
30+
} > "$TMP"
31+
32+
mv "$TMP" "$OUT"
33+
echo "Wrote $OUT ($(wc -l < "$OUT") lines)"

0 commit comments

Comments
 (0)