@intflow/sentinelctl 0.3.2 → 0.4.0

package/README.md

@@ -38,10 +38,25 @@ sentinelctl --help                    # overview
 sentinelctl logs search --help        # one command: options, examples, required role, output fields
 sentinelctl help agents               # guide for AI agents and scripts
 sentinelctl commands --json           # machine-readable catalog of every command
+sentinelctl commands logs --json      # only one group (or "logs stats" for one command)
 ```
 
 Mistyped commands and options get a suggestion (`Did you mean --range?`), and every error comes with a hint for the next step.
 
+## Fleet overview and metrics
+
+```bash
+sentinelctl fleet summary                                   # status, attention, busiest devices, log levels, top/rising/new error patterns
+sentinelctl fleet summary -r 1h -o json                     # about 5KB
+sentinelctl metrics top memory -r 7d                        # devices ranked by 7-day average memory + fleet distribution
+sentinelctl metrics top disk --agg last --above 85 --top 50
+sentinelctl metrics top cpu --agg p95 -r 24h --compare --sort change
+sentinelctl metrics top reboots -r 7d --above 0
+sentinelctl metrics top networkTx -r 24h --label fleet=edge -o json
+```
+
+`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. `--compare` adds the previous window of the same length. Device filters work like `devices list`; retired devices are excluded by default.
+
 ## Logs
 
 ```bash
@@ -55,12 +70,15 @@ sentinelctl logs histogram -l error -r 24h
 sentinelctl logs stats -l error -r 1h --by source          # exact counts, one server-side query
 sentinelctl logs stats -l error -r 24h --by agent --top 10
 sentinelctl logs stats -a <agent-id> -r 7d --by message    # message patterns, numbers collapsed to <N>
+sentinelctl logs stats -l error -r 24h --by message --compare --sort change   # what is new or growing
 sentinelctl logs sources -r 24h
 ```
 
+`logs stats --compare` also counts the previous window of the same length and adds `previousCount`, `change` and `isNew` per group. Message groups carry `searchText`, ready for `logs search -q`.
+
 Windows are `15m`, `1h`, `6h`, `24h`, `7d`, or `--from`/`--to` up to 30 days. One page holds 50, 100 or 250 logs; when you ask for several pages (`--pages N`, at most 40, or `--all`) the CLI fetches 250 per request and stops at 10,000 logs. To answer "how many" or "which devices the most", use `logs stats`: it aggregates on the server and returns exact counts instead of downloading logs. `--fields` (raw fields) is admin-only and audited. `--follow` polls at most every 5 seconds.
 
-Each user can run 2 log queries at a time, web and CLI combined; a third concurrent query gets 429 and GET requests retry automatically.
+Each user can run 2 log queries and 2 metric aggregations at a time, web and CLI combined; a third concurrent query gets 429 and GET requests retry automatically with backoff.
 
 ## Devices and metadata
 
@@ -101,6 +119,7 @@ Any other endpoint: `sentinelctl api "/api/devices?status=offline"`.
 
 ## 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.
 - `-o table` (default), `-o json` (`--json`), `-o ndjson`. Data goes to stdout; summaries, hints and errors go to stderr (`--quiet` drops summaries and hints). With json/ndjson, an error is one stderr line: `{"error":{"status","code","message","hint","exitCode"}}`.
 - Exit codes: `0` success, `1` server or network error, `2` usage error, `3` not logged in or insufficient role.
 - Server error messages are Korean because the web console shares them; hints are English.

package/package.json

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

package/src/args.mjs

@@ -82,6 +82,10 @@ export function parseArguments(argv, definitions) {
       parsed = Number(value);
       if (!Number.isInteger(parsed)) throw new UsageError(`--${name} must be an integer: ${value}`);
     }
+    if (spec.type === 'number') {
+      parsed = Number(value);
+      if (value.trim() === '' || !Number.isFinite(parsed)) throw new UsageError(`--${name} must be a number: ${value}`);
+    }
     if (spec.choices && !spec.choices.includes(parsed)) {
       const suggestion = closest(String(parsed), spec.choices.map(String));
       throw new UsageError(`--${name} must be one of ${spec.choices.join(', ')}: ${value}`,

package/src/commands.mjs

@@ -1,5 +1,5 @@
 import { readFile, writeFile } from 'node:fs/promises';
-import { keyValue, UsageError } from './args.mjs';
+import { closest, keyValue, UsageError } from './args.mjs';
 import { ageText, localTime, percentText, renderKeyValues, renderTable, singleLine } from './format.mjs';
 
 export const roleLabels = { viewer: 'viewer (read-only)', editor: 'editor', admin: 'admin' };
@@ -41,10 +41,41 @@ function logCriteria(options, positionals) {
   };
 }
 
+const listKeys = ['devices', 'logs', 'groups', 'buckets', 'sources', 'sessions', 'users', 'history', 'results', 'attention'];
+
+function pick(item, paths) {
+  if (!item || typeof item !== 'object') return item;
+  const picked = {};
+  for (const path of paths) {
+    const parts = path.split('.');
+    let value = item;
+    for (const part of parts) {
+      value = value !== null && typeof value === 'object' && Object.hasOwn(value, part) ? value[part] : undefined;
+      if (value === undefined) break;
+    }
+    if (value === undefined) continue;
+    let target = picked;
+    for (const part of parts.slice(0, -1)) target = (target[part] ??= {});
+    target[parts.at(-1)] = value;
+  }
+  return picked;
+}
+
+export function project(value, paths) {
+  if (!paths?.length) return value;
+  if (Array.isArray(value)) return value.map((item) => pick(item, paths));
+  const listKey = listKeys.find((key) => Array.isArray(value?.[key]));
+  if (!listKey) return pick(value, paths);
+  const meta = Object.fromEntries(Object.entries(value)
+    .filter(([key, entry]) => key !== listKey && (key === 'window' || entry === null || typeof entry !== 'object')));
+  return { ...meta, [listKey]: value[listKey].map((item) => pick(item, paths)) };
+}
+
 function emit(context, value, table) {
   const { output } = context.global;
-  if (output === 'json') context.out(JSON.stringify(value, null, 2));
-  else if (output === 'ndjson') for (const item of Array.isArray(value) ? value : [value]) context.out(JSON.stringify(item));
+  const selected = project(value, context.select);
+  if (output === 'json') context.out(JSON.stringify(selected, null, 2));
+  else if (output === 'ndjson') for (const item of Array.isArray(selected) ? selected : [selected]) context.out(JSON.stringify(item));
   else context.out(table());
 }
 
@@ -89,11 +120,8 @@ async function logsSearch(context, { options, positionals }) {
     if (!last.hasMore || !last.nextCursor) break;
     cursor = last.nextCursor;
   }
-  if (context.global.output === 'json') {
-    context.out(JSON.stringify({ criteria: last.criteria, window: last.window, count: logs.length, hasMore: last.hasMore, logs }, null, 2));
-  } else {
-    emit(context, logs, () => renderTable(logs, logColumns, { width: context.width, wide: options.wide }));
-  }
+  emit(context, context.global.output === 'json' ? { criteria: last.criteria, window: last.window, count: logs.length, hasMore: last.hasMore, logs } : logs,
+    () => renderTable(logs, logColumns, { width: context.width, wide: options.wide }));
   if (!logs.length) context.hint(emptyLogHint(criteria));
   else context.note(`${logs.length} logs · ${localTime(last.window.start)} → ${localTime(last.window.end)}`);
   if (last.hasMore && options.all) context.hint(`Stopped at the ${maxPages * 250}-log cap. Narrow the filters, or use \`sentinelctl logs stats\` for counts.`);
@@ -133,19 +161,133 @@ const statsDimensions = ['source', 'agent', 'level', 'message'];
 
 async function logsStats(context, { options, positionals }) {
   const criteria = logCriteria(options, positionals);
-  const body = await context.client.get('/api/logs/stats', { ...criteria, by: options.by, top: options.top });
+  if (options.sort === 'change' && !options.compare) {
+    throw new UsageError('--sort change needs --compare.', { hint: 'Example: sentinelctl logs stats -l error -r 24h --by message --compare --sort change' });
+  }
+  const body = await context.client.get('/api/logs/stats', {
+    ...criteria, by: options.by, top: options.top, compare: options.compare ? 1 : undefined, sort: options.sort,
+  });
   const label = { source: 'SOURCE', agent: 'DEVICE', level: 'LEVEL', message: 'MESSAGE PATTERN' }[body.criteria.by];
+  const signed = (value) => (value === null || value === undefined ? '?' : value > 0 ? `+${value}` : String(value));
   emit(context, context.global.output === 'ndjson' ? body.groups : body, () => renderTable(body.groups, [
     { header: 'COUNT', value: (group) => String(group.count) },
-    { header: 'SHARE', value: (group) => (body.total ? `${((group.count / body.total) * 100).toFixed(1)}%` : '-') },
+    ...(body.previous ? [
+      { header: 'PREV', value: (group) => (group.previousCount === null ? '?' : String(group.previousCount)) },
+      { header: 'CHANGE', value: (group) => (group.isNew ? 'new' : signed(group.change)) },
+    ] : [{ header: 'SHARE', value: (group) => (body.total ? `${((group.count / body.total) * 100).toFixed(1)}%` : '-') }]),
     { header: 'DEVICES', value: (group) => String(group.devices) },
     ...(body.criteria.by === 'agent' ? [{ header: 'AGENT ID', value: (group) => group.key, max: 36 }] : []),
     { header: label, value: (group) => (body.criteria.by === 'agent' ? group.displayName ?? group.host ?? group.key : group.key) },
   ], { width: context.width, wide: options.wide }));
   context.note(`${body.total} logs from ${body.devices} devices · ${localTime(body.window.start)} → ${localTime(body.window.end)}`);
+  if (body.previous) {
+    context.note(`Previous window ${localTime(body.previous.window.start)} → ${localTime(body.previous.window.end)}: ${body.previous.total} logs (${signed(body.total - body.previous.total)}) · ${body.newGroupCount} new groups`);
+    if (body.falling?.length && body.criteria.sort !== 'change') {
+      context.note(`Largest drops: ${body.falling.map((group) => `${singleLine(group.key).slice(0, 50)} (${group.change})`).join(' | ')}`);
+    }
+    if (!body.previous.exhaustive) context.hint('The previous window has too many groups to compare exactly; "?" marks groups outside its top list.');
+  }
   if (body.truncated) context.hint(`Showing the top ${body.groups.length} of ${body.groupCount} groups. Raise --top (max 100) or add filters.`);
   if (body.approximate) context.hint('Message patterns are approximate on this server (collapse_nums is unavailable); narrow the window or filters for exact counts.');
   if (!body.total) context.hint(emptyLogHint(criteria));
+  const sample = body.groups.find((group) => group.searchText);
+  if (body.criteria.by === 'message' && sample) {
+    context.hint(`See matching logs: sentinelctl logs search -q "${sample.searchText.replaceAll('"', '\\"')}" -r ${criteria.range ?? '24h'}${criteria.level ? ` -l ${criteria.level}` : ''} (searchText in -o json)`);
+  }
+}
+
+const metricNames = ['cpu', 'memory', 'disk', 'swap', 'load', 'temperature', 'processes', 'tcpConnections', 'networkRx', 'networkTx', 'reboots'];
+const metricWindows = ['1h', '6h', '24h', '7d', '30d'];
+const deviceSeries = ['cpu', 'memory', 'disk', 'load', 'temperature', 'processes', 'tcpConnections', 'networkRx', 'networkTx', 'swap', 'uptime'];
+
+function metricValueText(value, unit) {
+  if (value === null || value === undefined) return '-';
+  if (unit === '%') return `${value.toFixed(1)}%`;
+  if (unit === '°C') return `${value.toFixed(1)}°C`;
+  if (unit === 'B/s') return `${bytesText(value)}/s`;
+  return String(Math.round(value * 100) / 100);
+}
+
+async function metricsTop(context, { options, positionals }) {
+  const metric = positionals[0];
+  if (!metric) throw new UsageError('A metric name is required.', { hint: `One of: ${metricNames.join(', ')}. Example: sentinelctl metrics top memory -r 7d` });
+  if (!metricNames.includes(metric)) {
+    const suggestion = closest(metric, metricNames);
+    throw new UsageError(`Unknown metric: ${metric}`, { hint: `${suggestion ? `Did you mean ${suggestion}? ` : ''}One of: ${metricNames.join(', ')}` });
+  }
+  if ((options.from && !options.to) || (!options.from && options.to)) throw new UsageError('--from and --to must be given together.');
+  if (options.from && options.range) throw new UsageError('--range cannot be combined with --from/--to.');
+  if (options.sort === 'change' && !options.compare) throw new UsageError('--sort change needs --compare.', { hint: `Example: sentinelctl metrics top ${metric} -r 24h --compare --sort change` });
+  for (const label of options.label ?? []) keyValue(label, '--label');
+  const body = await context.client.get('/api/metrics/summary', {
+    metric, agg: options.agg, range: options.from ? undefined : options.range,
+    from: options.from ? new Date(options.from).toISOString() : undefined, to: options.to ? new Date(options.to).toISOString() : undefined,
+    top: options.top, order: options.order, sort: options.sort, compare: options.compare ? 1 : undefined, above: options.above, below: options.below,
+    query: options.query, status: options.status, lifecycle: options.lifecycle, role: options.role, site: options.site, group: options.group,
+    maintainer: options.maintainer, fleet: options.fleet, labels: options.label?.length ? JSON.stringify(options.label) : undefined,
+  });
+  const text = (value) => metricValueText(value, body.unit);
+  const signed = (value) => (value === null || value === undefined ? '?' : `${value > 0 ? '+' : ''}${text(value)}`);
+  emit(context, context.global.output === 'ndjson' ? body.devices : body, () => renderTable(body.devices, [
+    { header: 'AGENT ID', value: (device) => device.agentId, max: 36 },
+    { header: 'NAME', value: (device) => device.displayName, max: 32 },
+    { header: 'STATUS', value: (device) => device.status, max: 9 },
+    { header: body.aggregation.toUpperCase(), value: (device) => text(device.value) },
+    ...(body.criteria.compare ? [
+      { header: 'PREV', value: (device) => text(device.previous) },
+      { header: 'CHANGE', value: (device) => signed(device.change) },
+    ] : []),
+  ], { width: context.width }));
+  const spread = body.distribution;
+  context.note(`${body.metric} ${body.aggregation} over ${body.window.range ?? `${localTime(body.window.start)} → ${localTime(body.window.end)}`} · ${body.scope.withData} of ${body.scope.devices} devices have data`
+    + (spread.count ? ` · min ${text(spread.min)} · p50 ${text(spread.p50)} · p90 ${text(spread.p90)} · max ${text(spread.max)}` : ''));
+  if (body.criteria.above !== null || body.criteria.below !== null) context.note(`${body.scope.matched} devices within the --above/--below bounds.`);
+  if (!body.scope.withData) context.hint('No device reported this metric in the window. Widen -r or drop device filters.');
+  else if (body.scope.matched > body.devices.length) context.hint(`Showing ${body.devices.length} of ${body.scope.matched}. Raise --top (max 100).`);
+}
+
+async function fleetSummary(context, { options }) {
+  const body = await context.client.get('/api/fleet/summary', { range: options.range, logs: options.logs === false ? 0 : undefined });
+  emit(context, body, () => {
+    const counts = (record) => Object.entries(record ?? {}).sort((left, right) => right[1] - left[1]).map(([key, value]) => `${key} ${value}`).join(', ');
+    const names = (devices) => devices.map((device) => device.displayName).join(', ');
+    const sections = [renderKeyValues([
+      ['Devices', `${body.devices.total} (${counts(body.devices.status)})`],
+      ['Metrics', counts(body.devices.metrics)],
+      ['Logs', counts(body.devices.logs)],
+      ['Data', body.stale ? `stale (${body.staleReason ?? ''})` : 'fresh'],
+    ])];
+    sections.push('', 'Attention:', body.attention.length
+      ? renderTable(body.attention, [
+        { header: 'COUNT', value: (entry) => String(entry.count) },
+        { header: 'REASON', value: (entry) => entry.reason, max: 24 },
+        { header: 'EXAMPLES', value: (entry) => names(entry.devices) },
+      ], { width: context.width })
+      : '  none');
+    sections.push('', 'Highest now (online, active):', renderKeyValues(Object.entries(body.resources).map(([field, devices]) => [
+      field, devices.map((device) => `${device.displayName} ${field === 'temperature' ? `${device.value}°C` : `${device.value}%`}`).join(', ') || '-',
+    ])));
+    if (body.logs?.error) sections.push('', `Logs: ${body.logs.error}`);
+    else if (body.logs) {
+      const errors = body.logs.errors;
+      sections.push('', `Logs (${body.range}): ${body.logs.total} from ${body.logs.devices} devices · ${counts(body.logs.levels)}`,
+        `Errors: ${errors.total}${errors.previousTotal === null ? '' : ` (previous window ${errors.previousTotal})`} from ${errors.devices} devices · ${errors.newPatterns} new patterns`,
+        '', 'Top error patterns:', renderTable(body.logs.topErrorPatterns, [
+          { header: 'COUNT', value: (group) => String(group.count) },
+          { header: 'CHANGE', value: (group) => (group.isNew ? 'new' : group.change === null ? '?' : `${group.change > 0 ? '+' : ''}${group.change}`) },
+          { header: 'DEVICES', value: (group) => String(group.devices) },
+          { header: 'PATTERN', value: (group) => group.pattern },
+        ], { width: context.width }),
+        '', `Top error devices: ${body.logs.topErrorDevices.map((device) => `${device.displayName} ${device.count}`).join(', ') || '-'}`);
+      const changes = (label, groups) => {
+        if (groups?.length) sections.push(`${label}: ${groups.map((group) => `${singleLine(group.pattern).slice(0, 60)} (${group.change > 0 ? '+' : ''}${group.change})`).join(' | ')}`);
+      };
+      changes('Rising', body.logs.risingErrorPatterns);
+      changes('Falling', body.logs.fallingErrorPatterns);
+    }
+    return sections.join('\n');
+  });
+  context.hint('Drill down: devices list --focus attention · logs stats -l error --by message --compare · metrics top memory -r 24h');
 }
 
 async function logsContext(context, { options }) {
@@ -217,11 +359,8 @@ async function devicesList(context, { options, positionals }) {
     }
     for (const page of pages) devices.push(...results.get(page));
   }
-  if (context.global.output === 'json') {
-    context.out(JSON.stringify({ matched: first.matched, counts: first.counts, stale: first.stale, staleReason: first.staleReason, devices }, null, 2));
-  } else {
-    emit(context, devices, () => renderTable(devices, deviceColumns, { width: context.width }));
-  }
+  emit(context, context.global.output === 'json' ? { matched: first.matched, counts: first.counts, stale: first.stale, staleReason: first.staleReason, devices } : devices,
+    () => renderTable(devices, deviceColumns, { width: context.width }));
   context.note(`${devices.length} of ${first.matched} devices${options.all ? '' : ` · page ${first.page}/${first.totalPages}`}`);
   if (first.stale) context.hint(`Metrics are stale (${first.staleReason ?? 'metrics query failed'}). Check \`sentinelctl health\`.`);
   if (!devices.length) context.hint('No devices matched. Add --lifecycle all to include maintenance/retired devices, or shorten the search text.');
@@ -235,7 +374,11 @@ function requireAgentId(positionals) {
 
 async function devicesShow(context, { options, positionals }) {
   const agentId = requireAgentId(positionals);
+  const keep = options.series === undefined ? null : options.series === 'none' ? [] : options.series.split(',').map((name) => name.trim()).filter(Boolean);
+  const unknownSeries = (keep ?? []).filter((name) => !deviceSeries.includes(name));
+  if (unknownSeries.length) throw new UsageError(`Unknown series: ${unknownSeries.join(', ')}`, { hint: `Use none or a comma-separated list of: ${deviceSeries.join(', ')}` });
   const body = await context.client.get(`/api/devices/${encodeURIComponent(agentId)}`, { range: options.range, refresh: options.refresh ? 1 : undefined });
+  if (keep) body.series = Object.fromEntries(Object.entries(body.series ?? {}).filter(([name]) => keep.includes(name)));
   const device = body.device;
   const current = body.current ?? {};
   emit(context, body, () => renderKeyValues([
@@ -246,7 +389,7 @@ async function devicesShow(context, { options, positionals }) {
     ['Maintainer', device.metadata?.maintainer], ['Lifecycle', device.metadata?.lifecycle], ['Notes', device.metadata?.description],
     ['Data', body.stale ? `stale (${body.staleReason ?? ''})` : 'fresh'],
   ]));
-  if (context.global.output === 'table') context.hint(`Time series (${body.range}, ${body.stepSeconds}s step) are in \`series\` with -o json.`);
+  if (context.global.output === 'table') context.hint(`Time series (${body.range}, ${body.stepSeconds}s step) are in \`series\` with -o json; --series cpu,memory or --series none keeps the output small.`);
 }
 
 async function devicesLookup(context, { positionals }) {
@@ -547,7 +690,7 @@ async function rawApi(context, { options, positionals }) {
   }
   const url = new URL(path, context.client.server);
   const result = await context.client.request(options.method, url.pathname, { query: Object.fromEntries(url.searchParams), body });
-  context.out(JSON.stringify(result.body, null, 2));
+  context.out(JSON.stringify(project(result.body, context.select), null, 2));
 }
 
 const commands = [
@@ -585,15 +728,18 @@ const commands = [
       ...logFilterOptions,
       by: { alias: 'b', type: 'string', choices: statsDimensions, default: 'source', description: 'Group by source, agent (device), level or message pattern.' },
       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.' },
+      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.' },
     },
     examples: [
       'sentinelctl logs stats -l error -r 1h --by source',
       'sentinelctl logs stats -l error -r 24h --by agent --top 10 -o json',
+      'sentinelctl logs stats -l error -r 24h --by message --compare --sort change',
       '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, groups[]: {key, count, devices (distinct agents), host?, displayName?}}.',
+    output: '{criteria, window, total, devices, groupCount, truncated, approximate, groups[]: {key, count, devices (distinct agents), host?, displayName?, searchText? (message: text to pass to logs search -q), previousCount?, change?, isNew?}, previous?: {window, total, devices, exhaustive}, newGroupCount?, rising?[≤5], falling?[≤5] (largest increases and decreases across all groups, not only the returned top)}.',
   },
   {
     group: 'logs', name: 'context', run: logsContext, role: 'viewer', mutates: false,
@@ -657,9 +803,10 @@ const commands = [
     args: [{ name: 'agent-id' }],
     options: {
       range: { alias: 'r', type: 'string', choices: deviceRanges, default: '6h', description: 'Time-series window (about 120 points).' },
+      series: { type: 'string', placeholder: 'names|none', description: `Keep only these series in JSON (comma-separated: ${deviceSeries.join(', ')}) or none. Cuts output from ~80KB to ~2KB.` },
       refresh: { type: 'boolean', description: 'Bypass the server cache.' },
     },
-    examples: ['sentinelctl devices show <agent-id> -r 24h -o json'],
+    examples: ['sentinelctl devices show <agent-id> -o json --series none', 'sentinelctl devices show <agent-id> -r 24h -o json --series cpu,memory'],
     output: '{device, current, series{cpu, memory, disk, load, temperature, networkRx, networkTx, …: [[epochSeconds, value], …]}, range, stepSeconds, stale}.',
   },
   {
@@ -678,6 +825,52 @@ const commands = [
     examples: ['sentinelctl devices overview <agent-id> -r 7d -o json'],
     output: '{summary{metrics, logs}: {state, outages, delays, missingMinutes, longestOutageMinutes, normalRatio}, agentId, device, products, attentionReasons[], history, related{parent, children[], expectedParent}}.',
   },
+  {
+    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. Device filters work like devices list (retired devices are excluded by default). Cached for 60s.',
+    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).' },
+      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'], default: 'desc', description: 'desc = highest first, asc = lowest first.' },
+      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).' },
+      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.' },
+      site: { type: 'string', placeholder: 'site', description: 'Site.' },
+      group: { type: 'string', placeholder: 'group', description: 'Group.' },
+      maintainer: { type: 'string', placeholder: 'name', description: 'Maintainer.' },
+      fleet: { type: 'string', choices: ['edge', 'infrastructure', 'metrics-only'], description: 'Fleet type.' },
+      label: { type: 'string', multiple: true, placeholder: 'k=v', description: 'Label match (up to 8).' },
+    },
+    examples: [
+      'sentinelctl metrics top memory -r 7d',
+      'sentinelctl metrics top disk --agg last --above 85 --top 50',
+      'sentinelctl metrics top cpu --agg p95 -r 24h --compare --sort change',
+      'sentinelctl metrics top reboots -r 7d --above 0',
+      '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?}}.',
+  },
+  {
+    group: 'fleet', name: 'summary', run: fleetSummary, role: 'viewer', mutates: false,
+    summary: 'One-call fleet briefing: status counts, attention reasons, busiest devices, 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, and log statistics for the window: totals by level, top and rising error patterns (compared with the previous window) and the devices with the most errors. About 5KB as 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).' },
+    },
+    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}, attention[]: {reason, count, devices[≤5]}, resources{cpu, memory, disk, temperature: [{agentId, displayName, value}]}, logs{window, total, devices, levels, errors{total, previousTotal, devices, newPatterns}, topErrorPatterns[], risingErrorPatterns[], fallingErrorPatterns[] (shrunk or gone since the previous window), topErrorDevices[]}}.',
+  },
   {
     group: 'metadata', name: 'get', run: metadataGet, role: 'viewer', mutates: false,
     summary: 'Device metadata: name, role, maintainer, labels, lifecycle',
@@ -813,7 +1006,9 @@ const commands = [
 
 export const catalog = commands;
 export const groups = {
-  logs: 'Search, count and rank logs; context around a log; volume trends; sources',
+  fleet: 'One-call briefing of the whole fleet',
+  logs: 'Search, count and rank logs; compare windows; context around a log; volume trends; sources',
+  metrics: 'Rank devices by an aggregated metric across the fleet',
   devices: 'Device list, details, lookup, reception overview',
   metadata: 'Device metadata: read, edit (editor), import/export (admin)',
   sessions: 'Your sessions and CLI tokens',

package/src/main.mjs

@@ -14,6 +14,7 @@ const globalDefinitions = {
   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' },
   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.' },
@@ -22,7 +23,7 @@ const specialCommands = {
   login: { summary: 'Approve in the browser with your intflow.ai Google Workspace account and store a 30-day CLI token', usage: 'sentinelctl login [--no-browser] [--name <client-name>]' },
   logout: { summary: 'Revoke the CLI token on the server and delete local credentials', usage: 'sentinelctl logout' },
   whoami: { summary: 'Show the server, user, role and token expiry', usage: 'sentinelctl whoami' },
-  commands: { summary: 'List every command; with --json, a machine-readable catalog with options, roles and examples', usage: 'sentinelctl commands [--json]' },
+  commands: { summary: 'List every command; with --json, a machine-readable catalog with options, roles and examples (optionally for one group or command)', usage: 'sentinelctl commands [<group> [<command>]] [--json]' },
   help: { summary: 'Help: help <command>, help agents (guide for AI agents)', usage: 'sentinelctl help [<command> | agents]' },
 };
 
@@ -95,6 +96,7 @@ function overviewHelp() {
     '',
     'Getting started:',
     '  sentinelctl login                              approve once in the browser (valid for 30 days)',
+    '  sentinelctl fleet summary                      one-call briefing of the whole fleet',
     '  sentinelctl devices list --status offline',
     '  sentinelctl logs search -l error -r 1h',
     '',
@@ -130,35 +132,48 @@ const agentGuide = `Using sentinelctl from AI agents and scripts
    · 3 not logged in or insufficient role (do not retry). GET requests that hit 429 are retried
    automatically after Retry-After.
 4. \`sentinelctl commands --json\` returns every command with its options, choices, required role,
-   whether it changes data, examples and output fields.
-5. Typical investigation
+   whether it changes data, examples and output fields; \`commands logs --json\` or
+   \`commands "logs stats" --json\` returns only that part.
+5. Typical investigation (start broad, then narrow)
+   - overview:       fleet summary -o json                      (~5KB: status, attention, busiest devices,
+                                                                 log levels, top/rising/new error patterns)
+   - what changed:   logs stats -l error -r 24h --by message --compare --sort change -o json
+   - fleet metrics:  metrics top memory -r 7d -o json           (ranked devices + fleet distribution)
+                     metrics top disk --agg last --above 85 · metrics top cpu --agg p95 --compare
+                     metrics top reboots -r 7d --above 0
    - find a device:  devices lookup <part of name>            -> agentId
-   - status:         devices list --status offline -o json | devices overview <id> -o json
-   - metrics:        devices show <id> -r 24h -o json           (series.cpu etc. are [epochSeconds, value])
-   - logs:           logs search -a <id> -l error -r 24h -o ndjson
+   - status:         devices list --focus attention --all -o json --select agentId,displayName,status,attentionReasons
+                     devices overview <id> -o json
+   - metrics:        devices show <id> -r 24h -o json --series cpu,memory   (series are [epochSeconds, value])
+   - logs:           logs search -q "<searchText from logs stats>" -r 24h -o ndjson
+                     logs search -a <id> -l error -r 24h -o ndjson
                      then logs context -a <id> -s <source> -t <timestamp> for surrounding lines
    - counts/ranking: logs stats -l error -r 24h --by agent|source|message -o json
    - trend:          logs histogram -a <id> -r 7d -o json
 6. Efficiency
-   - To answer "how many" or "which devices/sources the most", use logs stats: one server-side
-     aggregation with exact counts. Do not download thousands of logs to count them.
+   - Prefer aggregates: fleet summary, logs stats and metrics top answer "how many", "which the most"
+     and "what changed" in one server-side query. Do not download thousands of logs or call
+     devices show per device to compute fleet-wide numbers.
+   - Keep JSON small: --select <fields> keeps only the fields you need (devices list --all -o json is
+     ~700KB without it, ~20KB with a few fields); devices show --series none drops time series.
    - Narrow the window and filters (-a, -s, -l, -q) first. Use --pages N (max 40) to take only what you
      need; --all stops at 10,000 logs.
-   - Each user can run 2 log queries at a time (web and CLI combined); run commands one after another.
+   - Each user can run 2 log queries and 2 metric aggregations at a time (web and CLI combined); run
+     commands one after another.
    - Do not use --follow (it never ends). Repeat a -r 15m search instead.
-   - The server caches identical log searches for 5s, histograms and sources for 60s.
+   - The server caches identical log searches for 5s; stats, histograms, sources and metrics top for 60s.
 7. For commands that change data (metadata set/bulk/rollback/import, admin ...), run with --dry-run
    first when available, check the result, then apply.
 8. Server error messages are in Korean (shared with the web console); the "hint" field is English.`;
 
-function commandsCatalog() {
+function commandsCatalog(selected = null) {
   return {
     version,
     globalOptions: globalDefinitions,
     exitCodes,
     commands: [
-      ...Object.entries(specialCommands).map(([name, command]) => ({ command: name, usage: command.usage, summary: command.summary, role: null, mutates: name === 'logout' })),
-      ...catalog.map((command) => ({
+      ...(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, {
@@ -329,10 +344,13 @@ export async function main(argv, {
       return 0;
     }
     if (name === 'commands') {
+      const scope = [subcommand, ...commandArguments].filter(Boolean).join(' ');
+      const selected = catalog.filter((item) => !scope || commandPath(item) === scope || item.group === scope);
+      if (scope && !selected.length) throw unknownCommandError(scope, [...Object.keys(groups), ...catalog.map(commandPath)], 'commands ');
       if (global.output === 'table') {
-        out(catalog.map((item) => `${commandPath(item).padEnd(20)} ${item.role.padEnd(7)} ${item.mutates ? 'write' : 'read '}  ${item.summary}`).join('\n'));
+        out(selected.map((item) => `${commandPath(item).padEnd(20)} ${item.role.padEnd(7)} ${item.mutates ? 'write' : 'read '}  ${item.summary}`).join('\n'));
       } else {
-        out(JSON.stringify(commandsCatalog(), null, global.output === 'json' ? 2 : 0));
+        out(JSON.stringify(commandsCatalog(scope ? selected : null), null, global.output === 'json' ? 2 : 0));
       }
       return 0;
     }
@@ -365,6 +383,7 @@ export async function main(argv, {
       path: credentialsPath(environment) });
     context = {
       global, connection, out, err, fetch, sleep, signal, openBrowser: open, width: stdout.columns ?? 120,
+      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 }),