@intflow/sentinelctl 0.1.0 → 0.3.0

package/src/commands.mjs

@@ -1,29 +1,43 @@
 import { readFile, writeFile } from 'node:fs/promises';
-import { keyValue, parseArguments, UsageError } from './args.mjs';
+import { keyValue, UsageError } from './args.mjs';
 import { ageText, localTime, percentText, renderKeyValues, renderTable, singleLine } from './format.mjs';
 
-const roleLabels = { viewer: '조회 전용', editor: '편집 가능', admin: '관리자' };
-const outputChoices = ['table', 'json', 'ndjson'];
+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 deviceRanges = ['30m', '1h', '6h', '24h', '7d', '30d'];
 const logLevels = ['emergency', 'critical', 'error', 'warning', 'info', 'debug'];
+const deviceStatuses = ['all', 'online', 'delayed', 'offline', 'unknown', 'maintenance', 'retired'];
+const lifecycles = ['operational', 'all', 'active', 'maintenance', 'retired'];
+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' },
-  agent: { alias: 'a', type: 'string' },
-  level: { alias: 'l', type: 'string', choices: logLevels },
-  source: { alias: 's', type: 'string' },
-  range: { alias: 'r', type: 'string', choices: logRanges },
-  from: { type: 'string' },
-  to: { type: 'string' },
+  query: { alias: 'q', type: 'string', placeholder: 'text', description: 'Case-insensitive text in the message. Positional words are appended.' },
+  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).' },
+  source: { alias: 's', type: 'string', placeholder: 'source', description: 'Exact source: systemd unit, container name, syslog identifier (see `logs sources`).' },
+  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.' },
+  to: { type: 'string', placeholder: 'ISO', description: 'Absolute window end.' },
 };
 
 function logCriteria(options, positionals) {
   const text = [options.query, ...positionals].filter(Boolean).join(' ');
-  if ((options.from && !options.to) || (!options.from && options.to)) throw new UsageError('--from과 --to는 함께 지정해야 합니다.');
-  if (options.from && options.range) throw new UsageError('--range와 --from/--to는 함께 쓸 수 없습니다.');
+  if ((options.from && !options.to) || (!options.from && options.to)) {
+    throw new UsageError('--from and --to must be given together.', { hint: 'For a recent window use --range, e.g. -r 1h.' });
+  }
+  if (options.from && options.range) throw new UsageError('--range cannot be combined with --from/--to.');
+  for (const [name, value] of [['from', options.from], ['to', options.to]]) {
+    if (value && !Number.isFinite(Date.parse(value))) {
+      throw new UsageError(`Cannot parse --${name}: ${value}`, { hint: 'Use ISO 8601, e.g. 2026-09-30T09:00:00+09:00.' });
+    }
+  }
   return {
     q: text || undefined, agentId: options.agent, level: options.level, source: options.source,
-    range: options.from ? undefined : (options.range ?? '15m'), from: options.from, to: options.to,
+    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,
   };
 }
 
@@ -35,63 +49,68 @@ function emit(context, value, table) {
 }
 
 const logColumns = [
-  { header: '시각', value: (log) => localTime(log.timestamp), max: 19 },
-  { header: '수준', value: (log) => log.severity, max: 9 },
-  { header: '장비', value: (log) => log.displayName ?? log.host ?? log.agentId, max: 24 },
-  { header: '출처', value: (log) => log.source, max: 22 },
-  { header: '메시지', value: (log) => log.message },
+  { header: 'TIME', value: (log) => localTime(log.timestamp), max: 19 },
+  { header: 'LEVEL', value: (log) => log.severity, max: 9 },
+  { header: 'DEVICE', value: (log) => log.displayName ?? log.host ?? log.agentId, max: 24 },
+  { header: 'SOURCE', value: (log) => log.source, max: 22 },
+  { header: 'MESSAGE', value: (log) => log.message },
 ];
 
 function logKey(log) {
   return `${log.timestamp}\n${log.agentId}\n${log.source}\n${log.message}`;
 }
 
-async function logsSearch(context, argv) {
-  const { options, positionals } = parseArguments(argv, {
-    ...logFilterOptions,
-    limit: { alias: 'n', type: 'integer', choices: [50, 100, 250], default: 100 },
-    pages: { type: 'integer', default: 1 },
-    all: { type: 'boolean' },
-    fields: { type: 'boolean' },
-    follow: { alias: 'f', type: 'boolean' },
-    interval: { type: 'integer', default: 5 },
-    wide: { alias: 'w', type: 'boolean' },
-  });
-  const criteria = { ...logCriteria(options, positionals), limit: options.fields ? 50 : options.limit, includeFields: options.fields ? 1 : undefined };
-  if (options.follow) return followLogs(context, criteria, options);
-  const maxPages = options.all ? 200 : Math.max(1, options.pages);
+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.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.';
+}
+
+async function logsSearch(context, { options, positionals }) {
+  const criteria = logCriteria(options, positionals);
+  const paging = options.all || options.pages > 1;
+  const limit = options.fields ? 50 : (options.limit ?? (paging ? 250 : 100));
+  const query = { ...criteria, limit, includeFields: options.fields ? 1 : undefined };
+  if (options.follow) return followLogs(context, query, options);
+  if (options.pages !== undefined && (options.pages < 1 || options.pages > maxPages)) {
+    throw new UsageError(`--pages must be between 1 and ${maxPages}.`, { hint: 'For counts over large windows use `sentinelctl logs stats` instead of fetching logs.' });
+  }
+  const pageBudget = options.all ? maxPages : (options.pages ?? 1);
   const logs = [];
   let cursor;
   let last;
-  for (let page = 0; page < maxPages; page += 1) {
-    last = await context.client.get('/api/logs', { ...criteria, cursor });
+  for (let page = 0; page < pageBudget; page += 1) {
+    last = await context.client.get('/api/logs', { ...query, cursor });
     logs.push(...last.logs);
     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));
-    return;
-  }
-  emit(context, logs, () => renderTable(logs, logColumns, { width: context.width, wide: options.wide }));
-  if (context.global.output === 'table') {
-    context.err(`${logs.length}건${last.hasMore ? ' · 더 있음 (--pages N 또는 --all)' : ''} · ${localTime(last.window.start)} ~ ${localTime(last.window.end)}`);
+  } else {
+    emit(context, 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.`);
+  else if (last.hasMore) context.hint('More logs match. Continue with --pages N or --all (up to 10,000), narrow the filters, or count them with `sentinelctl logs stats`.');
 }
 
-async function followLogs(context, criteria, options) {
+async function followLogs(context, query, options) {
   const seen = new Set();
-  const intervalMs = Math.max(2, options.interval) * 1_000;
-  // 한 번에 가져올 수 있는 최대치를 쓴다. 그래도 가져온 로그가 직전 결과와 전혀 겹치지 않으면
-  // 간격 사이에 더 많은 로그가 들어와 일부를 건너뛴 것이므로 알린다.
-  const followCriteria = { ...criteria, range: '15m', from: undefined, to: undefined, limit: criteria.includeFields ? 50 : 250 };
+  const intervalMs = Math.max(5, options.interval) * 1_000;
+  const followQuery = { ...query, range: '15m', from: undefined, to: undefined, limit: query.includeFields ? 50 : 250 };
   let first = true;
-  context.err('새 로그를 기다립니다. Ctrl+C로 종료합니다.');
+  context.err('Following new logs. Press Ctrl+C to stop.');
   while (!context.signal?.aborted) {
-    const body = await context.client.get('/api/logs', followCriteria);
+    const body = await context.client.get('/api/logs', followQuery);
     const fresh = body.logs.filter((log) => !seen.has(logKey(log))).reverse();
     if (!first && body.hasMore && fresh.length === body.logs.length) {
-      context.err(`경고: ${options.interval}초 사이에 ${followCriteria.limit}건보다 많은 로그가 들어와 일부를 건너뛰었습니다. -a/-s/-l/-q로 범위를 좁히거나 --interval을 줄이세요.`);
+      context.err(`warning: more than ${followQuery.limit} logs arrived within ${options.interval}s and some were skipped. Narrow with -a/-s/-l/-q or lower --interval.`);
     }
     for (const log of body.logs) seen.add(logKey(log));
     if (seen.size > 20_000) for (const key of [...seen].slice(0, seen.size - 10_000)) seen.delete(key);
@@ -109,62 +128,75 @@ async function followLogs(context, criteria, options) {
   }
 }
 
-async function logsContext(context, argv) {
-  const { options } = parseArguments(argv, {
-    agent: { alias: 'a', type: 'string' }, source: { alias: 's', type: 'string' }, timestamp: { alias: 't', type: 'string' },
-    before: { type: 'integer' }, after: { type: 'integer' }, window: { type: 'integer' }, wide: { alias: 'w', type: 'boolean' },
-  });
-  if (!options.agent || !options.source || !options.timestamp) throw new UsageError('--agent, --source, --timestamp가 필요합니다.');
+
+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 });
+  const label = { source: 'SOURCE', agent: 'DEVICE', level: 'LEVEL', message: 'MESSAGE PATTERN' }[body.criteria.by];
+  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)}%` : '-') },
+    { 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.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));
+}
+
+async function logsContext(context, { options }) {
+  if (!options.agent || !options.source || !options.timestamp) {
+    throw new UsageError('--agent, --source and --timestamp are all required.',
+      { hint: 'Copy agentId, source and timestamp from `logs search -o json` output.' });
+  }
   const body = await context.client.get('/api/logs/context', {
     agentId: options.agent, source: options.source, timestamp: options.timestamp,
     before: options.before, after: options.after, windowSeconds: options.window,
   });
   emit(context, context.global.output === 'ndjson' ? body.logs : body,
     () => renderTable(body.logs, logColumns, { width: context.width, wide: options.wide }));
+  if (!body.count) context.hint('No logs from that device and source around the timestamp. Try a larger --window (up to 3600).');
 }
 
-async function logsHistogram(context, argv) {
-  const { options, positionals } = parseArguments(argv, logFilterOptions);
+async function logsHistogram(context, { options, positionals }) {
   const body = await context.client.get('/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, [
-      { header: '시각', value: (bucket) => localTime(bucket.at) },
-      { header: '전체', value: (bucket) => String(bucket.total) },
-      { header: '오류', value: (bucket) => String(bucket.errors) },
+      { header: 'TIME', value: (bucket) => localTime(bucket.at) },
+      { header: 'TOTAL', value: (bucket) => String(bucket.total) },
+      { header: 'ERRORS', value: (bucket) => String(bucket.errors) },
       { header: '', value: (bucket) => '█'.repeat(Math.round((bucket.total / peak) * 30)) },
     ], { width: context.width, wide: true });
   });
+  context.note(`${body.total} logs in ${body.buckets.length} buckets of ${body.stepSeconds}s`);
 }
 
-async function logsSources(context, argv) {
-  const { options } = parseArguments(argv, { range: { alias: 'r', type: 'string', choices: logRanges, default: '24h' } });
+async function logsSources(context, { options }) {
   const body = await context.client.get('/api/logs/sources', { range: options.range });
   emit(context, context.global.output === 'ndjson' ? body.sources : body, () => renderTable(body.sources, [
-    { header: '출처', value: (source) => source.value },
-    { header: '건수', value: (source) => String(source.count) },
+    { 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.`);
 }
 
 const deviceColumns = [
-  { header: '에이전트 ID', value: (device) => device.agentId, max: 28 },
-  { header: '이름', value: (device) => device.displayName ?? device.host, max: 28 },
-  { header: '상태', value: (device) => device.status, max: 11 },
-  { header: '사이트', value: (device) => device.site, max: 14 },
+  { header: 'AGENT ID', value: (device) => device.agentId, max: 28 },
+  { header: 'NAME', value: (device) => device.displayName ?? device.host, max: 28 },
+  { header: 'STATUS', value: (device) => device.status, max: 11 },
+  { header: 'SITE', value: (device) => device.site, max: 14 },
   { header: 'CPU', value: (device) => percentText(device.cpu), max: 5 },
-  { header: '메모리', value: (device) => percentText(device.memory), max: 6 },
-  { header: '디스크', value: (device) => percentText(device.disk), max: 6 },
-  { header: '마지막 수신', value: (device) => ageText(device.ageSeconds) },
+  { header: 'MEM', value: (device) => percentText(device.memory), max: 5 },
+  { header: 'DISK', value: (device) => percentText(device.disk), max: 5 },
+  { header: 'LAST SEEN', value: (device) => ageText(device.ageSeconds) },
 ];
 
-async function devicesList(context, argv) {
-  const { options, positionals } = parseArguments(argv, {
-    query: { alias: 'q', type: 'string' }, status: { type: 'string' }, lifecycle: { type: 'string' },
-    role: { type: 'string' }, site: { type: 'string' }, group: { type: 'string' }, maintainer: { type: 'string' },
-    fleet: { type: 'string' }, focus: { type: 'string' }, inventory: { type: 'string' },
-    label: { type: 'string', multiple: true }, sort: { type: 'string' }, order: { type: 'string', choices: ['asc', 'desc'] },
-    page: { type: 'integer', default: 1 }, 'page-size': { type: 'integer', default: 50 }, all: { type: 'boolean' },
-  });
+async function devicesList(context, { options, positionals }) {
   for (const label of options.label ?? []) keyValue(label, '--label');
   const query = {
     query: [options.query, ...positionals].filter(Boolean).join(' ') || undefined,
@@ -173,124 +205,147 @@ async function devicesList(context, argv) {
     labels: options.label?.length ? JSON.stringify(options.label) : undefined, sort: options.sort, order: options.order,
     pageSize: options.all ? 100 : options['page-size'],
   };
-  const devices = [];
-  let body;
-  for (let page = options.all ? 1 : options.page; ; page += 1) {
-    body = await context.client.get('/api/devices', { ...query, page });
-    devices.push(...body.devices);
-    if (!options.all || page >= body.totalPages) break;
+  const first = await context.client.get('/api/devices', { ...query, page: options.all ? 1 : options.page });
+  const devices = [...first.devices];
+  if (options.all && first.totalPages > 1) {
+    const pages = Array.from({ length: first.totalPages - 1 }, (_, index) => index + 2);
+    const results = new Map();
+    for (let index = 0; index < pages.length; index += 4) {
+      await Promise.all(pages.slice(index, index + 4).map(async (page) => {
+        results.set(page, (await context.client.get('/api/devices', { ...query, page })).devices);
+      }));
+    }
+    for (const page of pages) devices.push(...results.get(page));
   }
   if (context.global.output === 'json') {
-    context.out(JSON.stringify({ matched: body.matched, counts: body.counts, stale: body.stale, devices }, null, 2));
-    return;
-  }
-  emit(context, devices, () => renderTable(devices, deviceColumns, { width: context.width }));
-  if (context.global.output === 'table') {
-    context.err(`${devices.length}/${body.matched}대${options.all ? '' : ` · ${body.page}/${body.totalPages} 페이지`}${body.stale ? ` · 오래된 데이터: ${body.staleReason ?? ''}` : ''}`);
+    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 }));
   }
+  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.');
+  else if (!options.all && first.totalPages > first.page) context.hint(`Next page: --page ${first.page + 1}; everything: --all`);
 }
 
-async function devicesShow(context, argv) {
-  const { options, positionals } = parseArguments(argv, { range: { alias: 'r', type: 'string', default: '6h' } });
-  const [agentId] = positionals;
-  if (!agentId) throw new UsageError('에이전트 ID가 필요합니다.');
-  const body = await context.client.get(`/api/devices/${encodeURIComponent(agentId)}`, { range: options.range });
+function requireAgentId(positionals) {
+  if (!positionals[0]) throw new UsageError('An agent ID is required.', { hint: 'Find it with `sentinelctl devices lookup <part of the name>`.' });
+  return positionals[0];
+}
+
+async function devicesShow(context, { options, positionals }) {
+  const agentId = requireAgentId(positionals);
+  const body = await context.client.get(`/api/devices/${encodeURIComponent(agentId)}`, { range: options.range, refresh: options.refresh ? 1 : undefined });
   const device = body.device;
   emit(context, body, () => renderKeyValues([
-    ['에이전트 ID', device.agentId], ['이름', device.displayName], ['호스트', device.host],
-    ['상태', device.observedStatus ?? device.status], ['마지막 수신', ageText(device.ageSeconds)],
-    ['CPU', percentText(device.cpu)], ['메모리', percentText(device.memory)], ['디스크', percentText(device.disk)],
-    ['부하', device.load], ['온도', device.temperature], ['용도', device.metadata?.role ?? device.role],
-    ['담당자', device.metadata?.maintainer], ['운영 상태', device.metadata?.lifecycle], ['메모', device.metadata?.description],
-    ['데이터', body.stale ? `오래됨 (${body.staleReason ?? ''})` : '최신'],
+    ['Agent ID', device.agentId], ['Name', device.displayName], ['Host', device.host],
+    ['Status', device.observedStatus ?? device.status], ['Last seen', ageText(device.ageSeconds)],
+    ['CPU', percentText(device.cpu)], ['Memory', percentText(device.memory)], ['Disk', percentText(device.disk)],
+    ['Load', device.load], ['Temperature', device.temperature], ['Role', device.metadata?.role ?? device.role],
+    ['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.`);
 }
 
-async function devicesLookup(context, argv) {
-  const { positionals } = parseArguments(argv, {});
+async function devicesLookup(context, { positionals }) {
+  if (!positionals.length) throw new UsageError('A search term is required.', { hint: 'Example: sentinelctl devices lookup edge-01' });
   const body = await context.client.get('/api/devices/lookup', { query: positionals.join(' ') });
   emit(context, context.global.output === 'ndjson' ? body.devices : body, () => renderTable(body.devices, [
-    { header: '에이전트 ID', value: (device) => device.agentId },
-    { header: '이름', value: (device) => device.displayName },
-    { header: '호스트', value: (device) => device.host },
+    { header: 'AGENT ID', value: (device) => device.agentId },
+    { header: 'NAME', value: (device) => device.displayName },
+    { header: 'HOST', value: (device) => device.host },
   ], { width: context.width }));
+  if (!body.devices.length) context.hint('No device matched. Try a shorter part of the name, host or ID.');
 }
 
-async function devicesOverview(context, argv) {
-  const { options, positionals } = parseArguments(argv, { range: { alias: 'r', type: 'string', default: '24h' } });
-  const [agentId] = positionals;
-  if (!agentId) throw new UsageError('에이전트 ID가 필요합니다.');
+async function devicesOverview(context, { options, positionals }) {
+  const agentId = requireAgentId(positionals);
   const body = await context.client.get(`/api/devices/${encodeURIComponent(agentId)}/overview`, { range: options.range });
-  emit(context, body, () => renderKeyValues([
-    ['에이전트 ID', body.agentId], ['이름', body.device?.displayName], ['메트릭', body.products?.metrics?.state],
-    ['로그', body.products?.logs?.state], ['주의 사유', (body.attentionReasons ?? []).join(', ') || '없음'],
-    ['관련 장비', (body.related ?? []).map((item) => item.agentId ?? item).join(', ')],
+  const summary = Object.fromEntries(['metrics', 'logs'].map((product) => {
+    const history = body.history?.products?.[product]?.summary ?? {};
+    return [product, {
+      state: body.products?.[product]?.state ?? null,
+      outages: history.incidentCount ?? null,
+      delays: history.delayedCount ?? null,
+      missingMinutes: Number.isFinite(history.missingSeconds) ? Math.round(history.missingSeconds / 60) : null,
+      longestOutageMinutes: Number.isFinite(history.longestMissingSeconds) ? Math.round(history.longestMissingSeconds / 60) : null,
+      normalRatio: Number.isFinite(history.normalRatio) ? Math.round(history.normalRatio * 1000) / 10 : null,
+    }];
+  }));
+  const describe = (item) => `${item.state ?? '-'} · ${item.outages ?? '-'} outages, ${item.missingMinutes ?? '-'} min missing (longest ${item.longestOutageMinutes ?? '-'} min), normal ${item.normalRatio ?? '-'}%`;
+  emit(context, { summary, ...body }, () => renderKeyValues([
+    ['Agent ID', body.agentId], ['Name', body.device?.displayName], ['Window', options.range],
+    ['Metrics', describe(summary.metrics)], ['Logs', describe(summary.logs)],
+    ['Attention', (body.attentionReasons ?? []).join(', ') || 'none'],
+    ['Related', (body.related ?? []).map((item) => item.agentId ?? item).join(', ')],
   ]));
 }
 
 async function health(context) {
   const body = await context.client.get('/api/health');
   emit(context, body, () => [
-    renderKeyValues([['전체', body.status], ['버전', `${body.application?.version} (${body.application?.commit})`],
-      ['관측기', body.observer?.status ?? body.observer?.state]]),
+    renderKeyValues([['Overall', body.status], ['Version', `${body.application?.version} (${body.application?.commit})`],
+      ['Observer', body.observer?.status ?? body.observer?.state]]),
     '',
     renderTable(Object.entries(body.components ?? {}), [
-      { header: '구성요소', value: ([name]) => name },
-      { header: '상태', value: ([, component]) => component.status },
-      { header: '지연', value: ([, component]) => (Number.isFinite(component.latencyMs) ? `${component.latencyMs}ms` : '-') },
-      { header: '오류', value: ([, component]) => component.error ?? '' },
+      { header: 'COMPONENT', value: ([name]) => name },
+      { header: 'STATUS', value: ([, component]) => component.status },
+      { header: 'LATENCY', value: ([, component]) => (Number.isFinite(component.latencyMs) ? `${component.latencyMs}ms` : '-') },
+      { header: 'ERROR', value: ([, component]) => component.error ?? '' },
     ], { width: context.width }),
   ].join('\n'));
+  if (body.status !== 'ok') context.hint('Some backends are unhealthy; results may be stale or empty.');
 }
 
-async function metadataGet(context, argv) {
-  const { positionals } = parseArguments(argv, {});
-  if (!positionals[0]) throw new UsageError('에이전트 ID가 필요합니다.');
-  const body = await context.client.get(`/api/devices/${encodeURIComponent(positionals[0])}/metadata`);
+async function metadataGet(context, { positionals }) {
+  const agentId = requireAgentId(positionals);
+  const body = await context.client.get(`/api/devices/${encodeURIComponent(agentId)}/metadata`);
   emit(context, body, () => renderKeyValues([
-    ['에이전트 ID', body.agentId], ['변경 버전', body.revision], ['이름', body.displayName], ['용도', body.role],
-    ['담당자', body.maintainer], ['연락처', body.maintainerContact], ['운영 상태', body.lifecycle],
-    ['점검 종료 예정', body.maintenanceUntil], ['점검 사유', body.maintenanceReason], ['메모', body.description],
-    ['라벨', Object.entries(body.labels ?? {}).map(([key, value]) => `${key}=${value}`).join(', ')],
-    ['갱신', body.updatedAt],
+    ['Agent ID', body.agentId], ['Revision', body.revision], ['Name', body.displayName], ['Role', body.role],
+    ['Maintainer', body.maintainer], ['Contact', body.maintainerContact], ['Lifecycle', body.lifecycle],
+    ['Maintenance until', body.maintenanceUntil], ['Maintenance reason', body.maintenanceReason], ['Notes', body.description],
+    ['Labels', Object.entries(body.labels ?? {}).map(([key, value]) => `${key}=${value}`).join(', ')],
+    ['Updated', body.updatedAt],
   ]));
 }
 
-async function metadataHistory(context, argv) {
-  const { options, positionals } = parseArguments(argv, { limit: { alias: 'n', type: 'integer', default: 20 } });
-  if (!positionals[0]) throw new UsageError('에이전트 ID가 필요합니다.');
-  const body = await context.client.get(`/api/devices/${encodeURIComponent(positionals[0])}/metadata/history`, { limit: options.limit });
+async function metadataHistory(context, { options, positionals }) {
+  const agentId = requireAgentId(positionals);
+  const body = await context.client.get(`/api/devices/${encodeURIComponent(agentId)}/metadata/history`, { limit: options.limit });
   emit(context, context.global.output === 'ndjson' ? body.history : body, () => renderTable(body.history, [
-    { header: '버전', value: (entry) => `${entry.beforeRevision}→${entry.afterRevision}` },
-    { header: '시각', value: (entry) => localTime(entry.createdAt) },
-    { header: '변경자', value: (entry) => entry.actor, max: 32 },
-    { header: '변경 항목', value: (entry) => entry.changedFields.join(', ') },
+    { header: 'REVISION', value: (entry) => `${entry.beforeRevision}→${entry.afterRevision}` },
+    { header: 'TIME', value: (entry) => localTime(entry.createdAt) },
+    { header: 'ACTOR', value: (entry) => entry.actor, max: 32 },
+    { header: 'CHANGED', value: (entry) => entry.changedFields.join(', ') },
   ], { width: context.width }));
+  if (body.history.length) context.hint(`Restore a revision with \`sentinelctl metadata rollback ${agentId} --to <revision>\`.`);
 }
 
 const metadataFieldOptions = {
   'display-name': 'displayName', role: 'role', maintainer: 'maintainer', contact: 'maintainerContact',
   description: 'description', lifecycle: 'lifecycle', 'maintenance-until': 'maintenanceUntil', 'maintenance-reason': 'maintenanceReason',
 };
+const metadataEditOptions = {
+  'display-name': { type: 'string', placeholder: 'name', description: 'Display name (max 80 chars).' },
+  role: { type: 'string', placeholder: 'role', description: 'Device role (max 80 chars).' },
+  maintainer: { type: 'string', placeholder: 'name', description: 'Maintainer (max 100 chars).' },
+  contact: { type: 'string', placeholder: 'contact', description: 'Maintainer contact (max 160 chars).' },
+  description: { type: 'string', placeholder: 'text', description: 'Operational notes (max 500 chars).' },
+  lifecycle: { type: 'string', choices: ['active', 'maintenance', 'retired'], description: 'Lifecycle. Pair maintenance with --maintenance-until.' },
+  'maintenance-until': { type: 'string', placeholder: 'ISO', description: 'Planned end of maintenance; the device counts as active afterwards.' },
+  'maintenance-reason': { type: 'string', placeholder: 'text', description: 'Maintenance reason (max 200 chars).' },
+  label: { type: 'string', multiple: true, placeholder: 'k=v', description: 'Add or change a label. Other labels are kept.' },
+  'remove-label': { type: 'string', multiple: true, placeholder: 'key', description: 'Remove a label.' },
+  clear: { type: 'string', multiple: true, choices: Object.keys(metadataFieldOptions), description: 'Clear a field.' },
+};
 
-async function metadataSet(context, argv) {
-  const { options, positionals } = parseArguments(argv, {
-    ...Object.fromEntries(Object.keys(metadataFieldOptions).map((name) => [name, { type: 'string' }])),
-    label: { type: 'string', multiple: true }, 'remove-label': { type: 'string', multiple: true },
-    clear: { type: 'string', multiple: true },
-  });
-  const [agentId] = positionals;
-  if (!agentId) throw new UsageError('에이전트 ID가 필요합니다.');
-  const path = `/api/devices/${encodeURIComponent(agentId)}/metadata`;
-  const current = await context.client.get(path);
+function metadataPatch(options, current) {
   const patch = { revision: current.revision };
   for (const [option, field] of Object.entries(metadataFieldOptions)) {
     if (options[option] !== undefined) patch[field] = options[option];
   }
-  for (const option of options.clear ?? []) {
-    if (!metadataFieldOptions[option]) throw new UsageError(`--clear에는 ${Object.keys(metadataFieldOptions).join(', ')} 중 하나를 지정하세요.`);
-    patch[metadataFieldOptions[option]] = null;
-  }
+  for (const option of options.clear ?? []) patch[metadataFieldOptions[option]] = null;
   if (options.label?.length || options['remove-label']?.length) {
     const labels = { ...(current.labels ?? {}) };
     for (const item of options.label ?? []) {
@@ -300,119 +355,192 @@ async function metadataSet(context, argv) {
     for (const key of options['remove-label'] ?? []) delete labels[key];
     patch.labels = labels;
   }
-  if (Object.keys(patch).length === 1) throw new UsageError('바꿀 항목을 하나 이상 지정하세요. 예: --display-name "DB 1"');
+  if (Object.keys(patch).length === 1) {
+    throw new UsageError('Nothing to change. Give at least one field option.', { hint: 'Example: --display-name "DB 1" --label site=seoul (all fields: --help)' });
+  }
+  return patch;
+}
+
+async function metadataSet(context, { options, positionals }) {
+  const agentId = requireAgentId(positionals);
+  metadataPatch(options, { revision: 0, labels: {} });
+  const path = `/api/devices/${encodeURIComponent(agentId)}/metadata`;
+  const current = await context.client.get(path);
+  const patch = metadataPatch(options, current);
+  if (options['dry-run']) {
+    const preview = await context.client.post('/api/devices/metadata/bulk/preview', { updates: [{ agentId, ...patch }] });
+    emit(context, preview, () => JSON.stringify(preview.results[0]?.changes ?? {}, null, 2));
+    context.hint('Dry run only. Run again without --dry-run to apply.');
+    return;
+  }
   const updated = await context.client.patch(path, patch);
-  emit(context, updated, () => `${agentId} 메타데이터를 변경 버전 ${updated.revision}으로 저장했습니다.`);
+  emit(context, updated, () => `Saved metadata for ${agentId} as revision ${updated.revision}.`);
+}
+
+async function metadataBulk(context, { options, positionals }) {
+  const agentIds = [...new Set(positionals)];
+  if (!agentIds.length) throw new UsageError('Give one or more agent IDs.', { hint: 'Example: sentinelctl metadata bulk id1 id2 --role db --dry-run' });
+  if (agentIds.length > 100) throw new UsageError('At most 100 devices per bulk update.');
+  metadataPatch(options, { revision: 0, labels: {} });
+  const currents = [];
+  for (let index = 0; index < agentIds.length; index += 8) {
+    currents.push(...await Promise.all(agentIds.slice(index, index + 8)
+      .map((agentId) => context.client.get(`/api/devices/${encodeURIComponent(agentId)}/metadata`))));
+  }
+  const updates = currents.map((current) => ({ agentId: current.agentId, ...metadataPatch(options, current) }));
+  const body = options['dry-run']
+    ? await context.client.post('/api/devices/metadata/bulk/preview', { updates })
+    : await context.client.patch('/api/devices/metadata/bulk', { updates });
+  emit(context, context.global.output === 'ndjson' ? body.results : body, () => renderTable(body.results, [
+    { header: 'AGENT ID', value: (result) => result.agentId },
+    { header: 'RESULT', value: (result) => (result.ok ? 'ok' : `failed ${result.status ?? ''}`) },
+    { header: 'DETAIL', value: (result) => {
+      if (!result.ok) return result.error;
+      if (result.metadata) return `revision ${result.metadata.revision}`;
+      return Object.keys(result.changes ?? {}).join(', ') || 'no change';
+    } },
+  ], { width: context.width }));
+  const failures = body.results.filter((result) => !result.ok).length;
+  if (options['dry-run']) context.hint(`Dry run: ${body.changeCount ?? 0} would change, ${failures} would fail. Run without --dry-run to apply.`);
+  else if (failures) context.hint(`${failures} failed. A 409 means someone changed that device meanwhile; rerun for those devices only.`);
 }
 
-async function metadataRollback(context, argv) {
-  const { options, positionals } = parseArguments(argv, { to: { type: 'integer' } });
-  const [agentId] = positionals;
-  if (!agentId || options.to === undefined) throw new UsageError('에이전트 ID와 --to <변경 버전>이 필요합니다.');
+async function metadataRollback(context, { options, positionals }) {
+  const agentId = requireAgentId(positionals);
+  if (options.to === undefined) throw new UsageError('--to <revision> is required.', { hint: `List revisions with \`sentinelctl metadata history ${agentId}\`.` });
   const path = `/api/devices/${encodeURIComponent(agentId)}/metadata`;
   const current = await context.client.get(path);
   const updated = await context.client.post(`${path}/rollback`, { revision: current.revision, targetRevision: options.to });
-  emit(context, updated, () => `${agentId} 메타데이터를 버전 ${options.to} 내용으로 되돌렸습니다(새 변경 버전 ${updated.revision}).`);
+  emit(context, updated, () => `Restored ${agentId} to the content of revision ${options.to} (new revision ${updated.revision}).`);
 }
 
-async function metadataExport(context, argv) {
-  const { options } = parseArguments(argv, { file: { type: 'string' } });
+async function metadataExport(context, { options }) {
   const body = await context.client.get('/api/metadata/export');
   if (options.file) {
-    await writeFile(options.file, `${JSON.stringify(body, null, 2)}\n`, { mode: 0o600, flag: 'wx' });
-    context.err(`${body.devices?.length ?? 0}대 메타데이터를 ${options.file}에 저장했습니다.`);
+    await writeFile(options.file, `${JSON.stringify(body, null, 2)}\n`, { mode: 0o600, flag: 'wx' }).catch((error) => {
+      if (error.code === 'EEXIST') throw new UsageError(`File already exists: ${options.file}`, { hint: 'Existing files are never overwritten; choose another path.' });
+      throw error;
+    });
+    context.note(`Saved metadata for ${body.devices?.length ?? 0} devices to ${options.file}.`);
     return;
   }
   context.out(JSON.stringify(body, null, 2));
 }
 
-async function metadataImport(context, argv) {
-  const { options, positionals } = parseArguments(argv, {
-    'dry-run': { type: 'boolean' }, conflict: { type: 'string', choices: ['error', 'skip', 'overwrite'], default: 'error' },
-  });
-  if (!positionals[0]) throw new UsageError('가져올 JSON 파일 경로가 필요합니다.');
+async function metadataImport(context, { options, positionals }) {
+  if (!positionals[0]) throw new UsageError('A JSON file path is required.', { hint: 'Use the format produced by `sentinelctl metadata export`.' });
   let payload;
   try {
     payload = JSON.parse(await readFile(positionals[0], 'utf8'));
   } catch {
-    throw new UsageError(`JSON 파일을 읽을 수 없습니다: ${positionals[0]}`);
+    throw new UsageError(`Cannot read JSON file: ${positionals[0]}`);
   }
   const path = options['dry-run'] ? '/api/metadata/import/validate' : '/api/metadata/import';
   const body = (await context.client.request('POST', path, { query: { conflictPolicy: options.conflict }, body: payload })).body;
   emit(context, body, () => JSON.stringify(body, null, 2));
+  if (options['dry-run']) context.hint('Validated only. Run again without --dry-run to import.');
 }
 
 const sessionColumns = [
   { header: 'ID', value: (session) => session.id },
-  { header: '종류', value: (session) => (session.kind === 'cli' ? 'CLI' : '웹') },
-  { header: '사용자', value: (session) => session.user, max: 32 },
-  { header: '클라이언트', value: (session) => session.clientName ?? '-', max: 28 },
-  { header: '마지막 사용', value: (session) => localTime(session.lastSeenAt) },
-  { header: '만료', value: (session) => localTime(session.expiresAt) },
+  { header: 'KIND', value: (session) => (session.kind === 'cli' ? 'cli' : 'web') },
+  { header: 'USER', value: (session) => session.user, max: 32 },
+  { header: 'CLIENT', value: (session) => session.clientName ?? '-', max: 28 },
+  { header: 'LAST USED', value: (session) => localTime(session.lastSeenAt) },
+  { header: 'EXPIRES', value: (session) => localTime(session.expiresAt) },
 ];
 
 async function sessionsList(context) {
   const body = await context.client.get('/api/auth/sessions');
   emit(context, context.global.output === 'ndjson' ? body.sessions : body, () => renderTable(
-    body.sessions, [...sessionColumns, { header: '', value: (session) => (session.current ? '← 현재' : '') }], { width: context.width },
+    body.sessions, [...sessionColumns, { header: '', value: (session) => (session.current ? '← current' : '') }], { width: context.width },
   ));
 }
 
-async function sessionsRevoke(context, argv) {
-  const { positionals } = parseArguments(argv, {});
-  if (!positionals[0]) throw new UsageError('폐기할 세션 ID가 필요합니다.');
+async function sessionsRevoke(context, { positionals }) {
+  if (!positionals[0]) throw new UsageError('A session ID is required.', { hint: 'List them with `sentinelctl sessions list`.' });
   await context.client.post(`/api/auth/sessions/${encodeURIComponent(positionals[0])}/revoke`, {});
-  context.out(`세션 ${positionals[0]}을 폐기했습니다.`);
+  context.out(`Revoked session ${positionals[0]}.`);
 }
 
 async function adminUsers(context) {
   const body = await context.client.get('/api/admin/users');
   emit(context, context.global.output === 'ndjson' ? body.users : body, () => renderTable(body.users, [
-    { header: '이메일', value: (user) => user.email, max: 36 },
-    { header: '권한', value: (user) => (user.disabled ? '중지됨' : roleLabels[user.effectiveRole] ?? user.effectiveRole) },
-    { header: '근거', value: (user) => ({ bootstrap: '기본 관리자', grant: '콘솔 지정', default: '기본값', disabled: '중지' })[user.roleSource] ?? user.roleSource },
-    { header: '웹/CLI', value: (user) => `${user.sessions.web}/${user.sessions.cli}` },
-    { header: '마지막 로그인', value: (user) => localTime(user.lastLoginAt) },
+    { header: 'EMAIL', value: (user) => user.email, max: 36 },
+    { header: 'ROLE', value: (user) => (user.disabled ? 'disabled' : user.effectiveRole) },
+    { header: 'SOURCE', value: (user) => ({ bootstrap: 'bootstrap admin', grant: 'granted', default: 'default', disabled: 'disabled', intflow_app_admin: 'intflow app admin' })[user.roleSource] ?? user.roleSource },
+    { header: 'WEB/CLI', value: (user) => `${user.sessions.web}/${user.sessions.cli}` },
+    { header: 'LAST LOGIN', value: (user) => localTime(user.lastLoginAt) },
   ], { width: context.width }));
 }
 
-async function adminGrant(context, argv, grant) {
-  const { options, positionals } = parseArguments(argv, grant.role === undefined
-    ? { role: { type: 'string', choices: ['viewer', 'editor', 'admin'] } }
-    : {});
-  const [email] = positionals;
-  if (!email) throw new UsageError('이메일이 필요합니다.');
-  const role = grant.role === undefined ? options.role : grant.role;
-  if (grant.role === undefined && !role) throw new UsageError('--role viewer|editor|admin이 필요합니다.');
-  const body = await context.client.post('/api/admin/users/grant', { email, role, disabled: grant.disabled ?? false });
-  emit(context, body, () => `${body.email}: ${body.disabled ? '접근 중지' : (roleLabels[body.effectiveRole] ?? body.effectiveRole)}`);
+function adminGrantCommand(grant) {
+  return async (context, { options, positionals }) => {
+    const [email] = positionals;
+    if (!email) throw new UsageError('An email is required.', { hint: 'Example: sentinelctl admin grant kim@intflow.ai --role editor' });
+    const role = grant.role === undefined ? options.role : grant.role;
+    if (grant.role === undefined && !role) throw new UsageError('--role is required.', { hint: 'Allowed values: viewer, editor, admin' });
+    const body = await context.client.post('/api/admin/users/grant', { email, role, disabled: grant.disabled ?? false });
+    emit(context, body, () => `${body.email}: ${body.disabled ? 'disabled' : body.effectiveRole}`);
+  };
 }
 
-async function adminSessions(context, argv) {
-  const { options } = parseArguments(argv, { kind: { type: 'string', choices: ['web', 'cli'] } });
+async function adminSessions(context, { options }) {
   const body = await context.client.get('/api/admin/sessions', { kind: options.kind });
   emit(context, context.global.output === 'ndjson' ? body.sessions : body, () => renderTable(body.sessions, sessionColumns, { width: context.width }));
 }
 
-async function adminRevokeSession(context, argv) {
-  const { positionals } = parseArguments(argv, {});
-  if (!positionals[0]) throw new UsageError('폐기할 세션 ID가 필요합니다.');
+async function adminRevokeSession(context, { positionals }) {
+  if (!positionals[0]) throw new UsageError('A session ID is required.', { hint: 'List them with `sentinelctl admin sessions`.' });
   await context.client.post(`/api/admin/sessions/${encodeURIComponent(positionals[0])}/revoke`, {});
-  context.out(`세션 ${positionals[0]}을 폐기했습니다.`);
+  context.out(`Revoked session ${positionals[0]}.`);
 }
 
-async function rawApi(context, argv) {
-  const { options, positionals } = parseArguments(argv, {
-    method: { alias: 'X', type: 'string', choices: ['GET', 'POST', 'PATCH'], default: 'GET' }, data: { alias: 'd', type: 'string' },
-  });
+async function adminAudit(context, { options }) {
+  if (options.cleanup) {
+    const result = await context.client.post('/api/metadata/audit-maintenance/cleanup', {});
+    emit(context, result, () => `Removed ${result.deletedCount} audit entries under the retention policy.`);
+    return;
+  }
+  const body = await context.client.get('/api/metadata/audit-maintenance', { limit: options.limit });
+  emit(context, context.global.output === 'ndjson' ? body.history : body, () => renderTable(body.history, [
+    { header: 'TIME', value: (entry) => localTime(entry.createdAt) },
+    { header: 'ACTOR', value: (entry) => entry.actor, max: 32 },
+    { header: 'DELETED', value: (entry) => String(entry.deletedCount) },
+    { header: 'POLICY', value: (entry) => `${entry.retentionDays}d / ${Math.round(entry.maximumBytes / 1_048_576)}MiB` },
+  ], { width: context.width }));
+}
+
+function bytesText(value) {
+  if (!Number.isFinite(value)) return '-';
+  const units = ['B', 'KiB', 'MiB', 'GiB', 'TiB'];
+  let size = value;
+  let index = 0;
+  while (Math.abs(size) >= 1024 && index < units.length - 1) { size /= 1024; index += 1; }
+  return `${size.toFixed(index ? 1 : 0)}${units[index]}`;
+}
+
+async function adminOperations(context, { options }) {
+  const body = await context.client.get('/api/operations', { range: options.range });
+  emit(context, body, () => renderTable(Object.entries(body.components ?? {}), [
+    { header: 'COMPONENT', value: ([name]) => name },
+    { header: 'LATEST', value: ([, component]) => component.latestAttempt?.status ?? component.latest?.status ?? '-' },
+    { header: 'STORED', value: ([, component]) => bytesText(component.latest?.dataBytes) },
+    { header: 'CHANGE', value: ([, component]) => bytesText(component.storageChangeBytes) },
+    { header: 'EST/DAY', value: ([, component]) => bytesText(component.estimatedDailyBytes) },
+    { header: 'COVERAGE', value: ([, component]) => (Number.isFinite(component.coverage?.ratio) ? `${Math.round(component.coverage.ratio * 100)}%` : '-') },
+  ], { width: context.width }));
+}
+
+async function rawApi(context, { options, positionals }) {
   const [path] = positionals;
-  if (!path?.startsWith('/api/')) throw new UsageError('/api/로 시작하는 경로가 필요합니다.');
+  if (!path?.startsWith('/api/')) throw new UsageError('A path starting with /api/ is required.', { hint: 'Example: sentinelctl api "/api/devices?status=offline"' });
   let body;
   if (options.data !== undefined) {
     try {
       body = JSON.parse(options.data);
     } catch {
-      throw new UsageError('--data는 JSON이어야 합니다.');
+      throw new UsageError('--data must be JSON.');
     }
   }
   const url = new URL(path, context.client.server);
@@ -420,59 +548,287 @@ async function rawApi(context, argv) {
   context.out(JSON.stringify(result.body, null, 2));
 }
 
-export const commandTable = {
-  logs: {
-    summary: '로그 검색·주변 로그·히스토그램·출처',
-    commands: {
-      search: { run: logsSearch, usage: 'logs search [검색어] [-q 텍스트] [-a 에이전트] [-l 수준] [-s 출처] [-r 15m|1h|6h|24h|7d | --from ISO --to ISO] [-n 50|100|250] [--pages N | --all] [--fields] [-f]' },
-      context: { run: logsContext, usage: 'logs context -a 에이전트 -s 출처 -t 2026-09-30T01:02:03.000Z [--before N] [--after N]' },
-      histogram: { run: logsHistogram, usage: 'logs histogram [로그 검색과 같은 필터]' },
-      sources: { run: logsSources, usage: 'logs sources [-r 24h]' },
+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.',
+    args: [{ name: 'text', optional: true, description: 'Same as -q (words are joined with spaces).' }],
+    options: {
+      ...logFilterOptions,
+      limit: { alias: 'n', type: 'integer', choices: [50, 100, 250], description: 'Logs per page. Default 100 (250 when paging).' },
+      pages: { type: 'integer', placeholder: 'N', description: `Follow the cursor for up to N pages (1-${maxPages}).` },
+      all: { type: 'boolean', description: 'Fetch every page of the window, stopping at 10,000 logs.' },
+      fields: { type: 'boolean', description: 'Include raw fields (admin only, audited, 50 logs per page).' },
+      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.' },
+    },
+    roleFor: (options) => (options.fields ? 'admin' : 'viewer'),
+    roleNote: '--fields requires admin',
+    examples: [
+      'sentinelctl logs search -l error -r 1h',
+      '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}.',
+  },
+  {
+    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.',
+    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.' },
+      top: { type: 'integer', default: 20, placeholder: 'N', description: 'Groups to return (1-100).' },
+      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 -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?}}.',
   },
-  devices: {
-    summary: '장비 목록·상세·찾기·개요',
-    commands: {
-      list: { run: devicesList, usage: 'devices list [검색어] [--status online|delayed|offline|…] [--site S] [--group G] [--role R] [--label k=v] [--sort 필드] [--order asc|desc] [--page N] [--page-size N | --all]' },
-      show: { run: devicesShow, usage: 'devices show <에이전트 ID> [-r 30m|1h|6h|24h|7d|30d]' },
-      lookup: { run: devicesLookup, usage: 'devices lookup <검색어>' },
-      overview: { run: devicesOverview, usage: 'devices overview <에이전트 ID> [-r 24h]' },
+  {
+    group: 'logs', name: 'context', run: logsContext, role: 'viewer', mutates: false,
+    summary: 'Logs just before and after one log, from the same device and source',
+    options: {
+      agent: { alias: 'a', type: 'string', placeholder: 'id', description: 'Agent ID (required).' },
+      source: { alias: 's', type: 'string', placeholder: 'source', description: 'Source (required).' },
+      timestamp: { alias: 't', type: 'string', placeholder: 'ISO', description: 'The anchor log timestamp exactly as returned (required).' },
+      before: { type: 'integer', placeholder: 'N', description: 'Logs before (1-50, default 10).' },
+      after: { type: 'integer', placeholder: 'N', description: 'Logs after (1-50, default 10).' },
+      window: { type: 'integer', placeholder: 'seconds', description: 'Search distance on each side (30-3600, default 300).' },
+      wide: { alias: 'w', type: 'boolean', description: 'Do not truncate messages.' },
     },
+    examples: ['sentinelctl logs context -a <agent-id> -s app.service -t 2026-09-30T01:02:03.456789Z -o json'],
+    output: '{criteria, count, logs[]} with logs in time order, same shape as logs search.',
   },
-  metadata: {
-    summary: '장비 메타데이터 조회·변경(편집 권한)·가져오기/내보내기(관리자)',
-    commands: {
-      get: { run: metadataGet, usage: 'metadata get <에이전트 ID>' },
-      history: { run: metadataHistory, usage: 'metadata history <에이전트 ID> [-n 20]' },
-      set: { run: metadataSet, usage: 'metadata set <에이전트 ID> [--display-name ..] [--role ..] [--maintainer ..] [--contact ..] [--description ..] [--lifecycle active|maintenance|retired] [--label k=v] [--remove-label k] [--clear 필드]' },
-      rollback: { run: metadataRollback, usage: 'metadata rollback <에이전트 ID> --to <변경 버전>' },
-      export: { run: metadataExport, usage: 'metadata export [--file 경로]' },
-      import: { run: metadataImport, usage: 'metadata import <파일> [--dry-run] [--conflict error|skip|overwrite]' },
+  {
+    group: 'logs', name: 'histogram', run: logsHistogram, role: 'viewer', mutates: false,
+    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.',
+  },
+  {
+    group: 'logs', name: 'sources', run: logsSources, role: 'viewer', mutates: false,
+    summary: 'Log sources (systemd units, containers) seen recently',
+    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.',
+  },
+  {
+    group: 'devices', name: 'list', run: devicesList, role: 'viewer', mutates: false,
+    summary: 'Devices with status and resource usage; search, filter and sort',
+    args: [{ name: 'text', optional: true, description: 'Substring of name, host, ID, OS, site, group, role, maintainer, notes or labels.' }],
+    options: {
+      query: { alias: 'q', type: 'string', placeholder: 'text', description: 'Same as the positional text.' },
+      status: { type: 'string', choices: deviceStatuses, description: 'Reception status.' },
+      lifecycle: { type: 'string', choices: lifecycles, description: 'Lifecycle scope (default operational = active + maintenance).' },
+      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.' },
+      focus: { type: 'string', choices: ['attention', 'resources', 'collection', 'repeated', 'recovered', 'spool', 'metadata'], description: 'Only devices needing attention of this kind.' },
+      inventory: { type: 'string', choices: ['registered', 'discovered', 'history'], description: 'Inventory state.' },
+      label: { type: 'string', multiple: true, placeholder: 'k=v', description: 'Label match (up to 8).' },
+      sort: { type: 'string', choices: deviceSorts, description: 'Sort key.' },
+      order: { type: 'string', choices: ['asc', 'desc'], description: 'Sort direction.' },
+      page: { type: 'integer', default: 1, placeholder: 'N', description: 'Page number.' },
+      'page-size': { type: 'integer', default: 50, placeholder: 'N', description: 'Page size (max 100).' },
+      all: { type: 'boolean', description: 'Fetch every page (remaining pages are fetched concurrently).' },
     },
+    examples: ['sentinelctl devices list --status offline', 'sentinelctl devices list --focus attention --all -o json',
+      'sentinelctl devices list --sort cpu --order desc --page-size 10'],
+    output: 'devices[]: agentId, displayName, host, status, cpu/memory/disk (%), ageSeconds, site, group, metadata, attentionReasons … -o json wraps them as {matched, counts, stale, devices}.',
   },
-  sessions: {
-    summary: '내 웹 세션·CLI 토큰 조회와 폐기',
-    commands: {
-      list: { run: sessionsList, usage: 'sessions list' },
-      revoke: { run: sessionsRevoke, usage: 'sessions revoke <세션 ID>' },
+  {
+    group: 'devices', name: 'show', run: devicesShow, role: 'viewer', mutates: false,
+    summary: 'One device: current state and metric time series',
+    args: [{ name: 'agent-id' }],
+    options: {
+      range: { alias: 'r', type: 'string', choices: deviceRanges, default: '6h', description: 'Time-series window (about 120 points).' },
+      refresh: { type: 'boolean', description: 'Bypass the server cache.' },
     },
+    examples: ['sentinelctl devices show <agent-id> -r 24h -o json'],
+    output: '{device, current, series{cpu, memory, disk, load, temperature, networkRx, networkTx, …: [[epochSeconds, value], …]}, range, stepSeconds, stale}.',
+  },
+  {
+    group: 'devices', name: 'lookup', run: devicesLookup, role: 'viewer', mutates: false,
+    summary: 'Find agent IDs by part of a name or host',
+    args: [{ name: 'text' }],
+    options: {},
+    examples: ['sentinelctl devices lookup 10357'],
+    output: '{devices[]: {agentId, host, displayName}, matched} (up to 100).',
+  },
+  {
+    group: 'devices', name: 'overview', run: devicesOverview, role: 'viewer', mutates: false,
+    summary: 'Reception state, outage counts and durations, and attention reasons for one device',
+    args: [{ name: 'agent-id' }],
+    options: { range: { alias: 'r', type: 'string', default: '24h', placeholder: 'window', description: 'History window, e.g. 24h or 7d.' } },
+    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[]}.',
+  },
+  {
+    group: 'metadata', name: 'get', run: metadataGet, role: 'viewer', mutates: false,
+    summary: 'Device metadata: name, role, maintainer, labels, lifecycle',
+    args: [{ name: 'agent-id' }], options: {},
+    examples: ['sentinelctl metadata get <agent-id> -o json'],
+    output: '{agentId, revision, displayName, role, maintainer, maintainerContact, description, labels, lifecycle, maintenanceUntil, maintenanceReason, updatedAt}.',
+  },
+  {
+    group: 'metadata', name: 'history', run: metadataHistory, role: 'viewer', mutates: false,
+    summary: 'Metadata change history: who, when, what',
+    args: [{ name: 'agent-id' }],
+    options: { limit: { alias: 'n', type: 'integer', default: 20, placeholder: 'N', description: 'Maximum entries (1-100).' } },
+    examples: ['sentinelctl metadata history <agent-id>'],
+    output: '{history[]: {beforeRevision, afterRevision, changedFields[], actor, createdAt, before, after}}.',
   },
-  admin: {
-    summary: '사용자 권한 지정·접근 중지, 전체 세션 관리(관리자)',
-    commands: {
-      users: { run: adminUsers, usage: 'admin users' },
-      grant: { run: (context, argv) => adminGrant(context, argv, {}), usage: 'admin grant <이메일> --role viewer|editor|admin' },
-      reset: { run: (context, argv) => adminGrant(context, argv, { role: null }), usage: 'admin reset <이메일>   (콘솔 지정 권한을 지우고 기본값으로)' },
-      disable: { run: (context, argv) => adminGrant(context, argv, { role: null, disabled: true }), usage: 'admin disable <이메일>   (접근 중지·세션 즉시 종료)' },
-      sessions: { run: adminSessions, usage: 'admin sessions [--kind web|cli]' },
-      revoke: { run: adminRevokeSession, usage: 'admin revoke <세션 ID>' },
+  {
+    group: 'metadata', name: 'set', run: metadataSet, role: 'editor', mutates: true,
+    summary: 'Edit metadata (reads the latest revision and applies on top of it)',
+    args: [{ name: 'agent-id' }],
+    options: { ...metadataEditOptions, 'dry-run': { type: 'boolean', description: 'Show what would change without saving.' } },
+    examples: ['sentinelctl metadata set <agent-id> --display-name "Edge 1" --label site=seoul --dry-run',
+      'sentinelctl metadata set <agent-id> --lifecycle maintenance --maintenance-until 2026-10-01T09:00:00+09:00 --maintenance-reason "disk swap"'],
+    output: 'Saved metadata (same shape as metadata get). With --dry-run: {results[0].changes}.',
+  },
+  {
+    group: 'metadata', name: 'bulk', run: metadataBulk, role: 'editor', mutates: true,
+    summary: 'Apply the same metadata change to up to 100 devices',
+    args: [{ name: 'agent-id…', description: 'Space separated.' }],
+    options: { ...metadataEditOptions, 'dry-run': { type: 'boolean', description: 'Preview the change per device.' } },
+    examples: ['sentinelctl metadata bulk id1 id2 id3 --role camera --label site=farm-a --dry-run'],
+    output: '{count, successCount|changeCount, failureCount, results[]: {agentId, ok, status?, error?, changes|metadata}}. Partial success per device.',
+  },
+  {
+    group: 'metadata', name: 'rollback', run: metadataRollback, role: 'editor', mutates: true,
+    summary: 'Restore metadata to the content of an earlier revision (recorded as a new revision)',
+    args: [{ name: 'agent-id' }],
+    options: { to: { type: 'integer', placeholder: 'revision', description: 'Revision to restore (required; see metadata history).' } },
+    examples: ['sentinelctl metadata rollback <agent-id> --to 3'],
+    output: 'Metadata after the rollback.',
+  },
+  {
+    group: 'metadata', name: 'export', run: metadataExport, role: 'admin', mutates: false,
+    summary: 'Export metadata for all devices as JSON',
+    options: { file: { type: 'string', placeholder: 'path', description: 'Write to a new file (0600, never overwrites). Default: stdout.' } },
+    examples: ['sentinelctl metadata export --file metadata-backup.json'],
+    output: '{schemaVersion, scope, exportedAt, devices[]}.',
+  },
+  {
+    group: 'metadata', name: 'import', run: metadataImport, role: 'admin', mutates: true,
+    summary: 'Import metadata in export format',
+    args: [{ name: 'file' }],
+    options: {
+      'dry-run': { type: 'boolean', description: 'Validate only.' },
+      conflict: { type: 'string', choices: ['error', 'skip', 'overwrite'], default: 'error', description: 'What to do with devices that already have metadata.' },
     },
+    examples: ['sentinelctl metadata import backup.json --dry-run --conflict skip'],
+    output: '{valid, count, insertCount, overwriteCount, skipCount, conflictCount, …}.',
   },
-};
+  {
+    group: 'sessions', name: 'list', run: sessionsList, role: 'viewer', mutates: false,
+    summary: 'Your web sessions and CLI tokens', options: {},
+    examples: ['sentinelctl sessions list'], output: '{sessions[]: {id, kind, user, clientName, createdAt, lastSeenAt, expiresAt, current}}.',
+  },
+  {
+    group: 'sessions', name: 'revoke', run: sessionsRevoke, role: 'viewer', mutates: true,
+    summary: 'Revoke one of your sessions or CLI tokens', args: [{ name: 'session-id' }], options: {},
+    examples: ['sentinelctl sessions revoke <session-id>'], output: 'Confirmation message.',
+  },
+  {
+    group: 'admin', name: 'users', run: adminUsers, role: 'admin', mutates: false,
+    summary: 'Users with their role, where it comes from, and session counts', options: {},
+    examples: ['sentinelctl admin users -o json'],
+    output: '{users[]: {email, name, effectiveRole, roleSource, grantedRole, disabled, bootstrapAdmin, sessions{web, cli}, lastLoginAt}}.',
+  },
+  {
+    group: 'admin', name: 'grant', run: adminGrantCommand({}), role: 'admin', mutates: true,
+    summary: 'Grant a role (works before the user first logs in)', args: [{ name: 'email' }],
+    options: { role: { type: 'string', choices: ['viewer', 'editor', 'admin'], description: 'Role to grant (required).' } },
+    examples: ['sentinelctl admin grant kim@intflow.ai --role editor'], output: 'The updated user row.',
+  },
+  {
+    group: 'admin', name: 'reset', run: adminGrantCommand({ role: null }), role: 'admin', mutates: true,
+    summary: 'Remove a granted role (back to the default viewer)', args: [{ name: 'email' }], options: {},
+    examples: ['sentinelctl admin reset kim@intflow.ai'], output: 'The updated user row.',
+  },
+  {
+    group: 'admin', name: 'disable', run: adminGrantCommand({ role: null, disabled: true }), role: 'admin', mutates: true,
+    summary: 'Block access and end all of the user\'s sessions and CLI tokens now', args: [{ name: 'email' }], options: {},
+    examples: ['sentinelctl admin disable kim@intflow.ai'], output: 'The updated user row. Undo with admin reset.',
+  },
+  {
+    group: 'admin', name: 'sessions', run: adminSessions, role: 'admin', mutates: false,
+    summary: 'All web sessions and CLI tokens',
+    options: { kind: { type: 'string', choices: ['web', 'cli'], description: 'Filter by kind.' } },
+    examples: ['sentinelctl admin sessions --kind cli'], output: '{sessions[]}.',
+  },
+  {
+    group: 'admin', name: 'revoke', run: adminRevokeSession, role: 'admin', mutates: true,
+    summary: 'Revoke anyone\'s session or CLI token', args: [{ name: 'session-id' }], options: {},
+    examples: ['sentinelctl admin revoke <session-id>'], output: 'Confirmation message.',
+  },
+  {
+    group: 'admin', name: 'audit', run: adminAudit, role: 'admin', mutates: false,
+    summary: 'Metadata audit clean-up records; run the clean-up now',
+    options: {
+      cleanup: { type: 'boolean', description: 'Apply the retention policy now (default 365 days / 64 MiB).' },
+      limit: { alias: 'n', type: 'integer', placeholder: 'N', description: 'Records to show (1-100).' },
+    },
+    examples: ['sentinelctl admin audit', 'sentinelctl admin audit --cleanup'], output: '{history[]} or {deletedCount}.',
+  },
+  {
+    group: 'admin', name: 'operations', run: adminOperations, role: 'admin', mutates: false,
+    summary: 'Backend (metrics, logs, console) storage and ingestion trends',
+    options: { range: { alias: 'r', type: 'string', choices: ['24h', '7d'], default: '24h', description: 'Window.' } },
+    examples: ['sentinelctl admin operations -r 7d -o json'], output: '{components{metrics, logs, console}: {latest, storageChangeBytes, estimatedDailyBytes, coverage, series}}.',
+  },
+  {
+    group: null, name: 'health', run: health, role: 'viewer', mutates: false,
+    summary: 'Backend connectivity', options: {},
+    examples: ['sentinelctl health -o json'], output: '{status, application, components{metrics, logs, metadata}: {status, latencyMs}}.',
+  },
+  {
+    group: null, name: 'api', run: rawApi, role: 'viewer', mutates: false,
+    summary: 'Call a console API directly (JSON output; the server enforces roles)',
+    args: [{ name: 'path', description: 'Starts with /api/.' }],
+    options: {
+      method: { alias: 'X', type: 'string', choices: ['GET', 'POST', 'PATCH'], default: 'GET', description: 'HTTP method.' },
+      data: { alias: 'd', type: 'string', placeholder: 'JSON', description: 'Request body.' },
+    },
+    examples: ['sentinelctl api "/api/devices?status=offline&pageSize=5"'], output: 'The server response JSON as is.',
+  },
+];
 
-export const standaloneCommands = {
-  health: { run: health, usage: 'health', summary: '백엔드 연결 상태' },
-  api: { run: rawApi, usage: 'api <경로> [-X GET|POST|PATCH] [-d JSON]', summary: '콘솔 API 직접 호출(JSON 출력)' },
+export const catalog = commands;
+export const groups = {
+  logs: 'Search, count and rank logs; context around a log; volume trends; sources',
+  devices: 'Device list, details, lookup, reception overview',
+  metadata: 'Device metadata: read, edit (editor), import/export (admin)',
+  sessions: 'Your sessions and CLI tokens',
+  admin: 'Roles, all sessions, audit clean-up, capacity (admin)',
 };
 
-export { outputChoices, singleLine };
+export function findCommand(group, name) {
+  return commands.find((command) => command.group === group && command.name === name) ?? null;
+}
+
+export function commandPath(command) {
+  return command.group ? `${command.group} ${command.name}` : command.name;
+}
+
+export function usageLine(command) {
+  const args = (command.args ?? []).map((arg) => (arg.optional ? `[${arg.name}]` : `<${arg.name}>`)).join(' ');
+  return `sentinelctl ${commandPath(command)}${args ? ` ${args}` : ''}${Object.keys(command.options).length ? ' [options]' : ''}`;
+}
+
+export { singleLine };