@intflow/sentinelctl 0.5.0 → 0.6.0

package/README.md

@@ -54,6 +54,8 @@ sentinelctl metrics top diskDaysLeft --below 14             # disks that fill up
 sentinelctl metrics top cpu --agg p95 -r 24h --compare --sort change
 sentinelctl metrics top reboots -r 7d --above 0             # many devices reboot daily on schedule; compare with p50
 sentinelctl metrics top networkTx -r 24h --label fleet=edge -o json
+sentinelctl devices correlate <agent-id> --peak cpu -r 24h      # metrics and logs around the CPU peak
+sentinelctl devices correlate <agent-id> --at 2026-09-30T14:58:00+09:00 --window 30m
 ```
 
 `metrics top` runs one query over every device: `--agg avg|max|min|p95|last` per device over `-r 1h|6h|24h|7d|30d` (or `--from/--to`, up to 30 days), ranked, with min/p50/p90/p95/max across devices. Metrics: cpu, memory, disk, swap, load, temperature, processes, tcpConnections, networkRx, networkTx, reboots, diskDaysLeft. `--compare` adds the previous window of the same length. Device filters work like `devices list`; retired devices are excluded by default.
@@ -121,6 +123,10 @@ sentinelctl admin operations -r 7d
 
 Any other endpoint: `sentinelctl api "/api/devices?status=offline"`.
 
+## Updates
+
+The server tells the CLI the latest version; when a newer one exists the CLI prints one notice a day on stderr (`{"notice":{"type":"update_available"}}` with -o json). Update with `npm install -g sentinelctl@latest`. A CLI older than the server minimum gets exit code 3 with the same command. `SENTINELCTL_NO_UPDATE_NOTICE=1` turns the notice off.
+
 ## Output and exit codes
 
 - `--select agentId,displayName,status,metadata.role` keeps only those fields of each item in json/ndjson output (plus top-level scalars), e.g. `devices list --all -o json` drops from ~700KB to ~20KB. `devices show --series none` (or `--series cpu,memory`) drops time series.
@@ -130,9 +136,10 @@ Any other endpoint: `sentinelctl api "/api/devices?status=offline"`.
 
 ## Publishing
 
-Publish the scoped package first, then the alias with the same version (`cli/unscoped/package.json` depends on it). Accounts with two-factor authentication need an interactive terminal for the browser approval.
+GitHub Actions publishes both packages (`.github/workflows/publish-cli.yml`) with npm trusted publishing, so no npm token is stored.
 
-```bash
-cd cli && npm test && npm publish --access public
-cd unscoped && npm publish --access public
-```
+1. Bump `cli/package.json`, `cli/unscoped/package.json` (version and its `@intflow/sentinelctl` dependency) and `cliLatestVersion` in `config/dashboard.json` to the same version; `node scripts/check-cli-release.mjs` checks this.
+2. Commit, then push a tag: `git tag cli-v0.6.0 && git push origin cli-v0.6.0`.
+3. The workflow runs the CLI checks and tests, publishes `@intflow/sentinelctl`, waits for the registry, then publishes the `sentinelctl` alias. Versions already on npm are skipped. Run it manually (Actions → publish-cli) to verify and pack without publishing.
+
+One-time setup on npmjs.com, for each of the two packages: Settings → Trusted Publisher → GitHub Actions, organization or user `yeon3724`, repository `sentinel-fleet-console`, workflow `publish-cli.yml`, environment `npm`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intflow/sentinelctl",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Sentinel Fleet Console CLI: search device logs, inspect status and metrics, edit metadata and manage roles",
   "type": "module",
   "bin": {

package/src/client.mjs

@@ -9,9 +9,7 @@ export class ApiError extends Error {
   }
 }
 
-const userAgent = 'sentinelctl';
-
-export function createClient({ server, token = null, fetch: fetchImplementation = globalThis.fetch, timeoutMs = 60_000, maxRetries = 5, sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)) }) {
+export function createClient({ server, token = null, userAgent = 'sentinelctl', onVersions = null, fetch: fetchImplementation = globalThis.fetch, timeoutMs = 60_000, maxRetries = 5, sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)) }) {
   async function request(method, path, { query, body, auth = true, allowStatuses = [] } = {}) {
     const url = new URL(path, server);
     for (const [key, value] of Object.entries(query ?? {})) {
@@ -36,6 +34,8 @@ export function createClient({ server, token = null, fetch: fetchImplementation
         const reason = error?.name === 'TimeoutError' ? 'timed out' : 'could not connect';
         throw new ApiError(`Request to ${url.origin} ${reason}.`, { code: 'network_error' });
       }
+      const latest = response.headers.get('x-sentinelctl-latest');
+      if (onVersions && latest) onVersions({ latest, minimum: response.headers.get('x-sentinelctl-minimum') });
       const text = await response.text();
       let payload = {};
       try {

package/src/commands.mjs

@@ -13,17 +13,17 @@ const maxPages = 40;
 const deviceSorts = ['attention', 'status', 'displayName', 'cpu', 'memory', 'disk', 'load', 'temperature', 'ageSeconds', 'role', 'site', 'group', 'incidentCount'];
 
 const logFilterOptions = {
-  query: { alias: 'q', type: 'string', placeholder: 'text', description: 'Words or phrase in the message, case-insensitive by default. Positional words are appended.' },
-  pattern: { alias: 'p', type: 'string', placeholder: 'pattern', description: 'Exact message pattern with numbers as <N>, copied from `logs stats --by message` or `logs groups`. Fast and precise.' },
-  'case-sensitive': { type: 'boolean', description: 'Match -q case-sensitively. Much faster on long windows, but misses other casings.' },
-  agent: { alias: 'a', type: 'string', placeholder: 'id', description: 'Exact agent ID (find it with `devices lookup`).' },
-  level: { alias: 'l', type: 'string', choices: logLevels, description: 'emergency/critical/error include more severe levels; warning, info (with notice) and debug match that level only.' },
-  source: { alias: 's', type: 'string', placeholder: 'source', description: 'Exact source: systemd unit, container name, syslog identifier (see `logs sources`).' },
-  service: { type: 'string', placeholder: 'name', description: 'Logical service label (`service` field) across all devices, e.g. payment-api. Logs without the label never match.' },
-  env: { type: 'string', placeholder: 'name', description: 'Environment label (`env` field), e.g. prod.' },
-  range: { alias: 'r', type: 'string', choices: logRanges, description: 'Relative window. Default 15m when --from/--to are absent.' },
-  from: { type: 'string', placeholder: 'ISO', description: 'Absolute window start, e.g. 2026-09-30T00:00:00+09:00. Requires --to; up to the retention period (31 days by default).' },
-  to: { type: 'string', placeholder: 'ISO', description: 'Absolute window end.' },
+  query: { alias: 'q', type: 'string', placeholder: 'text', description: 'Words in the message, case-insensitive. Positional words are appended.' },
+  pattern: { alias: 'p', type: 'string', placeholder: 'pattern', description: 'Exact pattern as printed by logs stats --by message or logs groups (<N> = number).' },
+  'case-sensitive': { type: 'boolean', description: 'Case-sensitive -q: much faster, misses other casings.' },
+  agent: { alias: 'a', type: 'string', placeholder: 'id', description: 'Agent ID (see devices lookup).' },
+  level: { alias: 'l', type: 'string', choices: logLevels, description: 'emergency/critical/error include more severe levels; warning, info, debug are exact.' },
+  source: { alias: 's', type: 'string', placeholder: 'source', description: 'systemd unit, container or syslog identifier (see logs sources).' },
+  service: { type: 'string', placeholder: 'name', description: '`service` label, across devices.' },
+  env: { type: 'string', placeholder: 'name', description: '`env` label.' },
+  range: { alias: 'r', type: 'string', choices: logRanges, description: 'Relative window (default 15m).' },
+  from: { type: 'string', placeholder: 'ISO', description: 'Start, e.g. 2026-09-30T09:00:00+09:00 (with --to; up to 31 days).' },
+  to: { type: 'string', placeholder: 'ISO', description: 'End.' },
 };
 
 async function getComplete(context, path, query) {
@@ -552,6 +552,52 @@ async function devicesOverview(context, { options, positionals }) {
   ]));
 }
 
+function durationSeconds(value, name) {
+  const match = /^(\d+)([smh])$/.exec(String(value));
+  if (!match) throw new UsageError(`--${name} must look like 90s, 15m or 2h: ${value}`);
+  return Number(match[1]) * { s: 1, m: 60, h: 3600 }[match[2]];
+}
+
+const correlateMetricNames = ['cpu', 'memory', 'disk', 'load', 'temperature', 'swap', 'processes', 'tcpConnections', 'networkRx', 'networkTx'];
+const correlateUnits = { cpu: '%', memory: '%', disk: '%', swap: '%', temperature: '°C', networkRx: 'B/s', networkTx: 'B/s' };
+
+async function devicesCorrelate(context, { options, positionals }) {
+  const agentId = requireAgentId(positionals);
+  if (!options.at === !options.peak) throw new UsageError('Give exactly one of --at <time> or --peak <metric>.', { hint: 'Example: sentinelctl devices correlate <agent-id> --peak cpu -r 24h' });
+  if (options.at && !Number.isFinite(Date.parse(options.at))) throw new UsageError(`Cannot parse --at: ${options.at}`);
+  const body = await context.client.get(`/api/devices/${encodeURIComponent(agentId)}/correlate`, {
+    at: options.at ? new Date(options.at).toISOString() : undefined, peak: options.peak, range: options.peak ? options.range : undefined,
+    window: durationSeconds(options.window, 'window'), level: options.level, top: options.top, series: options.series ? 1 : undefined,
+  });
+  const value = (name, number) => metricValueText(number, correlateUnits[name]);
+  emit(context, body, () => [
+    renderKeyValues([
+      ['Device', `${body.displayName} (${body.agentId})`],
+      ['At', `${localTime(body.at)}${body.peak ? ` · peak ${body.peak.metric} ${value(body.peak.metric, body.peak.value)} in ${body.peak.range}` : ''}`],
+      ['Window', `${localTime(body.window.start)} → ${localTime(body.window.end)} (${body.stepSeconds}s step)`],
+      ['Reboots', body.reboots.map(localTime).join(', ') || 'none'],
+      ['Logs', `${body.logs.total} (${Object.entries(body.logs.levels).map(([level, count]) => `${level} ${count}`).join(', ') || '-'})`],
+    ]),
+    '',
+    renderTable(Object.entries(body.metrics), [
+      { header: 'METRIC', value: ([name]) => name },
+      { header: 'AT', value: ([name, item]) => value(name, item.atValue) },
+      { header: 'MIN', value: ([name, item]) => value(name, item.min) },
+      { header: 'MAX', value: ([name, item]) => value(name, item.max) },
+      { header: 'BIGGEST STEP', value: ([name, item]) => (item.biggestStep ? `${item.biggestStep.delta > 0 ? '+' : ''}${value(name, item.biggestStep.delta)} at ${localTime(item.biggestStep.at).slice(11)}` : '-') },
+    ], { width: context.width }),
+    '',
+    body.logs.groups.length ? renderTable(body.logs.groups, [
+      { header: 'COUNT', value: (group) => String(group.count) },
+      { header: 'FIRST', value: (group) => localTime(group.first).slice(11) },
+      { header: 'SOURCE', value: (group) => group.source, max: 22 },
+      { header: 'PATTERN', value: (group) => group.pattern },
+    ], { width: context.width, wide: options.wide }) : 'No logs in the window.',
+  ].join('\n'));
+  if (!body.logs.complete) context.hint('Log counts are partial; run again to complete.');
+  if (body.logs.truncated) context.hint(`Showing ${body.logs.groups.length} of ${body.logs.groupCount} log groups. Raise --top or add -l.`);
+}
+
 async function health(context) {
   const body = await context.client.get('/api/health');
   emit(context, body, () => [
@@ -821,22 +867,22 @@ async function rawApi(context, { options, positionals }) {
 const commands = [
   {
     group: 'logs', name: 'search', run: logsSearch, role: 'viewer', mutates: false,
-    summary: 'Raw log lines by window, device, severity, source, text or exact pattern; --collapse for groups',
-    description: 'Newest first. Default 15m window and 100 logs. When fetching several pages, 250 logs are fetched per request, up to 10,000 in total, which on busy fleets covers only minutes. Use it for a handful of example lines after narrowing with `logs stats`/`logs groups` and -p. --collapse returns every matching group instead of lines (same as `logs groups`).',
+    summary: 'Raw log lines, newest first',
+    description: 'Stops at 10,000 lines, which covers minutes of this fleet: read examples here after logs stats/groups, never count with it.',
     args: [{ name: 'text', optional: true, description: 'Same as -q (words are joined with spaces).' }],
     options: {
       ...logFilterOptions,
-      limit: { alias: 'n', type: 'integer', choices: [50, 100, 250], description: 'Logs per page. Default 100 (250 when paging).' },
-      pages: { type: 'integer', placeholder: 'N', description: `Follow the cursor for up to N pages (1-${maxPages}).` },
-      all: { type: 'boolean', description: 'Fetch every page of the window, stopping at 10,000 logs.' },
-      fields: { type: 'boolean', description: 'Include raw fields (admin only, audited, 50 logs per page).' },
-      collapse: { type: 'boolean', description: 'Group by device, source and pattern over the whole window with counts, first/last time and the latest line (see logs groups).' },
-      top: { type: 'integer', placeholder: 'N', description: 'With --collapse: groups to return (1-500, default 50).' },
-      dedupe: { type: 'boolean', description: 'Fold lines repeated within the same second on the same device and source into one with a repeat count.' },
-      since: { type: 'string', placeholder: 'ISO', description: 'Only logs after this timestamp (exclusive) up to now; pass the printed nextSince to poll without re-reading.' },
-      follow: { alias: 'f', type: 'boolean', description: 'Keep printing new logs (for humans; never ends, agents should not use it).' },
-      interval: { type: 'integer', default: 5, placeholder: 'seconds', description: 'Polling interval for --follow (min 5).' },
-      wide: { alias: 'w', type: 'boolean', description: 'Do not truncate messages in table output.' },
+      limit: { alias: 'n', type: 'integer', choices: [50, 100, 250], description: 'Lines per page (default 100; 250 when paging).' },
+      pages: { type: 'integer', placeholder: 'N', description: `Pages to follow (1-${maxPages}).` },
+      all: { type: 'boolean', description: 'All pages, up to 10,000 lines.' },
+      fields: { type: 'boolean', description: 'Raw fields (admin, audited, 50 per page).' },
+      collapse: { type: 'boolean', description: 'Same as logs groups.' },
+      top: { type: 'integer', placeholder: 'N', description: 'Groups with --collapse (1-500, default 50).' },
+      dedupe: { type: 'boolean', description: 'Fold same-second repeats into one line with a count.' },
+      since: { type: 'string', placeholder: 'ISO', description: 'Only logs after this time; poll with the printed nextSince.' },
+      follow: { alias: 'f', type: 'boolean', description: 'Stream new logs (humans only; never ends).' },
+      interval: { type: 'integer', default: 5, placeholder: 'seconds', description: 'Seconds between --follow polls (min 5).' },
+      wide: { alias: 'w', type: 'boolean', description: 'Do not truncate.' },
     },
     roleFor: (options) => (options.fields ? 'admin' : 'viewer'),
     roleNote: '--fields requires admin',
@@ -849,21 +895,21 @@ const commands = [
       'sentinelctl logs search -a <agent-id> -s ssh.service -r 6h --all -o json',
       'sentinelctl logs search --from 2026-09-30T09:00:00+09:00 --to 2026-09-30T10:00:00+09:00 -l warning',
     ],
-    output: 'logs[]: timestamp (UTC ISO), severity, priority, agentId, host, displayName, source, message (+fields, +repeat with --dedupe). -o json wraps them as {criteria, window, count, hasMore, nextSince?, logs}.',
+    output: 'logs[]: {timestamp, severity, agentId, displayName, source, message, repeat?, fields?}; json adds {window, count, hasMore, nextSince?}.',
   },
   {
     group: 'logs', name: 'stats', run: logsStats, role: 'viewer', mutates: false,
-    summary: 'Count and rank logs by source, device, severity or message pattern; compare windows; trends',
-    description: 'Aggregates in VictoriaLogs instead of downloading logs, so counts are exact over the whole window. message groups by pattern with numbers collapsed to <N>; pass a pattern to -p for exact follow-ups. Windows over one day are computed per day and finished days are cached, so repeating a long query is cheap; long requests continue automatically.',
+    summary: 'Exact counts by source, device, level, message pattern or service',
+    description: 'Counts every log in the window on the server. --compare shows what changed, --timeline when.',
     args: [{ name: 'text', optional: true, description: 'Same as -q.' }],
     options: {
       ...logFilterOptions,
-      by: { alias: 'b', type: 'string', choices: statsDimensions, default: 'source', description: 'Group by source, agent (device), level, message pattern or service label.' },
-      top: { type: 'integer', default: 20, placeholder: 'N', description: 'Groups to return (1-100).' },
-      compare: { type: 'boolean', description: 'Also count the previous window of the same length: previousCount, change and isNew per group.' },
-      timeline: { type: 'boolean', description: 'Add per-group counts over time (about 48 buckets): when a pattern started, stopped or spiked.' },
-      sort: { type: 'string', choices: ['count', 'change'], description: 'Rank by count (default) or by increase over the previous window (needs --compare).' },
-      wide: { alias: 'w', type: 'boolean', description: 'Do not truncate long keys in table output.' },
+      by: { alias: 'b', type: 'string', choices: statsDimensions, default: 'source', description: 'Grouping (agent = device).' },
+      top: { type: 'integer', default: 20, placeholder: 'N', description: 'Groups (1-100).' },
+      compare: { type: 'boolean', description: 'Add the previous window: previousCount, change, isNew.' },
+      timeline: { type: 'boolean', description: 'Add counts over time per group (~48 buckets).' },
+      sort: { type: 'string', choices: ['count', 'change'], description: 'count or change (needs --compare).' },
+      wide: { alias: 'w', type: 'boolean', description: 'Do not truncate.' },
     },
     examples: [
       'sentinelctl logs stats -l error -r 1h --by source',
@@ -873,36 +919,36 @@ const commands = [
       'sentinelctl logs stats -a <agent-id> -r 7d --by message',
       'sentinelctl logs stats "connection refused" -r 24h --by agent',
     ],
-    output: '{criteria, window, total, devices, groupCount, truncated, approximate, complete, coverage{chunks, done}, groups[]: {key, count, devices (distinct agents), first?, last? (with --timeline, bucket precision), host?, displayName?, searchText?, previousCount?, change?, isNew?, timeline?: [[epochSeconds, count]]}, timelineStepSeconds?, previous?: {window, total, devices, exhaustive}, newGroupCount?, rising?[≤5], falling?[≤5] (largest increases and decreases across all groups, not only the returned top)}.',
+    output: '{total, devices, groupCount, truncated, complete, groups[]: {key, count, devices, displayName?, previousCount?, change?, isNew?, timeline?[[epoch, count]], first?, last?}, previous?, newGroupCount?, rising?, falling?}.',
   },
   {
     group: 'logs', name: 'groups', run: logsGroups, role: 'viewer', mutates: false,
-    summary: 'Every distinct (device, source, message pattern) in the window with counts, first/last time and the latest line',
-    description: 'The lossless way to see what happened: each group is counted over the whole window and keeps its latest raw line, so nothing is skipped the way a 10,000-line download skips. Typically 50-100x smaller than the raw logs. Windows over one day are computed per day and cached.',
+    summary: 'Every device × source × pattern with count, first/last time and latest line',
+    description: 'Lossless summary of the window, typically 50-100x smaller than the raw lines.',
     args: [{ name: 'text', optional: true, description: 'Same as -q.' }],
     options: {
       ...logFilterOptions,
-      top: { type: 'integer', default: 50, placeholder: 'N', description: 'Groups to return, largest first (1-500).' },
-      wide: { alias: 'w', type: 'boolean', description: 'Do not truncate patterns in table output.' },
+      top: { type: 'integer', default: 50, placeholder: 'N', description: 'Groups, largest first (1-500).' },
+      wide: { alias: 'w', type: 'boolean', description: 'Do not truncate.' },
     },
     examples: [
       'sentinelctl logs groups -l error -r 1h',
       'sentinelctl logs groups -a <agent-id> -r 7d -o json',
       'sentinelctl logs groups -p "Failed to start <N>.service" -r 24h',
     ],
-    output: '{criteria, window, complete, coverage, total, devices, groupCount, patternCount, truncated, approximate, groups[]: {agentId, displayName, source, pattern, count, first, last, latest{timestamp, severity, message}}}.',
+    output: '{total, devices, groupCount, patternCount, truncated, complete, groups[]: {agentId, displayName, source, pattern, count, first, last, latest{timestamp, severity, message}}}.',
   },
   {
     group: 'logs', name: 'facets', run: logsFacets, role: 'viewer', mutates: false,
-    summary: 'Top values of device, host, severity, source, agent version and profile in one query',
-    description: 'Orientation for an unfamiliar window: which devices, sources and severities dominate. Fleet-wide up to 24h; up to 7 days with -a, -s or -p.',
+    summary: 'Top devices, severities, sources and labels in one query',
+    description: 'Fleet-wide up to 24h; up to 7 days with -a, -s, --service or -p.',
     options: {
       ...logFilterOptions,
       range: { alias: 'r', type: 'string', choices: logRanges, description: 'Window (default 1h).' },
       top: { type: 'integer', default: 10, placeholder: 'N', description: 'Values per field (1-50).' },
     },
     examples: ['sentinelctl logs facets -l error -r 24h', 'sentinelctl logs facets -a <agent-id> -r 7d -o json'],
-    output: '{criteria, window, facets{agent_id[{value, count, displayName}], host[], severity[], _SYSTEMD_UNIT[], …}}.',
+    output: '{facets{agent_id[{value, count, displayName}], severity[], _SYSTEMD_UNIT[], service[], …}}.',
   },
   {
     group: 'logs', name: 'context', run: logsContext, role: 'viewer', mutates: false,
@@ -925,14 +971,14 @@ const commands = [
     args: [{ name: 'text', optional: true, description: 'Same as -q.' }],
     options: logFilterOptions,
     examples: ['sentinelctl logs histogram -r 24h', 'sentinelctl logs histogram -a <agent-id> -r 30d -o json'],
-    output: '{start, end, complete, coverage, stepSeconds, total, buckets[]: {at (epoch seconds), total, errors}}. Finished days are cached.',
+    output: '{stepSeconds, total, complete, buckets[]: {at (epoch), total, errors}}.',
   },
   {
     group: 'logs', name: 'sources', run: logsSources, role: 'viewer', mutates: false,
     summary: 'Log sources (systemd units, containers) ranked by exact count',
     options: { range: { alias: 'r', type: 'string', choices: logRanges, default: '24h', description: 'Sample window.' } },
     examples: ['sentinelctl logs sources -r 1h'],
-    output: '{range, total, complete, sources[]: {value, count}}: top 50 by exact count.',
+    output: '{total, sources[]: {value, count}} (top 50).',
   },
   {
     group: 'devices', name: 'list', run: devicesList, role: 'viewer', mutates: false,
@@ -990,21 +1036,21 @@ const commands = [
   },
   {
     group: 'metrics', name: 'top', run: metricsTop, role: 'viewer', mutates: false,
-    summary: 'Rank devices by a metric aggregated over a window, with the fleet-wide distribution',
-    description: 'One server-side query over every device: avg/max/min/p95/last of the metric per device, ranked, plus min/p50/p90/p95/max across devices. --compare adds the previous window of the same length. reboots counts uptime resets (many devices reboot daily on schedule; compare with the fleet p50). diskDaysLeft forecasts days until the root disk is full from the growth over the window (only growing disks; soonest first). Device filters work like devices list (retired devices are excluded by default). Cached for 60s.',
+    summary: 'Rank all devices by a metric over a window, with the fleet distribution',
+    description: 'reboots = uptime resets (daily scheduled reboots are normal; compare with p50). diskDaysLeft = days until the root disk is full at the current growth. Device filters match devices list.',
     args: [{ name: 'metric', description: metricNames.join(', ') }],
     options: {
-      agg: { type: 'string', choices: ['avg', 'max', 'min', 'p95', 'last'], default: 'avg', description: 'Per-device aggregation over the window (ignored for reboots).' },
+      agg: { type: 'string', choices: ['avg', 'max', 'min', 'p95', 'last'], default: 'avg', description: 'Per-device aggregation.' },
       range: { alias: 'r', type: 'string', choices: metricWindows, description: 'Window (default 24h).' },
-      from: { type: 'string', placeholder: 'ISO', description: 'Absolute window start (with --to, at most 30 days).' },
-      to: { type: 'string', placeholder: 'ISO', description: 'Absolute window end.' },
-      top: { type: 'integer', default: 10, placeholder: 'N', description: 'Devices to return (1-100).' },
-      order: { type: 'string', choices: ['desc', 'asc'], description: 'desc = highest first, asc = lowest first (default desc; asc for diskDaysLeft).' },
-      compare: { type: 'boolean', description: 'Also aggregate the previous window: previous and change per device.' },
-      sort: { type: 'string', choices: ['value', 'change'], description: 'Rank by value (default) or by change (needs --compare).' },
-      above: { type: 'number', placeholder: 'N', description: 'Only devices whose value is above N (e.g. --above 90).' },
-      below: { type: 'number', placeholder: 'N', description: 'Only devices whose value is below N.' },
-      query: { alias: 'q', type: 'string', placeholder: 'text', description: 'Device text filter (same as devices list).' },
+      from: { type: 'string', placeholder: 'ISO', description: 'Start (with --to; up to 30 days).' },
+      to: { type: 'string', placeholder: 'ISO', description: 'End.' },
+      top: { type: 'integer', default: 10, placeholder: 'N', description: 'Devices (1-100).' },
+      order: { type: 'string', choices: ['desc', 'asc'], description: 'Default desc (asc for diskDaysLeft).' },
+      compare: { type: 'boolean', description: 'Add the previous window: previous, change.' },
+      sort: { type: 'string', choices: ['value', 'change'], description: 'value or change (needs --compare).' },
+      above: { type: 'number', placeholder: 'N', description: 'Only values above N.' },
+      below: { type: 'number', placeholder: 'N', description: 'Only values below N.' },
+      query: { alias: 'q', type: 'string', placeholder: 'text', description: 'Device text.' },
       status: { type: 'string', choices: deviceStatuses, description: 'Reception status.' },
       lifecycle: { type: 'string', choices: lifecycles, description: 'Lifecycle scope (default operational).' },
       role: { type: 'string', placeholder: 'role', description: 'Device role.' },
@@ -1022,19 +1068,37 @@ const commands = [
       'sentinelctl metrics top diskDaysLeft -r 24h --below 14',
       'sentinelctl metrics top networkTx -r 24h --label fleet=edge -o json',
     ],
-    output: '{metric, aggregation, unit, window{start, end, seconds, range}, criteria, scope{devices, withData, withoutData, matched}, distribution{count, min, avg, p50, p90, p95, max}, previousDistribution?, devices[]: {agentId, displayName, host, status, value, previous?, change?}}.',
+    output: '{metric, unit, scope{devices, withData, matched}, distribution{min, avg, p50, p90, p95, max}, devices[]: {agentId, displayName, status, value, previous?, change?}}.',
   },
   {
     group: 'fleet', name: 'summary', run: fleetSummary, role: 'viewer', mutates: false,
-    summary: 'One-call fleet briefing: status, attention, busiest devices, metric trends, log levels and error patterns',
-    description: 'Start here to answer "how is the infrastructure?". Combines the device inventory, attention reasons with example devices, the highest current CPU/memory/disk/temperature, offline devices split by how long, metric trends (disks full within 14 days, temperature rises of 15°C or more, reboot counts well above the fleet norm) and log statistics for the window: totals by level, top, rising, falling and new error patterns (compared with the previous window) and the devices with the most errors. About 10KB as JSON.',
+    summary: 'Status, attention, trends and error patterns in one call',
+    description: 'Start here. Trends flag disks full within 14 days, temperature rises of 15°C+ and unusual reboot counts; error patterns are compared with the previous window. ~10KB JSON.',
     options: {
       range: { alias: 'r', type: 'string', choices: logRanges, default: '24h', description: 'Log window.' },
-      logs: { type: 'boolean', description: 'Include log statistics (default on; --no-logs skips them).' },
-      trends: { type: 'boolean', description: 'Include metric trends: disks full within 14 days, temperature rises, unusual reboot counts (default on; --no-trends skips them).' },
+      logs: { type: 'boolean', description: 'Log statistics (--no-logs skips).' },
+      trends: { type: 'boolean', description: 'Metric trends (--no-trends skips).' },
     },
     examples: ['sentinelctl fleet summary', 'sentinelctl fleet summary -r 1h -o json', 'sentinelctl fleet summary --no-logs'],
-    output: '{range, stale, devices{total, status, lifecycle, metrics, logs, offline{within24h[], over7dCount, otherCount}}, attention[]: {reason, count, devices[≤5]}, resources{cpu, memory, disk, temperature: [{agentId, displayName, value}]}, trends{diskFullWithin14Days[], temperatureRise[], rebootOutliers{typicalPerWeek, threshold, devices[]}}, logs{complete, window, total, devices, levels, errors{total, previousTotal, devices, newPatterns}, topErrorPatterns[], risingErrorPatterns[], fallingErrorPatterns[] (shrunk or gone since the previous window), topErrorDevices[]}}.',
+    output: '{devices{status, metrics, logs, offline}, attention[]{reason, count, devices}, resources{cpu, memory, disk, temperature}, trends{diskFullWithin14Days, temperatureRise, rebootOutliers}, logs{levels, errors, topErrorPatterns, risingErrorPatterns, fallingErrorPatterns, topErrorDevices}}.',
+  },
+  {
+    group: 'devices', name: 'correlate', run: devicesCorrelate, role: 'viewer', mutates: false,
+    summary: 'Metrics and logs of one device around a time or metric peak',
+    description: 'For "what happened when X spiked": metric values and biggest change, reboots and log groups around --at or the --peak of a metric.',
+    args: [{ name: 'agent-id' }],
+    options: {
+      at: { type: 'string', placeholder: 'ISO', description: 'Center time.' },
+      peak: { type: 'string', choices: correlateMetricNames, description: 'Center on the highest point of this metric within --range instead.' },
+      range: { alias: 'r', type: 'string', choices: ['1h', '6h', '24h', '7d'], default: '24h', description: 'Where to look for --peak.' },
+      window: { type: 'string', default: '15m', placeholder: 'duration', description: 'Look this far before and after (1m-6h).' },
+      level: { alias: 'l', type: 'string', choices: logLevels, description: 'Only these log levels in the groups.' },
+      top: { type: 'integer', default: 20, placeholder: 'N', description: 'Log groups (1-100).' },
+      series: { type: 'boolean', description: 'Include the metric time series in JSON.' },
+      wide: { alias: 'w', type: 'boolean', description: 'Do not truncate patterns.' },
+    },
+    examples: ['sentinelctl devices correlate <agent-id> --peak cpu -r 24h', 'sentinelctl devices correlate <agent-id> --at 2026-09-30T14:58:00+09:00 --window 30m -o json'],
+    output: '{at, window, peak?, metrics{<name>: {atValue, min, max, change, biggestStep{at, delta}}}, reboots[], logs{total, levels, groups[]: {source, pattern, count, first, last, latest}}}.',
   },
   {
     group: 'metadata', name: 'get', run: metadataGet, role: 'viewer', mutates: false,
@@ -1171,10 +1235,10 @@ const commands = [
 
 export const catalog = commands;
 export const groups = {
-  fleet: 'One-call briefing of the whole fleet',
-  logs: 'Count, group and compare logs on the server; exact pattern search; context; volume; sources',
-  metrics: 'Rank devices by an aggregated metric across the fleet',
-  devices: 'Device list, details, lookup, reception overview',
+  fleet: 'Fleet briefing',
+  logs: 'Log counts, groups, patterns and raw lines',
+  metrics: 'Fleet-wide metric rankings',
+  devices: 'Device list, details, reception history, metric-log correlation',
   metadata: 'Device metadata: read, edit (editor), import/export (admin)',
   sessions: 'Your sessions and CLI tokens',
   admin: 'Roles, all sessions, audit clean-up, capacity (admin)',

package/src/main.mjs

@@ -1,4 +1,6 @@
 import { readFileSync } from 'node:fs';
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
 import { closest, parseArguments, UsageError } from './args.mjs';
 import { ApiError, createClient } from './client.mjs';
 import { catalog, commandPath, findCommand, groups, outputChoices, roleLabels, usageLine } from './commands.mjs';
@@ -7,14 +9,23 @@ import { renderKeyValues } from './format.mjs';
 import { browserLogin, openBrowser } from './login.mjs';
 
 const version = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version;
+const userAgent = `sentinelctl/${version} node/${process.versions.node}`;
+const updateCommand = 'npm install -g sentinelctl@latest';
+
+function newer(latest, current) {
+  const a = latest.split('.').map(Number);
+  const b = current.split('.').map(Number);
+  for (let index = 0; index < 3; index += 1) if (a[index] !== b[index]) return a[index] > b[index];
+  return false;
+}
 const roleRank = { viewer: 0, editor: 1, admin: 2 };
-const exitCodes = { 0: 'success', 1: 'server or network error', 2: 'usage error (fix the arguments)', 3: 'not logged in or insufficient role (retrying will not help)' };
+const exitCodes = { 0: 'success', 1: 'server or network error', 2: 'usage error (fix the arguments)', 3: 'not logged in, insufficient role or CLI too old (retrying will not help)' };
 const globalDefinitions = {
   server: { type: 'string', placeholder: 'url', description: 'Console URL (default https://monitor.intflow.dev; also SENTINEL_URL).' },
   profile: { type: 'string', placeholder: 'name', description: 'Saved login profile (default "default").' },
   output: { alias: 'o', type: 'string', choices: outputChoices, description: 'Output format. Use json or ndjson from agents and scripts.' },
   json: { type: 'boolean', description: 'Same as -o json.' },
-  select: { type: 'string', placeholder: 'fields', description: 'json/ndjson: keep only these comma-separated fields (dotted paths like metadata.role) of each item in the main list, plus top-level scalars. Example: --select agentId,displayName,status,memory' },
+  select: { type: 'string', placeholder: 'fields', description: 'json/ndjson: keep only these fields of each item, e.g. agentId,status,metadata.role.' },
   quiet: { type: 'boolean', description: 'Suppress summaries and hints on stderr (errors are still printed).' },
   help: { alias: 'h', type: 'boolean', description: 'Show help.' },
   version: { alias: 'V', type: 'boolean', description: 'Show the version.' },
@@ -119,84 +130,54 @@ function overviewHelp() {
   return lines.join('\n');
 }
 
-const agentGuide = `Using sentinelctl from AI agents and scripts
-
-SETUP
-- A human logs in once (\`sentinelctl login\`, approve in the browser; 30 days). Later commands are
-  non-interactive. Elsewhere pass SENTINEL_TOKEN and SENTINEL_URL.
-- Use -o json or -o ndjson. stdout is data only; notes, hints and errors go to stderr (--quiet drops
-  notes and hints). A json/ndjson error is one stderr line {"error":{status,code,message,hint,exitCode}}.
-- Exit codes: 0 ok · 1 server/network (retry later) · 2 usage (fix the arguments) · 3 login/role (do
-  not retry). \`sentinelctl commands <group> --json\` describes options and output fields.
-
-HOW TO INVESTIGATE: broad to narrow, count before you read
-1. Overview          fleet summary -o json
-                     status, attention reasons, busiest devices, trends (disk full soon, temperature
-                     rises, unusual reboots), error levels, top/rising/falling/new error patterns.
-2. What and where    logs stats -l error -r 24h --by message --compare -o json      (patterns, change)
-                     logs groups -l error -r 24h -o json        (every device x source x pattern with
-                                                                 count, first/last time, latest line)
-3. When              logs stats -p "<pattern>" --by agent --timeline -r 7d -o json
-                     logs histogram -a <id> -r 7d -o json
-4. Read a few lines  logs search -p "<pattern>" -a <id> -r 24h -n 50 -o json
-                     logs context -a <id> -s <source> -t <timestamp>   (lines around one log)
-5. Device state      devices overview <id> -r 7d -o json · devices show <id> --series cpu,memory -o json
-6. Fleet metrics     metrics top memory -r 7d · metrics top disk --agg last --above 85
-                     metrics top diskDaysLeft --below 14 · metrics top cpu --agg p95 --compare
-                     metrics top reboots -r 7d (most devices reboot daily; compare with p50)
+const agentGuide = `sentinelctl for AI agents
 
-LOG SEARCH RULES (complete answers at low cost)
-- Never download logs to count, rank or summarize them. logs search returns at most 10,000 lines,
-  which on this fleet covers minutes, not hours: the rest of the window is silently missing.
-  logs stats and logs groups count every log in the window on the server.
-- Prefer logs groups over logs search: errors in one hour are typically ~10,000 lines but ~150
-  groups, each with its exact count and latest line.
-- Copy patterns exactly. Patterns from logs stats --by message / logs groups (numbers shown as <N>)
-  go to -p/--pattern, which matches that pattern exactly and quickly. -q matches words
-  case-insensitively and can also hit unrelated messages.
-- Narrow before widening: device (-a), source (-s), service (--service), severity (-l), pattern (-p).
-  Start with 1h-24h; widen to 7d or 30d only when you need history.
-- Fleet-wide windows over 7 days need a narrowing filter (-a, -s, --service, -p or -q with
-  --case-sensitive); otherwise the server answers 422 log_query_too_broad.
-  Single-device, single-service and single-pattern queries can use the whole retention period
-  (31 days by default).
-- Windows over one day are aggregated per day and finished days are cached: repeating a long query
-  is cheap, and the CLI continues automatically if the server needs several requests. A partial
-  result says so in complete/coverage.
-- To watch for new logs, poll with --since <nextSince from the previous run>, not --follow.
-- --dedupe folds lines repeated within the same second (the agent writes some messages twice).
-- Levels: emergency/critical/error include more severe levels; warning, info and debug are exact.
-- Applications are found by source (-s: systemd unit, container) on one device, or by the service
-  label (--service, --env) across devices when the collector sets it; logs stats --by service ranks them.
+Setup   A human runs \`sentinelctl login\` once (30 days), or set SENTINEL_TOKEN and SENTINEL_URL.
+Output  Use -o json. stdout is data; notes, hints and errors go to stderr (--quiet drops notes).
+Errors  One stderr line {"error":{status,code,message,hint,exitCode}}; messages are Korean, hints English.
+        Exit 0 ok · 1 server/network (retry later) · 2 usage (fix arguments) · 3 login/role/too old (stop).
+Updates A stderr {"notice":{"type":"update_available",…}} line means a newer CLI exists; tell the user.
+Help    sentinelctl <command> --help · sentinelctl commands <group> --json
 
-LIMITS (shared with the web console, per user)
-- 2 log queries and 2 metric aggregations at a time; 60 seconds of log query time per minute.
-  429 responses are retried automatically with backoff; run commands one after another.
-- Retrying a 422 or 400 without changing the arguments will fail again; read the hint.
+Workflow: broad to narrow, count before reading
+1. fleet summary                                      status, attention, trends, error patterns
+2. logs stats -l error -r 24h --by message --compare  which patterns, what changed
+   logs groups -l error -r 24h                        device x source x pattern, latest line
+3. logs stats -p "<pattern>" --by agent --timeline    who and since when
+   devices correlate <id> --peak cpu                  metrics and logs around a spike
+4. logs search -p "<pattern>" -a <id> -n 50           a few raw lines (logs context for neighbors)
+Metrics: metrics top <metric>, e.g. memory -r 7d · disk --agg last · diskDaysLeft · reboots
 
-KEEP OUTPUT SMALL
-- --select a,b.c keeps only those fields (devices list --all -o json: ~700KB -> ~20KB).
-- devices show --series none drops time series; logs groups/stats return compact rows.
+Rules
+- Never count or summarize by downloading: logs search stops at 10,000 lines (minutes of this
+  fleet); logs stats and logs groups count the whole window.
+- Pass patterns to -p exactly as printed (<N> = number). -q is a case-insensitive word match.
+- Narrow first (-a, -s, --service, -l, -p) and start with 1h-24h. Fleet-wide windows over 7 days
+  need one of -a, -s, --service, -p or --case-sensitive (else 422 log_query_too_broad); narrowed
+  queries reach 31 days. Long aggregations are cached per day and continue automatically.
+- Run commands one at a time: per user 2 log queries at once and 60s of log time per minute
+  (429 is retried automatically). Poll with --since <nextSince>, never --follow.
+- Keep output small: --select a,b.c · devices show --series none.
+- Commands that change data (metadata, admin): --dry-run first. Viewer tokens are read-only.`;
 
-CHANGES
-- metadata set/bulk/rollback/import and admin commands change data: run with --dry-run first when
-  available, check the result, then apply. Viewer tokens cannot change anything.
-- Server error messages are Korean (shared with the web console); hints are English.`;
+function compact(record) {
+  return Object.fromEntries(Object.entries(record).filter(([, value]) => value !== undefined && value !== null && !(Array.isArray(value) && !value.length)));
+}
 
 function commandsCatalog(selected = null) {
   return {
     version,
-    globalOptions: globalDefinitions,
+    globalOptions: Object.fromEntries(Object.entries(globalDefinitions).map(([name, spec]) => [name, compact(spec)])),
     exitCodes,
     commands: [
-      ...(selected ? [] : Object.entries(specialCommands).map(([name, command]) => ({ command: name, usage: command.usage, summary: command.summary, role: null, mutates: name === 'logout' }))),
-      ...(selected ?? catalog).map((command) => ({
-        command: commandPath(command), usage: usageLine(command), summary: command.summary, description: command.description ?? null,
-        role: command.role, roleNote: command.roleNote ?? null, mutates: command.mutates, args: command.args ?? [],
-        options: Object.fromEntries(Object.entries(command.options).map(([name, spec]) => [name, {
-          alias: spec.alias ?? null, type: spec.type, choices: spec.choices ?? null, default: spec.default ?? null,
-          multiple: Boolean(spec.multiple), description: spec.description ?? null,
-        }])),
+      ...(selected ? [] : Object.entries(specialCommands).map(([name, command]) => ({ command: name, usage: command.usage, summary: command.summary, mutates: name === 'logout' }))),
+      ...(selected ?? catalog).map((command) => compact({
+        command: commandPath(command), usage: usageLine(command), summary: command.summary, description: command.description,
+        role: command.role, roleNote: command.roleNote, mutates: command.mutates, args: command.args,
+        options: Object.fromEntries(Object.entries(command.options).map(([name, spec]) => [name, compact({
+          alias: spec.alias, type: spec.type, choices: spec.choices, default: spec.default,
+          multiple: spec.multiple || undefined, description: spec.description,
+        })])),
         examples: command.examples, output: command.output,
       })),
     ],
@@ -205,7 +186,7 @@ function commandsCatalog(selected = null) {
 
 async function login(context, argv) {
   const { options } = parseArguments(argv, { 'no-browser': { type: 'boolean' }, name: { type: 'string' } });
-  const client = createClient({ server: context.connection.server, fetch: context.fetch });
+  const client = createClient({ server: context.connection.server, fetch: context.fetch, userAgent });
   const result = await browserLogin(client, {
     clientName: options.name,
     launchBrowser: !options['no-browser'],
@@ -240,6 +221,21 @@ async function logout(context) {
   context.out(removed ? 'Logged out.' : 'No saved login to remove.');
 }
 
+async function noticeUpdate(context, environment) {
+  const latest = context?.versions?.latest;
+  if (!latest || !newer(latest, version) || environment.SENTINELCTL_NO_UPDATE_NOTICE) return;
+  const path = join(dirname(context.connection.path), 'update-notice.json');
+  let last = {};
+  try { last = JSON.parse(await readFile(path, 'utf8')); } catch {}
+  if (last.latest === latest && Date.now() - (last.at ?? 0) < 86_400_000) return;
+  const message = `sentinelctl ${latest} is available (you have ${version}). Update: ${updateCommand}`;
+  context.err(context.global.output === 'table' ? `notice: ${message}` : JSON.stringify({ notice: { type: 'update_available', current: version, latest, command: updateCommand } }));
+  try {
+    await mkdir(dirname(path), { recursive: true });
+    await writeFile(path, JSON.stringify({ latest, at: Date.now() }), { mode: 0o600 });
+  } catch {}
+}
+
 async function rememberRole(context, role) {
   const saved = context.connection.profile;
   if (!saved || context.connection.fromEnvironment || saved.role === role) return;
@@ -254,13 +250,14 @@ async function whoami(context) {
   const identity = await context.client.get('/api/session');
   await rememberRole(context, identity.role);
   if (context.global.output === 'json' || context.global.output === 'ndjson') {
-    context.out(JSON.stringify({ server: context.connection.server, ...identity, tokenExpiresAt: context.connection.profile?.expiresAt ?? null }));
+    context.out(JSON.stringify({ server: context.connection.server, ...identity, tokenExpiresAt: context.connection.profile?.expiresAt ?? null, cli: { version, latest: context.versions?.latest ?? null } }));
     return;
   }
   context.out(renderKeyValues([
     ['Server', context.connection.server], ['User', identity.user], ['Name', identity.name],
     ['Role', roleLabels[identity.role] ?? identity.role], ['Token ID', identity.sessionId],
     ['Token expires', context.connection.profile?.expiresAt],
+    ['CLI', `${version}${context.versions?.latest ? ` (latest ${context.versions.latest})` : ''}`],
   ]));
 }
 
@@ -299,6 +296,7 @@ function apiHint(error, context, command) {
       ? 'Check the agent ID with `sentinelctl devices lookup <part of the name>`.' : 'Not found; check the ID.';
   }
   if (error.status === 409) return 'Someone saved a change first. Run the command again to apply on top of the latest revision.';
+  if (error.code === 'cli_upgrade_required') return `Update the CLI: ${updateCommand} (or @intflow/sentinelctl@latest), then rerun.`;
   if (error.code === 'log_query_too_broad') {
     return 'Narrow it: add -a <agent-id>, -s <source>, --service <name>, -p "<pattern>" (from `logs stats --by message`) or --case-sensitive with -q, or use a window of 7 days or less.';
   }
@@ -412,7 +410,7 @@ export async function main(argv, {
       select: global.select ? global.select.split(',').map((field) => field.trim()).filter(Boolean) : null,
       hint: (text) => { if (!global.quiet) err(`hint: ${text}`); },
       note: (text) => { if (!global.quiet && global.output === 'table') err(text); },
-      client: createClient({ server: connection.server, token: connection.token, fetch, sleep }),
+      client: createClient({ server: connection.server, token: connection.token, fetch, sleep, userAgent, onVersions: (versions) => { context.versions = versions; } }),
     };
     if (name === 'login') { await login(context, commandArgv); return 0; }
     if (name === 'logout') { await logout(context); return 0; }
@@ -438,9 +436,11 @@ export async function main(argv, {
         `Ask an admin to run \`sentinelctl admin grant <your-email> --role ${error.required}\`. Nothing was sent to the server.`, 3);
     }
     if (error instanceof ApiError) {
-      const exitCode = error.status === 401 || error.status === 403 || error.code === 'not_logged_in' ? 3 : 1;
+      const exitCode = error.status === 401 || error.status === 403 || error.status === 426 || error.code === 'not_logged_in' ? 3 : 1;
       return report(error, apiHint(error, context ?? { connection: {} }, command), exitCode);
     }
     return report(error, null, 1);
+  } finally {
+    if (context) await noticeUpdate(context, environment);
   }
 }