Add sentryctl agents CLI surface

sentryctl agents list|get, config get|set|clear, restart -- same
list/get shape as dashboards/alerts, plus a config sub-subcommand
mirroring dashboards' permissions since an override has its own
lifecycle distinct from the agent resource itself.

config set is the one command with real logic: since PUT
/agents/{host}/config replaces the whole stored override rather than
patching individual fields, it fetches the agent's current effective
config first and merges only the flags actually passed on top of it,
mirroring the web UI's edit form logic in Go. restart requires
explicit confirmation (interactive y/N or --yes) and refuses on
non-interactive stdin without --yes, the same posture cmd_query.go's
--nl/--execute already established for anything that changes what's
running.

Live-verified the merge logic specifically, since it's the part most
likely to hide a real bug: setting one field on a clean agent
correctly carried forward its other reported values, and a second
config set call correctly carried forward the first call's override
rather than resetting it to the reported baseline. config clear and
restart --yes both round-tripped against a live agent, with the
restart picked up and acted on within one check-in cycle.

This closes out the agent-management punch list (restart, fleet-wide
alerting, this CLI surface) -- see /docs/agent-management-design.md.
This commit is contained in:
2026-08-16 20:30:45 -07:00
parent 21fb68a0d4
commit d2bb9de245
5 changed files with 723 additions and 0 deletions
+16
View File
@@ -38,6 +38,8 @@ func run(args []string, stdout, stderr io.Writer) int {
return cmdDashboards(args[1:], stdout, stderr)
case "alerts":
return cmdAlerts(args[1:], stdout, stderr)
case "agents":
return cmdAgents(args[1:], stdout, stderr)
case "-h", "--help", "help":
usage(stdout)
return 0
@@ -59,6 +61,12 @@ Usage:
sentryctl dashboards permissions grant <dashboard-id> <user-id> viewer|editor [--api <url>]
sentryctl dashboards permissions revoke <dashboard-id> <user-id> [--api <url>]
sentryctl alerts list|get <id>|apply <file> [--alerting-api <url>]
sentryctl agents list|get <host> [--api <url>]
sentryctl agents config get <host>|clear <host> [--api <url>]
sentryctl agents config set <host> [--batch-max-size N] [--batch-flush-interval-ms N]
[--heartbeat-enabled true|false] [--heartbeat-interval-ms N]
[--journald-unit UNIT] [--api <url>]
sentryctl agents restart <host> [--yes] [--api <url>]
Commands:
ping Checks that the api service is reachable via GET /healthz.
@@ -79,6 +87,14 @@ Commands:
alerts list/get/apply against alerting's rule CRUD endpoints.
"apply <file>" creates a rule from a JSON file with the
same shape POST /rules accepts.
agents Agent inventory, remote config, and lifecycle commands
(see /docs/agent-management-design.md). "config set" reads
the agent's current effective config first and PUTs back
the complete merged override -- only the fields you pass
change, everything else carries forward unchanged, same
as the web UI's edit form. "restart" briefly interrupts
log collection on that host and prompts for confirmation
unless --yes is given.
--api defaults to $SENTRYCTL_API_URL, or `+defaultAPIURL+` if unset.
--alerting-api defaults to $SENTRYCTL_ALERTING_API_URL, or `+defaultAlertingURL+` if unset.