feat(pilotctl): add pilotctl update command (PILOT-396) (#262)

* feat(pilotctl): add update command for one-shot updater invoke (PILOT-396)

pilotctl update runs the updater once — checks the latest release,
downloads and installs if newer. When the daemon is not running (manual
mode), it also re-runs skill install so newly installed binaries have
matching skill definitions.

Dependency: github.com/pilot-protocol/updater now exposes RunOnce() for
one-shot invocation without a periodic loop.

Closes PILOT-396

* chore: regenerate docs/cli-reference.md via gen-cli-reference.sh

PILOT-396

* fix: remove MOTD line from cli-reference.md (CI env has no daemon)

---------

Co-authored-by: matthew-pilot <matthew@pilotprotocol.network>
Co-authored-by: Calin Teodor <t.calin@student.vu.nl>

Author: 3 people

cmd/pilotctl/main.go

@@ -1128,6 +1128,16 @@ Common keys:
 	"version": `Usage: pilotctl version
 
 Print the pilotctl build version string.
+`,
+	"update": `Usage: pilotctl update [flags]
+
+Run the updater once — check for new releases and install if available.
+In manual mode (daemon not running), re-runs skill install so newly
+installed binaries have matching skill definitions.
+
+Flags:
+  --repo <name>   GitHub owner/repo for releases (default: TeoSlayer/pilotprotocol)
+  --pin <tag>     pin to a specific release tag (e.g. v1.10.5)
 `,
 	"updates": `Usage: pilotctl updates [flags]
 
@@ -1315,6 +1325,7 @@ Diagnostic commands:
   pilotctl bench <address|hostname> [size_mb] [--timeout <dur>]
   pilotctl listen <port> [--count <n>] [--timeout <dur>]
   pilotctl broadcast <network_id> <message>
+  pilotctl update [--pin <tag>]                        run the updater once — check and install new release
   pilotctl updates [--count <n>] [--scope <scope>]   read https://teoslayer.github.io/pilot-changelog/feed.xml
 
 Agent tool discovery:
@@ -1412,6 +1423,10 @@ dispatch:
 		cmdQuickstart()
 		return
 
+	case "update":
+		cmdUpdate(cmdArgs)
+		return
+
 	case "updates":
 		cmdUpdates(cmdArgs)
 		return

cmd/pilotctl/updates.go

@@ -11,6 +11,10 @@ import (
 	"path/filepath"
 	"strings"
 	"time"
+
+	"github.com/pilot-protocol/common/driver"
+	"github.com/pilot-protocol/skillinject"
+	"github.com/pilot-protocol/updater"
 )
 
 // changelogFeedURL is the canonical RSS 2.0 feed for the public Pilot
@@ -204,6 +208,74 @@ func collapseWhitespace(s string) string {
 	return strings.TrimSpace(b.String())
 }
 
+// cmdUpdate runs the updater once — checking for new releases, downloading and
+// installing if available. When the daemon is not running (manual mode), it
+// also re-runs skill install so newly installed binaries have matching skills.
+//
+// Flags:
+//	--repo <name>   : GitHub owner/repo for releases (default: TeoSlayer/pilotprotocol)
+//	--pin <tag>     : pin to a specific release tag (e.g. v1.10.5)
+//	(global) --json : emit machine-readable JSON
+func cmdUpdate(args []string) {
+	flags, _ := parseFlags(args)
+	repo := flagString(flags, "repo", "TeoSlayer/pilotprotocol")
+	pin := flagString(flags, "pin", "")
+
+	// Determine install directory: where the updater binary lives.
+	updaterBin, err := findCompanionBinary("pilot-updater", "PILOT_UPDATER_BIN")
+	if err != nil {
+		fatalCode("internal", "cannot locate pilot-updater binary: %v", err)
+	}
+	installDir := filepath.Dir(updaterBin)
+
+	u := updater.New(updater.Config{
+		CheckInterval:  0, // unused for RunOnce
+		Repo:           repo,
+		InstallDir:     installDir,
+		Version:        version,
+		PinnedVersion:  pin,
+	})
+
+	u.RunOnce()
+
+	if jsonOutput {
+		outputOK(map[string]interface{}{
+			"install_dir": installDir,
+			"repo":        repo,
+			"pinned":      pin != "",
+		})
+		return
+	}
+	fmt.Printf("Update check complete. Install dir: %s\n", installDir)
+
+	// In manual mode (no daemon running), re-run skill install so skills
+	// match the (possibly updated) binaries.
+	if !daemonRunning() {
+		report, err := runTick()
+		if err != nil {
+			fmt.Fprintf(os.Stderr, "warning: skill install failed: %v\n", err)
+		} else {
+			c := report.Counts()
+			fmt.Printf("Skills: %d files checked (%d up-to-date, %d installed, %d errors)\n",
+				len(report.Outcomes),
+				c[skillinject.ActionNoop],
+				c[skillinject.ActionCreate]+c[skillinject.ActionRewrite],
+				c[skillinject.ActionError])
+		}
+	}
+}
+
+// daemonRunning checks whether the daemon socket is reachable.
+func daemonRunning() bool {
+	sock := getSocket()
+	d, err := driver.Connect(sock)
+	if err != nil {
+		return false
+	}
+	d.Close()
+	return true
+}
+
 // fetchChangelogFeed returns the cached feed body if it's fresh (< 5 min)
 // and `refresh` is false; otherwise hits the network. Returns
 // (body, fromCache, err). Cache lives at ~/.pilot/updates-cache.xml so

docs/cli-reference.md

@@ -76,6 +76,7 @@ Diagnostic commands:
   pilotctl bench <address|hostname> [size_mb] [--timeout <dur>]
   pilotctl listen <port> [--count <n>] [--timeout <dur>]
   pilotctl broadcast <network_id> <message>
+  pilotctl update [--pin <tag>]                        run the updater once — check and install new release
   pilotctl updates [--count <n>] [--scope <scope>]   read https://teoslayer.github.io/pilot-changelog/feed.xml
 
 Agent tool discovery:

go.mod

@@ -16,7 +16,7 @@ require (
 	github.com/pilot-protocol/runtime v0.3.1
 	github.com/pilot-protocol/skillinject v0.2.2
 	github.com/pilot-protocol/trustedagents v0.2.3
-	github.com/pilot-protocol/updater v0.2.2-0.20260529065627-220ed5b8383f
+	github.com/pilot-protocol/updater v0.2.2-0.20260616131353-92a3a30a235e
 	github.com/pilot-protocol/webhook v0.2.0
 	golang.org/x/sys v0.45.0
 )
@@ -25,3 +25,5 @@ require (
 	github.com/expr-lang/expr v1.17.8 // indirect
 	golang.org/x/net v0.55.0 // indirect
 )
+
+replace github.com/pilot-protocol/updater v0.2.2-0.20260616131353-92a3a30a235e => github.com/pilot-protocol/updater v0.2.2-0.20260616131353-92a3a30a235e

go.sum

@@ -50,6 +50,8 @@ github.com/pilot-protocol/trustedagents v0.2.3 h1:QQJHYqzPrECJwkCev0xIDBMjd92uht
 github.com/pilot-protocol/trustedagents v0.2.3/go.mod h1:gDgEOC9lHmXSS9v45h80XxlmUS861soIrA0AsbXiSV4=
 github.com/pilot-protocol/updater v0.2.2-0.20260529065627-220ed5b8383f h1:1dyunPeEOriqTv1xbt0fuDwieA5V5NLU1nVSC2714jU=
 github.com/pilot-protocol/updater v0.2.2-0.20260529065627-220ed5b8383f/go.mod h1:/I0uhVk1SljAOEYmjTdI/6CP7UmemmV4WB22ai1FxUw=
+github.com/pilot-protocol/updater v0.2.2-0.20260616131353-92a3a30a235e h1:vFzuw5dUVi0igwI2PdVzDY8OnY6FDLzM05wzI75zUZ8=
+github.com/pilot-protocol/updater v0.2.2-0.20260616131353-92a3a30a235e/go.mod h1:/I0uhVk1SljAOEYmjTdI/6CP7UmemmV4WB22ai1FxUw=
 github.com/pilot-protocol/webhook v0.2.0 h1:3UFU9X2yBb0iKlPbzVcism+Z6yCrBBaOgdo9+vd4Wf4=
 github.com/pilot-protocol/webhook v0.2.0/go.mod h1:WVXhHFg+o0pHHk+4nXMCh1zl/ZAyZ3AXrtx6mNuZS6g=
 golang.org/x/net v0.55.0 h1:bcvxaJn3e1U6InsFWt1JUq1aSjnRxLzT2rtD2KfkDF8=