@intflow/sentinelctl 0.3.2 → 0.5.0

package/README.md

@@ -38,29 +38,51 @@ 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.
 
-## Logs
+## Fleet overview and metrics
 
 ```bash
-sentinelctl logs search timeout -r 1h
-sentinelctl logs search -a <agent-id> -l error -r 24h --all
-sentinelctl logs search -s sshd.service --from 2026-09-30T00:00:00Z --to 2026-09-30T06:00:00Z
-sentinelctl logs search -l error -f                        # follow new errors (Ctrl+C to stop)
-sentinelctl logs search -q boom -o ndjson | jq .message
+sentinelctl fleet summary                                   # status, offline split, attention, busiest devices, trends, log levels, error patterns
+sentinelctl fleet summary -r 1h -o json                     # about 10KB
+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 diskDaysLeft --below 14             # disks that fill up within two weeks at the current growth
+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
+```
+
+`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.
+
+## Logs: count first, read last
+
+```bash
+sentinelctl logs stats -l error -r 24h --by message --compare        # which patterns, what changed
+sentinelctl logs groups -l error -r 24h                              # every device x source x pattern, with count, first/last and latest line
+sentinelctl logs stats -p "<pattern>" --by agent --timeline -r 7d    # where and since when
+sentinelctl logs search -p "<pattern>" -a <agent-id> -r 24h -n 50    # a few raw lines
 sentinelctl logs context -a <agent-id> -s app.service -t 2026-09-30T01:02:03.456Z
-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 facets -l error -r 24h                              # top devices, sources, severities at a glance
+sentinelctl logs histogram -a <agent-id> -r 30d
 sentinelctl logs sources -r 24h
+sentinelctl logs stats --service payment-api --env prod -l error -r 7d --by message   # one application across devices (needs service/env labels)
+sentinelctl logs stats -l error -r 24h --by service
+sentinelctl logs search -l error --since <nextSince> -o ndjson       # poll only new logs
 ```
 
-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.
+- `logs search` returns at most 10,000 lines (250 per request, `--pages N` up to 40 or `--all`). On a busy fleet that covers minutes, so never download logs to count or summarize them: `logs stats` and `logs groups` count every log in the window on the server.
+- `-p/--pattern` takes a pattern exactly as `logs stats --by message` or `logs groups` print it (numbers as `<N>`) and matches only that pattern. `-q` matches words case-insensitively; add `--case-sensitive` for a much faster exact-case match.
+- `--dedupe` folds lines repeated within the same second; `--collapse` on `logs search` is the same as `logs groups`.
+- Windows: `15m`, `1h`, `6h`, `24h`, `7d`, `30d` or `--from/--to` up to the retention period (31 days by default). Fleet-wide aggregations over 7 days need `-a`, `-s`, `-p` or `--case-sensitive`; the server answers `log_query_too_broad` otherwise.
+- Aggregations over a day are computed per day and finished days are cached, so repeating a long query is cheap; the CLI continues automatically when the server needs several requests.
+- Levels: `emergency`, `critical` and `error` include more severe levels; `warning`, `info` (with notice) and `debug` match that level only.
+- `--fields` (raw fields) is admin-only and audited. `--follow` polls at most every 5 seconds and is meant for humans.
 
-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) and spend 60 seconds of log query time per minute; GET requests that get 429 retry automatically with backoff.
 
 ## Devices and metadata
 
@@ -101,6 +123,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.5.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,10 +1,10 @@
 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' };
 export const outputChoices = ['table', 'json', 'ndjson'];
-const logRanges = ['15m', '1h', '6h', '24h', '7d'];
+const logRanges = ['15m', '1h', '6h', '24h', '7d', '30d'];
 const deviceRanges = ['30m', '1h', '6h', '24h', '7d', '30d'];
 const logLevels = ['emergency', 'critical', 'error', 'warning', 'info', 'debug'];
 const deviceStatuses = ['all', 'online', 'delayed', 'offline', 'unknown', 'maintenance', 'retired'];
@@ -13,15 +13,29 @@ 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: 'Case-insensitive text in the message. Positional words are appended.' },
+  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: 'This severity and above (error includes emergency/alert/critical).' },
+  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; at most 30 days.' },
+  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.' },
 };
 
+async function getComplete(context, path, query) {
+  let body = await context.client.get(path, query);
+  for (let round = 0; body.complete === false && round < 20; round += 1) {
+    context.note(`Aggregating step ${body.coverage?.done ?? 0}/${body.coverage?.chunks ?? '?'}, continuing…`);
+    body = await context.client.get(path, query);
+  }
+  if (body.complete === false) context.hint(`Partial result: ${body.coverage?.done}/${body.coverage?.chunks} steps aggregated. Run the same command again to continue (finished days are cached).`);
+  return body;
+}
+
 function logCriteria(options, positionals) {
   const text = [options.query, ...positionals].filter(Boolean).join(' ');
   if ((options.from && !options.to) || (!options.from && options.to)) {
@@ -33,18 +47,51 @@ function logCriteria(options, positionals) {
       throw new UsageError(`Cannot parse --${name}: ${value}`, { hint: 'Use ISO 8601, e.g. 2026-09-30T09:00:00+09:00.' });
     }
   }
+  if (options['case-sensitive'] && !text) throw new UsageError('--case-sensitive needs search text (-q).');
   return {
-    q: text || undefined, agentId: options.agent, level: options.level, source: options.source,
+    q: text || undefined, agentId: options.agent, level: options.level, source: options.source, service: options.service, env: options.env,
+    pattern: options.pattern, match: options['case-sensitive'] ? 'exact' : undefined,
     range: options.from ? undefined : (options.range ?? '15m'),
     from: options.from ? new Date(options.from).toISOString() : undefined,
     to: options.to ? new Date(options.to).toISOString() : undefined,
   };
 }
 
+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());
 }
 
@@ -63,14 +110,43 @@ function logKey(log) {
 function emptyLogHint(criteria) {
   const tips = [];
   if (criteria.range && criteria.range !== '7d') tips.push('widen the window (-r 24h or -r 7d)');
-  if (criteria.q) tips.push('shorten or drop the search text');
+  if (criteria.q) tips.push(criteria.match === 'exact' ? 'drop --case-sensitive' : 'shorten or drop the search text');
+  if (criteria.pattern) tips.push('check the pattern with `sentinelctl logs stats --by message`');
   if (criteria.source) tips.push('check source names with `sentinelctl logs sources -r 24h`');
   if (criteria.agentId) tips.push('check the agent ID with `sentinelctl devices lookup <name>`');
   if (criteria.level) tips.push('drop -l');
   return tips.length ? `No logs matched. Try: ${tips.join('; ')}.` : 'No logs matched.';
 }
 
+function timestampNanos(value) {
+  const match = /^(\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2})(?:\.(\d{1,9}))?(Z|[+-]\d{2}:\d{2})$/.exec(String(value));
+  if (!match) return BigInt(Date.parse(value)) * 1_000_000n;
+  return BigInt(Date.parse(`${match[1]}${match[3]}`)) * 1_000_000n + BigInt((match[2] ?? '').padEnd(9, '0'));
+}
+
+function dedupeLogs(logs) {
+  const result = [];
+  for (const log of logs) {
+    const previous = result.at(-1);
+    const sameSecond = previous && String(previous.timestamp).slice(0, 19) === String(log.timestamp).slice(0, 19);
+    const strip = (message) => String(message).replace(/^\[[^\]]+\]\s*/, '');
+    if (sameSecond && previous.agentId === log.agentId && previous.source === log.source && strip(previous.message) === strip(log.message)) {
+      previous.repeat = (previous.repeat ?? 1) + 1;
+      continue;
+    }
+    result.push({ ...log });
+  }
+  return result;
+}
+
 async function logsSearch(context, { options, positionals }) {
+  if (options.collapse) return logsGroups(context, { options, positionals });
+  if (options.since) {
+    if (options.from || options.to || options.range) throw new UsageError('--since cannot be combined with --range/--from/--to.');
+    if (!Number.isFinite(Date.parse(options.since))) throw new UsageError(`Cannot parse --since: ${options.since}`, { hint: 'Pass the nextSince value printed by the previous run.' });
+    options.from = options.since;
+    options.to = new Date().toISOString();
+  }
   const criteria = logCriteria(options, positionals);
   const paging = options.all || options.pages > 1;
   const limit = options.fields ? 50 : (options.limit ?? (paging ? 250 : 100));
@@ -89,11 +165,17 @@ 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 }));
+  if (options.since) {
+    const since = timestampNanos(options.since);
+    for (let index = logs.length - 1; index >= 0; index -= 1) if (timestampNanos(logs[index].timestamp) <= since) logs.splice(index, 1);
   }
+  const shown = options.dedupe ? dedupeLogs(logs) : logs;
+  const nextSince = logs[0]?.timestamp ?? options.since ?? null;
+  emit(context, context.global.output === 'json'
+    ? { criteria: last.criteria, window: last.window, count: logs.length, ...(options.dedupe ? { rows: shown.length } : {}), hasMore: last.hasMore, ...(options.since ? { nextSince } : {}), logs: shown }
+    : shown,
+  () => renderTable(shown, options.dedupe ? [...logColumns.slice(0, 4), { header: 'x', value: (log) => (log.repeat ? `×${log.repeat}` : ''), max: 5 }, logColumns[4]] : logColumns, { width: context.width, wide: options.wide }));
+  if (options.since) context.hint(`Next time: --since ${nextSince}`);
   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.`);
@@ -129,23 +211,208 @@ async function followLogs(context, query, options) {
 }
 
 
-const statsDimensions = ['source', 'agent', 'level', 'message'];
+const statsDimensions = ['source', 'agent', 'level', 'message', 'service'];
+
+const sparkBlocks = ['▁', '▂', '▃', '▄', '▅', '▆', '▇', '█'];
+
+function sparkline(points, window, step) {
+  if (!points?.length || !step) return '';
+  const start = Math.floor(Date.parse(window.start) / 1000 / step) * step;
+  const end = Date.parse(window.end) / 1000;
+  const counts = new Map(points);
+  const values = [];
+  for (let at = start; at < end; at += step) values.push(counts.get(at) ?? 0);
+  const peak = Math.max(1, ...values);
+  return values.map((value) => (value ? sparkBlocks[Math.min(7, Math.floor((value / peak) * 7.999))] : ' ')).join('');
+}
+
+function quoteArgument(text) {
+  return `"${String(text).replaceAll('\\', '\\\\').replaceAll('"', '\\"')}"`;
+}
+
+function narrowingHint(criteria) {
+  const window = criteria.range ? `-r ${criteria.range}` : `--from ${criteria.from} --to ${criteria.to}`;
+  return { window, level: criteria.level ? ` -l ${criteria.level}` : '' };
+}
 
 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 });
-  const label = { source: 'SOURCE', agent: 'DEVICE', level: 'LEVEL', message: 'MESSAGE PATTERN' }[body.criteria.by];
+  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 getComplete(context, '/api/logs/stats', {
+    ...criteria, by: options.by, top: options.top, compare: options.compare ? 1 : undefined, sort: options.sort, timeline: options.timeline ? 1 : undefined,
+  });
+  const label = { source: 'SOURCE', agent: 'DEVICE', level: 'LEVEL', message: 'MESSAGE PATTERN', service: 'SERVICE' }[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.timelineStepSeconds ? [{ header: 'TREND', value: (group) => sparkline(group.timeline, body.window, body.timelineStepSeconds), max: 48 }] : []),
+    ...(body.timelineStepSeconds ? [{ header: 'LAST', value: (group) => (group.last ? localTime(group.last).slice(5, 16) : '-'), max: 11 }] : []),
     ...(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.timelineStepSeconds) context.note(`TREND: one column per ${Math.round(body.timelineStepSeconds / 60)} min; first/last (bucket precision) are in -o json.`);
+  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.count > 0);
+  if (body.criteria.by === 'message' && sample) {
+    const { window, level } = narrowingHint(criteria);
+    context.hint(`Next: who and where → sentinelctl logs groups -p ${quoteArgument(sample.key)} ${window}${level}; raw lines → sentinelctl logs search -p ${quoteArgument(sample.key)} ${window} -n 50`);
+  }
+}
+
+const groupColumns = [
+  { header: 'COUNT', value: (group) => String(group.count) },
+  { header: 'LAST', value: (group) => (group.last ? localTime(group.last).slice(5, 16) : '-'), max: 11 },
+  { header: 'DEVICE', value: (group) => group.displayName ?? group.agentId, max: 26 },
+  { header: 'SOURCE', value: (group) => group.source, max: 22 },
+  { header: 'PATTERN', value: (group) => group.pattern },
+];
+
+async function logsGroups(context, { options, positionals }) {
+  const criteria = logCriteria(options, positionals);
+  const body = await getComplete(context, '/api/logs/groups', { ...criteria, top: options.top ?? options.limit });
+  emit(context, context.global.output === 'ndjson' ? body.groups : body, () => renderTable(body.groups, groupColumns, { width: context.width, wide: options.wide }));
+  context.note(`${body.total} logs in ${body.groupCount} groups (${body.patternCount} patterns, ${body.devices} devices) · ${localTime(body.window.start)} → ${localTime(body.window.end)}`);
+  if (body.truncated) context.hint(`Showing ${body.groups.length} of ${body.groupCount} groups, largest first. Raise --top (max 500) or add filters.`);
+  if (body.approximate) context.hint('Patterns are approximate on this server (collapse_nums is unavailable).');
+  if (!body.total) context.hint(emptyLogHint(criteria));
+  const first = body.groups[0];
+  if (first) {
+    const { window } = narrowingHint(criteria);
+    context.hint(`Each group keeps its latest line in -o json (latest.message). Raw lines of one group: sentinelctl logs search -a ${first.agentId} -p ${quoteArgument(first.pattern)} ${window} -n 50`);
+  }
+}
+
+async function logsFacets(context, { options, positionals }) {
+  const criteria = logCriteria({ ...options, range: options.range ?? (options.from ? undefined : '1h') }, positionals);
+  const body = await context.client.get('/api/logs/facets', { ...criteria, top: options.top });
+  emit(context, body, () => Object.entries(body.facets).map(([field, values]) => `${field}:\n${values
+    .map((item) => `  ${String(item.count).padStart(9)}  ${item.displayName && item.displayName !== item.value ? `${item.displayName} (${item.value})` : item.value}`).join('\n')}`).join('\n'));
+  context.note(`${localTime(body.window.start)} → ${localTime(body.window.end)}`);
+}
+
+const metricNames = ['cpu', 'memory', 'disk', 'swap', 'load', 'temperature', 'processes', 'tcpConnections', 'networkRx', 'networkTx', 'reboots', 'diskDaysLeft'];
+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, trends: options.trends === 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');
+    const offline = body.devices.offline;
+    if (offline) {
+      sections.push('', `Offline: ${offline.within24h.length} within 24h${offline.within24h.length ? ` (${offline.within24h.map((device) => `${device.displayName} ${device.offlineHours}h`).join(', ')})` : ''} · ${offline.otherCount} for 1-7 days · ${offline.over7dCount} over 7 days`);
+    }
+    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.trends?.error) sections.push('', `Trends: ${body.trends.error}`);
+    else if (body.trends) {
+      const list = (devices, format) => devices.map((device) => `${device.displayName} ${format(device)}`).join(', ') || 'none';
+      sections.push('', 'Trends:', renderKeyValues([
+        ['disk full <14d', list(body.trends.diskFullWithin14Days, (device) => `${device.value}d`)],
+        ['temperature +15°C', list(body.trends.temperatureRise, (device) => `${device.previous}→${device.value}°C`)],
+        [`reboots >${body.trends.rebootOutliers.threshold}/7d`, `${list(body.trends.rebootOutliers.devices, (device) => `${device.value}`)} (typical ${body.trends.rebootOutliers.typicalPerWeek}/7d)`],
+      ]));
+    }
+    if (body.logs?.complete === false) sections.push('', 'Logs: partial (some days still aggregating); run again to complete.');
+    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: logs groups -l error -r 24h · logs stats -l error --by message --compare --timeline · metrics top diskDaysLeft · devices overview <id>');
 }
 
 async function logsContext(context, { options }) {
@@ -163,7 +430,7 @@ async function logsContext(context, { options }) {
 }
 
 async function logsHistogram(context, { options, positionals }) {
-  const body = await context.client.get('/api/logs/histogram', logCriteria(options, positionals));
+  const body = await getComplete(context, '/api/logs/histogram', logCriteria(options, positionals));
   emit(context, context.global.output === 'ndjson' ? body.buckets : body, () => {
     const peak = Math.max(1, ...body.buckets.map((bucket) => bucket.total));
     return renderTable(body.buckets, [
@@ -182,7 +449,7 @@ async function logsSources(context, { options }) {
     { header: 'SOURCE', value: (source) => source.value },
     { header: 'COUNT', value: (source) => String(source.count) },
   ], { width: context.width }));
-  context.note(`Top sources in a sample of the latest ${body.sampleSize} logs.`);
+  context.note(`Top ${body.sources.length} sources by exact count over ${body.range} (${body.total} logs).`);
 }
 
 const deviceColumns = [
@@ -217,11 +484,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 +499,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 +514,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,14 +815,14 @@ 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 = [
   {
     group: 'logs', name: 'search', run: logsSearch, role: 'viewer', mutates: false,
-    summary: 'Search logs by window, device, severity, source and text; or follow live',
-    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. To count or rank logs, use `logs stats` instead.',
+    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`).',
     args: [{ name: 'text', optional: true, description: 'Same as -q (words are joined with spaces).' }],
     options: {
       ...logFilterOptions,
@@ -562,6 +830,10 @@ const commands = [
       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.' },
@@ -570,30 +842,67 @@ const commands = [
     roleNote: '--fields requires admin',
     examples: [
       'sentinelctl logs search -l error -r 1h',
+      'sentinelctl logs search -p "tegra-xusb <N>.usb: not all ports suspended: -<N>" -r 24h -n 50 -o json',
+      'sentinelctl logs search -l error -r 24h --collapse -o json',
+      'sentinelctl logs search -l error --since 2026-09-30T01:02:03.456789Z -o ndjson',
       'sentinelctl logs search "connection reset" -r 24h -o ndjson',
       '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). -o json wraps them as {criteria, window, count, hasMore, logs}.',
+    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}.',
   },
   {
     group: 'logs', name: 'stats', run: logsStats, role: 'viewer', mutates: false,
-    summary: 'Count and rank logs by source, device, severity or message pattern (one server-side query)',
-    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>. Cached for 60s on the server.',
+    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.',
     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 or message pattern.' },
+      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.' },
     },
     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 -l error -r 7d --by message --timeline --top 10',
       '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, 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)}.',
+  },
+  {
+    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.',
+    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.' },
+    },
+    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}}}.',
+  },
+  {
+    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.',
+    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[], …}}.',
   },
   {
     group: 'logs', name: 'context', run: logsContext, role: 'viewer', mutates: false,
@@ -615,15 +924,15 @@ const commands = [
     summary: 'Log volume and error counts over time',
     args: [{ name: 'text', optional: true, description: 'Same as -q.' }],
     options: logFilterOptions,
-    examples: ['sentinelctl logs histogram -r 24h', 'sentinelctl logs histogram -a <agent-id> -r 7d -o json'],
-    output: '{start, end, stepSeconds, total, buckets[]: {at (epoch seconds), total, errors}}. Cached for 60s on the server.',
+    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.',
   },
   {
     group: 'logs', name: 'sources', run: logsSources, role: 'viewer', mutates: false,
-    summary: 'Log sources (systemd units, containers) seen recently',
+    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, sampleSize, sources[]: {value, count}}: top 50 in a sample of the latest 250 logs.',
+    output: '{range, total, complete, sources[]: {value, count}}: top 50 by exact count.',
   },
   {
     group: 'devices', name: 'list', run: devicesList, role: 'viewer', mutates: false,
@@ -657,9 +966,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 +988,54 @@ 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 (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.',
+    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'], 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).' },
+      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 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?}}.',
+  },
+  {
+    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.',
+    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).' },
+    },
+    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[]}}.',
+  },
   {
     group: 'metadata', name: 'get', run: metadataGet, role: 'viewer', mutates: false,
     summary: 'Device metadata: name, role, maintainer, labels, lifecycle',
@@ -813,7 +1171,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: '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',
   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',
     '',
@@ -119,46 +121,76 @@ function overviewHelp() {
 
 const agentGuide = `Using sentinelctl from AI agents and scripts
 
-1. A human logs in once: \`sentinelctl login\` and approve in the browser. The token lasts 30 days;
-   every later command is non-interactive. The token carries the logged-in user's role, so log in
-   with a viewer account for agents that should only read. Elsewhere, pass SENTINEL_TOKEN and
-   SENTINEL_URL as environment variables.
-2. Use -o json (one document) or -o ndjson (one item per line). stdout carries data only; summaries,
-   hints and errors go to stderr. --quiet drops summaries and hints. With json/ndjson output an error
-   is one stderr line: {"error":{"status","code","message","hint","exitCode"}}.
-3. Exit codes: 0 success · 1 server/network error · 2 usage error (fix the arguments and retry)
-   · 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
-   - 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
-                     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.
-   - 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.
-   - 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.
-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.`;
+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.
 
-function commandsCatalog() {
+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)
+
+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.
+
+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.
+
+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.
+
+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 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, {
@@ -267,6 +299,15 @@ 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 === '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.';
+  }
+  if (error.code === 'log_budget_exceeded') {
+    return `Your log query time for this minute is used up${error.retryAfterSeconds ? `; wait ${error.retryAfterSeconds}s` : ''}. Prefer logs stats/groups with filters over repeated wide searches.`;
+  }
+  if (error.status === 504) {
+    return 'The log/metric backend timed out. Narrow the window or add -a/-s/-l, use -p "<pattern>" instead of -q, or add --case-sensitive. Long aggregations resume from cache if you rerun.';
+  }
   if (error.status === 429) return `Too many requests${error.retryAfterSeconds ? `; wait ${error.retryAfterSeconds}s` : ''} and retry. Narrower filters reduce load.`;
   if ([400, 413, 415, 422].includes(error.status)) {
     return command ? `Check the input: sentinelctl ${commandPath(command)} --help` : 'Check the input.';
@@ -329,10 +370,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 +409,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 }),