@intflow/sentinelctl 0.1.0 → 0.3.0

package/src/credentials.mjs

@@ -16,14 +16,14 @@ export function normalizeServer(value) {
   try {
     url = new URL(String(value ?? ''));
   } catch {
-    throw new Error(`서버 주소가 올바르지 않습니다: ${value}`);
+    throw new Error(`Invalid server URL: ${value}`);
   }
   const loopback = ['localhost', '127.0.0.1', '[::1]'].includes(url.hostname);
   if (url.username || url.password || url.search || url.hash || (url.pathname !== '/' && url.pathname !== '')) {
-    throw new Error('서버 주소는 경로가 없는 origin이어야 합니다. 예: https://monitor.intflow.dev');
+    throw new Error('The server must be an origin without a path, e.g. https://monitor.intflow.dev');
   }
   if (url.protocol !== 'https:' && !(url.protocol === 'http:' && loopback)) {
-    throw new Error('서버 주소는 HTTPS여야 합니다(localhost만 HTTP 허용).');
+    throw new Error('The server must use HTTPS (plain HTTP is allowed only for localhost).');
   }
   return url.origin;
 }
@@ -32,16 +32,15 @@ export async function readCredentials(path) {
   try {
     const parsed = JSON.parse(await readFile(path, 'utf8'));
     if (parsed?.version !== 1 || typeof parsed.profiles !== 'object' || parsed.profiles === null) {
-      throw new Error('형식');
+      throw new Error('format');
     }
     return parsed;
   } catch (error) {
     if (error.code === 'ENOENT') return { version: 1, profiles: {} };
-    throw new Error(`자격 증명 파일을 읽을 수 없습니다: ${path}`);
+    throw new Error(`Cannot read the credentials file: ${path}`);
   }
 }
 
-// 토큰 파일은 소유자만 읽을 수 있게 0600으로 쓰고, 임시 파일을 거쳐 원자적으로 교체한다.
 export async function writeCredentials(path, credentials) {
   await mkdir(dirname(path), { recursive: true, mode: 0o700 });
   const temporary = `${path}.${process.pid}.tmp`;
@@ -65,12 +64,12 @@ export async function removeProfile(path, profileName) {
   return true;
 }
 
-// 우선순위: 명령행 --server > SENTINEL_URL > 프로필 > 기본값. 토큰은 SENTINEL_TOKEN > 프로필.
 export async function resolveConnection({ server, profile = 'default', environment = process.env, path = credentialsPath(environment) }) {
   const credentials = await readCredentials(path);
   const saved = credentials.profiles[profile] ?? null;
   const resolvedServer = normalizeServer(server ?? environment.SENTINEL_URL ?? saved?.server ?? defaultServer);
+  const fromEnvironment = Boolean(environment.SENTINEL_TOKEN);
   const token = environment.SENTINEL_TOKEN
     ?? (saved && normalizeServer(saved.server) === resolvedServer ? saved.token : null);
-  return { server: resolvedServer, token: token ?? null, profile: saved, profileName: profile, path };
+  return { server: resolvedServer, token: token ?? null, profile: saved, profileName: profile, path, fromEnvironment };
 }

package/src/format.mjs

@@ -1,4 +1,3 @@
-// 한글·CJK 전각 문자는 터미널에서 두 칸을 차지한다.
 const wideCharacter = /[ᄀ-ᅟ⺀-꓏가-힣豈-﫿︰-﹏＀-｠￠-￦]/u;
 
 export function displayWidth(value) {
@@ -30,7 +29,6 @@ export function singleLine(value) {
   return String(value ?? '').replace(/[\r\n\t]+/g, ' ').replace(/[\u0000-\u001f\u007f]/g, '');
 }
 
-// columns: [{ header, value(row), max? }]. 마지막 열은 남은 터미널 폭에 맞춰 자른다.
 export function renderTable(rows, columns, { width = 120, wide = false } = {}) {
   const cells = rows.map((row) => columns.map((column) => singleLine(column.value(row) ?? '-')));
   const widths = columns.map((column, index) => Math.min(column.max ?? Infinity,
@@ -66,8 +64,8 @@ export function percentText(value) {
 
 export function ageText(seconds) {
   if (!Number.isFinite(seconds)) return '-';
-  if (seconds < 60) return `${Math.max(0, Math.round(seconds))}초 전`;
-  if (seconds < 3_600) return `${Math.round(seconds / 60)}분 전`;
-  if (seconds < 86_400) return `${Math.round(seconds / 3_600)}시간 전`;
-  return `${Math.round(seconds / 86_400)}일 전`;
+  if (seconds < 60) return `${Math.max(0, Math.round(seconds))}s ago`;
+  if (seconds < 3_600) return `${Math.round(seconds / 60)}m ago`;
+  if (seconds < 86_400) return `${Math.round(seconds / 3_600)}h ago`;
+  return `${Math.round(seconds / 86_400)}d ago`;
 }

package/src/login.mjs

@@ -21,7 +21,6 @@ export function defaultClientName() {
   return `sentinelctl@${hostname()}`.replace(/[\u0000-\u001f\u007f]/g, '').slice(0, 80);
 }
 
-// 서버가 발급하는 토큰은 브라우저 승인 뒤 폴링으로 한 번만 받는다. poll secret은 이 프로세스 밖으로 나가지 않는다.
 export async function browserLogin(client, {
   clientName = defaultClientName(), launchBrowser = true, notify, open = openBrowser,
   sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)), now = () => Date.now(),
@@ -50,5 +49,5 @@ export async function browserLogin(client, {
     if (result.status === 202) continue;
     return result.body;
   }
-  throw new ApiError('브라우저 승인 시간이 지났습니다. sentinelctl login을 다시 실행하세요.', { code: 'expired_token' });
+  throw new ApiError('Browser approval timed out.', { code: 'expired_token' });
 }

package/src/main.mjs

@@ -1,23 +1,31 @@
 import { readFileSync } from 'node:fs';
-import { parseArguments, UsageError } from './args.mjs';
+import { closest, parseArguments, UsageError } from './args.mjs';
 import { ApiError, createClient } from './client.mjs';
-import { commandTable, outputChoices, standaloneCommands } from './commands.mjs';
-import { credentialsPath, normalizeServer, removeProfile, resolveConnection, saveProfile } from './credentials.mjs';
+import { catalog, commandPath, findCommand, groups, outputChoices, roleLabels, usageLine } from './commands.mjs';
+import { credentialsPath, normalizeServer, readCredentials, removeProfile, resolveConnection, saveProfile, writeCredentials } from './credentials.mjs';
 import { renderKeyValues } from './format.mjs';
 import { browserLogin, openBrowser } from './login.mjs';
 
 const version = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version;
-const roleLabels = { viewer: '조회 전용', editor: '편집 가능', admin: '관리자' };
+const roleRank = { viewer: 0, editor: 1, admin: 2 };
+const exitCodes = { 0: 'success', 1: 'server or network error', 2: 'usage error (fix the arguments)', 3: 'not logged in or insufficient role (retrying will not help)' };
 const globalDefinitions = {
-  server: { type: 'string' },
-  profile: { type: 'string' },
-  output: { alias: 'o', type: 'string' },
-  json: { type: 'boolean' },
-  help: { alias: 'h', type: 'boolean' },
-  version: { alias: 'V', type: 'boolean' },
+  server: { type: 'string', placeholder: 'url', description: 'Console URL (default https://monitor.intflow.dev; also SENTINEL_URL).' },
+  profile: { type: 'string', placeholder: 'name', description: 'Saved login profile (default "default").' },
+  output: { alias: 'o', type: 'string', choices: outputChoices, description: 'Output format. Use json or ndjson from agents and scripts.' },
+  json: { type: 'boolean', description: 'Same as -o json.' },
+  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.' },
+};
+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]' },
+  help: { summary: 'Help: help <command>, help agents (guide for AI agents)', usage: 'sentinelctl help [<command> | agents]' },
 };
 
-// 전역 옵션은 명령 앞뒤 어디에 와도 되게 먼저 떼어 낸다.
 export function splitGlobalOptions(argv) {
   const global = [];
   const rest = [];
@@ -40,29 +48,129 @@ export function splitGlobalOptions(argv) {
   return { global: parseArguments(global, globalDefinitions).options, rest };
 }
 
-function helpText() {
+function roleOf(command, options) {
+  return command.roleFor?.(options) ?? command.role;
+}
+
+function optionLines(options) {
+  return Object.entries(options).map(([name, spec]) => {
+    const value = spec.type === 'boolean' ? '' : ` <${spec.choices ? spec.choices.join('|') : spec.placeholder ?? 'value'}>`;
+    const flag = `${spec.alias ? `-${spec.alias}, ` : '    '}--${name}${value}`;
+    const suffix = [spec.multiple ? 'repeatable' : null, spec.default !== undefined ? `default ${spec.default}` : null].filter(Boolean).join(', ');
+    return `  ${flag}\n        ${spec.description ?? ''}${suffix ? ` (${suffix})` : ''}`;
+  });
+}
+
+function commandHelp(command) {
+  const lines = [
+    `Usage: ${usageLine(command)}`,
+    '',
+    command.summary + (command.description ? `\n${command.description}` : ''),
+    '',
+    `Requires: ${roleLabels[command.role]}${command.roleNote ? ` (${command.roleNote})` : ''} · ${command.mutates ? 'changes data' : 'read-only'}`,
+  ];
+  if (command.args?.length) {
+    lines.push('', 'Arguments:', ...command.args.map((arg) => `  ${arg.optional ? `[${arg.name}]` : `<${arg.name}>`}  ${arg.description ?? ''}`));
+  }
+  if (Object.keys(command.options).length) lines.push('', 'Options:', ...optionLines(command.options));
+  lines.push('', 'Examples:', ...command.examples.map((example) => `  ${example}`));
+  lines.push('', `Output: ${command.output}`);
+  lines.push('', 'Global: -o table|json|ndjson, --server <url>, --profile <name>, --quiet.',
+    `Exit codes: ${Object.entries(exitCodes).map(([code, meaning]) => `${code} ${meaning}`).join(' · ')}.`);
+  return lines.join('\n');
+}
+
+function groupHelp(group) {
+  const members = catalog.filter((command) => command.group === group);
+  return [`Usage: sentinelctl ${group} <command> [options]`, '', groups[group], '',
+    ...members.map((command) => `  ${command.name.padEnd(10)} ${command.summary}${command.role === 'viewer' ? '' : ` [${command.role}]`}`),
+    '', `Details: sentinelctl ${group} <command> --help`].join('\n');
+}
+
+function overviewHelp() {
   const lines = [
-    `sentinelctl ${version} — Sentinel Fleet Console 명령행 도구`,
+    `sentinelctl ${version} — Sentinel Fleet Console CLI: device metrics, logs and metadata`,
     '',
-    '사용법: sentinelctl [--server URL] [--profile 이름] [-o table|json|ndjson] <명령> …',
+    'Usage: sentinelctl [global options] <command> [subcommand] [arguments] [options]',
     '',
-    '인증:',
-    '  login [--no-browser]   브라우저에서 Intflow 계정으로 승인하고 CLI 토큰을 저장',
-    '  logout                 서버의 CLI 토큰을 폐기하고 로컬 자격 증명을 삭제',
-    '  whoami                 현재 사용자·권한 확인',
+    'Getting started:',
+    '  sentinelctl login                              approve once in the browser (valid for 30 days)',
+    '  sentinelctl devices list --status offline',
+    '  sentinelctl logs search -l error -r 1h',
     '',
-    '명령:',
+    'Authentication:',
+    ...['login', 'logout', 'whoami'].map((name) => `  ${name.padEnd(10)} ${specialCommands[name].summary}`),
+    '',
+    'Commands:',
   ];
-  for (const [group, definition] of Object.entries(commandTable)) {
-    lines.push(`  ${group.padEnd(10)} ${definition.summary}`);
-    for (const command of Object.values(definition.commands)) lines.push(`      sentinelctl ${command.usage}`);
+  for (const [group, summary] of Object.entries(groups)) {
+    lines.push(`  ${group.padEnd(10)} ${summary}`);
+    for (const command of catalog.filter((item) => item.group === group)) {
+      lines.push(`      ${command.name.padEnd(10)} ${command.summary}${command.role === 'viewer' ? '' : ` [${command.role}]`}`);
+    }
   }
-  for (const [name, command] of Object.entries(standaloneCommands)) lines.push(`  ${name.padEnd(10)} ${command.summary} — sentinelctl ${command.usage}`);
-  lines.push('', '환경 변수: SENTINEL_URL(서버), SENTINEL_TOKEN(토큰, 자동화용), SENTINELCTL_CONFIG(자격 증명 파일 경로)',
-    `기본 서버: https://monitor.intflow.dev · 자격 증명: ${credentialsPath()}`);
+  for (const command of catalog.filter((item) => !item.group)) lines.push(`  ${command.name.padEnd(10)} ${command.summary}`);
+  lines.push(`  ${'commands'.padEnd(10)} ${specialCommands.commands.summary}`);
+  lines.push('', 'Global options:', ...optionLines(globalDefinitions));
+  lines.push('', 'More: sentinelctl <command> <subcommand> --help · Guide for AI agents: sentinelctl help agents',
+    `Environment: SENTINEL_URL (server), SENTINEL_TOKEN (token for automation), SENTINELCTL_CONFIG (credentials file, default ${credentialsPath()})`);
   return lines.join('\n');
 }
 
+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.`;
+
+function commandsCatalog() {
+  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) => ({
+        command: commandPath(command), usage: usageLine(command), summary: command.summary, description: command.description ?? null,
+        role: command.role, roleNote: command.roleNote ?? null, mutates: command.mutates, args: command.args ?? [],
+        options: Object.fromEntries(Object.entries(command.options).map(([name, spec]) => [name, {
+          alias: spec.alias ?? null, type: spec.type, choices: spec.choices ?? null, default: spec.default ?? null,
+          multiple: Boolean(spec.multiple), description: spec.description ?? null,
+        }])),
+        examples: command.examples, output: command.output,
+      })),
+    ],
+  };
+}
+
 async function login(context, argv) {
   const { options } = parseArguments(argv, { 'no-browser': { type: 'boolean' }, name: { type: 'string' } });
   const client = createClient({ server: context.connection.server, fetch: context.fetch });
@@ -72,16 +180,17 @@ async function login(context, argv) {
     open: context.openBrowser,
     sleep: context.sleep,
     notify: ({ verificationUrl, userCode, expiresIn }) => {
-      context.err('아래 주소를 브라우저에서 열고 Intflow 계정으로 로그인한 뒤 승인하세요.');
+      context.err('Open this URL, sign in with your Intflow account and approve:');
       context.err(`  ${verificationUrl}`);
-      context.err(`확인 코드: ${userCode}  (브라우저에 표시된 코드와 같은지 확인하세요 · ${Math.round(expiresIn / 60)}분 안에 승인)`);
+      context.err(`Confirmation code: ${userCode}  (check the browser shows the same code; approve within ${Math.round(expiresIn / 60)} minutes)`);
     },
   });
   await saveProfile(context.connection.path, context.global.profile ?? 'default', {
     server: context.connection.server, token: result.token, tokenId: result.tokenId,
     user: result.identity.user, role: result.identity.role, expiresAt: result.expiresAt,
   });
-  context.out(`로그인했습니다: ${result.identity.user} (${roleLabels[result.identity.role] ?? result.identity.role}) · 토큰 만료 ${result.expiresAt}`);
+  context.out(`Logged in as ${result.identity.user} (${roleLabels[result.identity.role] ?? result.identity.role}). Token expires ${result.expiresAt}.`);
+  context.hint('Next: sentinelctl devices list, or sentinelctl logs search -l error -r 1h (all commands: sentinelctl --help).');
 }
 
 async function logout(context) {
@@ -91,87 +200,202 @@ async function logout(context) {
       await context.client.post('/api/logout', {});
     } catch (error) {
       if (!(error instanceof ApiError) || error.status !== 401) {
-        context.err(`서버에서 토큰을 폐기하지 못했습니다: ${error.message}. 로컬 자격 증명은 삭제합니다.`);
+        context.err(`Could not revoke the token on the server (${error.message}). Local credentials are deleted anyway.`);
       }
     }
   }
   const removed = await removeProfile(context.connection.path, profileName);
-  context.out(removed ? '로그아웃했습니다.' : '저장된 로그인 정보가 없습니다.');
+  context.out(removed ? 'Logged out.' : 'No saved login to remove.');
+}
+
+async function rememberRole(context, role) {
+  const saved = context.connection.profile;
+  if (!saved || context.connection.fromEnvironment || saved.role === role) return;
+  const credentials = await readCredentials(context.connection.path);
+  const name = context.global.profile ?? 'default';
+  if (!credentials.profiles[name]) return;
+  credentials.profiles[name].role = role;
+  await writeCredentials(context.connection.path, credentials);
 }
 
 async function whoami(context) {
   const identity = await context.client.get('/api/session');
+  await rememberRole(context, identity.role);
   if (context.global.output === 'json' || context.global.output === 'ndjson') {
     context.out(JSON.stringify({ server: context.connection.server, ...identity, tokenExpiresAt: context.connection.profile?.expiresAt ?? null }));
     return;
   }
   context.out(renderKeyValues([
-    ['서버', context.connection.server], ['사용자', identity.user], ['이름', identity.name],
-    ['권한', roleLabels[identity.role] ?? identity.role], ['토큰 ID', identity.sessionId],
-    ['토큰 만료', context.connection.profile?.expiresAt],
+    ['Server', context.connection.server], ['User', identity.user], ['Name', identity.name],
+    ['Role', roleLabels[identity.role] ?? identity.role], ['Token ID', identity.sessionId],
+    ['Token expires', context.connection.profile?.expiresAt],
   ]));
 }
 
+class PermissionError extends Error {
+  constructor(required, current) {
+    super(`This command requires the ${required} role (you are ${current}).`);
+    this.required = required;
+    this.current = current;
+  }
+}
+
+async function ensureRole(context, required) {
+  if (!required || required === 'viewer' || !context.connection.token) return;
+  const cached = context.connection.fromEnvironment ? null : context.connection.profile?.role;
+  if (!cached || roleRank[cached] >= roleRank[required]) return;
+  const identity = await context.client.get('/api/session');
+  await rememberRole(context, identity.role);
+  if (roleRank[identity.role] < roleRank[required]) throw new PermissionError(required, identity.role);
+}
+
+function apiHint(error, context, command) {
+  if (error.code === 'network_error') return `Check the server (--server or SENTINEL_URL) and the network. Current server: ${context.connection.server}`;
+  if (error.code === 'not_logged_in') return 'Run `sentinelctl login` and approve in the browser.';
+  if (error.code === 'expired_token') return 'Run `sentinelctl login` again and approve within 5 minutes.';
+  if (error.status === 401) {
+    return context.connection.fromEnvironment
+      ? 'SENTINEL_TOKEN has expired or was revoked; supply a new token.'
+      : 'The CLI token has expired or was revoked. Run `sentinelctl login` again.';
+  }
+  if (error.status === 403) {
+    const required = command ? roleOf(command, context.options ?? {}) : null;
+    return `Insufficient role${required && required !== 'viewer' ? ` (requires ${required})` : ''}. Ask an admin to run \`sentinelctl admin grant <your-email> --role <role>\`; check yours with \`sentinelctl whoami\`.`;
+  }
+  if (error.status === 404) {
+    return command?.group === 'devices' || command?.group === 'metadata'
+      ? '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.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.';
+  }
+  if (error.status >= 500) return 'Server or backend error. Check `sentinelctl health` and retry shortly.';
+  return null;
+}
+
+function unknownCommandError(name, candidates, prefix = '') {
+  const suggestion = closest(name, candidates);
+  return new UsageError(`Unknown command: ${prefix}${name}`,
+    { hint: `${suggestion ? `Did you mean \`sentinelctl ${prefix}${suggestion}\`? ` : ''}All commands: sentinelctl --help` });
+}
+
 export async function main(argv, {
   stdout = process.stdout, stderr = process.stderr, environment = process.env, fetch = globalThis.fetch,
   sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)), openBrowser: open = openBrowser, signal,
 } = {}) {
   const out = (text) => stdout.write(`${text}\n`);
   const err = (text) => stderr.write(`${text}\n`);
+  let global = { output: 'table' };
+  let command = null;
+  let context = null;
+  const report = (error, hint, exitCode) => {
+    if (global.output === 'json' || global.output === 'ndjson') {
+      err(JSON.stringify({ error: { status: error.status ?? null, code: error.code ?? error.name ?? null, message: error.message, hint: hint ?? null, exitCode } }));
+    } else {
+      err(`${error instanceof UsageError ? 'usage error' : 'error'}: ${error.message}`);
+      if (hint) err(`hint: ${hint}`);
+    }
+    return exitCode;
+  };
   try {
-    const { global, rest } = splitGlobalOptions(argv);
+    const split = splitGlobalOptions(argv);
+    global = split.global;
+    global.output = global.json ? 'json' : (global.output ?? 'table');
     if (global.version) {
       out(version);
       return 0;
     }
-    global.output = global.json ? 'json' : (global.output ?? 'table');
-    if (!outputChoices.includes(global.output)) throw new UsageError('-o는 table, json, ndjson 중 하나여야 합니다.');
-    const [name, subcommand, ...commandArguments] = rest;
-    if (!name || global.help || name === 'help') {
-      out(helpText());
-      return name || global.help || name === 'help' ? 0 : 2;
+    const [name, subcommand, ...commandArguments] = split.rest;
+    const wantsHelp = global.help;
+    if (!name) {
+      out(overviewHelp());
+      return wantsHelp ? 0 : 2;
     }
-    if (global.server) global.server = normalizeServer(global.server);
-    const connection = await resolveConnection({ server: global.server, profile: global.profile ?? 'default', environment,
-      path: credentialsPath(environment) });
-    const context = {
-      global, connection, out, err, fetch, sleep, signal, openBrowser: open, width: stdout.columns ?? 120,
-      client: createClient({ server: connection.server, token: connection.token, fetch, sleep }),
-    };
-    if (name === 'login') {
-      await login(context, [subcommand, ...commandArguments].filter((item) => item !== undefined));
+    if (name === 'help') {
+      if (!subcommand) out(overviewHelp());
+      else if (subcommand === 'agents') out(agentGuide);
+      else if (specialCommands[subcommand]) out(`Usage: ${specialCommands[subcommand].usage}\n\n${specialCommands[subcommand].summary}`);
+      else if (groups[subcommand] && !commandArguments[0]) out(groupHelp(subcommand));
+      else {
+        const target = groups[subcommand] ? findCommand(subcommand, commandArguments[0]) : findCommand(null, subcommand);
+        if (!target) {
+          throw unknownCommandError([subcommand, commandArguments[0]].filter(Boolean).join(' '),
+            [...Object.keys(groups), ...Object.keys(specialCommands), ...catalog.filter((item) => !item.group).map((item) => item.name), 'agents'], 'help ');
+        }
+        out(commandHelp(target));
+      }
       return 0;
     }
-    if (name === 'logout') {
-      await logout(context);
+    if (name === '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'));
+      } else {
+        out(JSON.stringify(commandsCatalog(), null, global.output === 'json' ? 2 : 0));
+      }
       return 0;
     }
-    if (name === 'whoami') {
-      await whoami(context);
+    if (specialCommands[name] && wantsHelp) {
+      out(`Usage: ${specialCommands[name].usage}\n\n${specialCommands[name].summary}`);
       return 0;
     }
-    if (standaloneCommands[name]) {
-      await standaloneCommands[name].run(context, [subcommand, ...commandArguments].filter((item) => item !== undefined));
+
+    if (groups[name]) {
+      command = findCommand(name, subcommand);
+      if (!command) {
+        if (!subcommand || wantsHelp) {
+          out(groupHelp(name));
+          return subcommand || wantsHelp ? 0 : 2;
+        }
+        throw unknownCommandError(subcommand, catalog.filter((item) => item.group === name).map((item) => item.name), `${name} `);
+      }
+    } else if (!specialCommands[name]) {
+      command = findCommand(null, name);
+      if (!command) throw unknownCommandError(name, [...Object.keys(groups), ...Object.keys(specialCommands), ...catalog.filter((item) => !item.group).map((item) => item.name)]);
+    }
+    const commandArgv = command?.group ? commandArguments : [subcommand, ...commandArguments].filter((item) => item !== undefined);
+    if (command && wantsHelp) {
+      out(commandHelp(command));
       return 0;
     }
-    const group = commandTable[name];
-    if (!group) throw new UsageError(`알 수 없는 명령입니다: ${name}. sentinelctl --help를 확인하세요.`);
-    const command = group.commands[subcommand];
-    if (!command) {
-      throw new UsageError(`${name} 하위 명령이 필요합니다:\n${Object.values(group.commands).map((item) => `  sentinelctl ${item.usage}`).join('\n')}`);
+
+    if (global.server) global.server = normalizeServer(global.server);
+    const connection = await resolveConnection({ server: global.server, profile: global.profile ?? 'default', environment,
+      path: credentialsPath(environment) });
+    context = {
+      global, connection, out, err, fetch, sleep, signal, openBrowser: open, width: stdout.columns ?? 120,
+      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 }),
+    };
+    if (name === 'login') { await login(context, commandArgv); return 0; }
+    if (name === 'logout') { await logout(context); return 0; }
+    if (name === 'whoami') { await whoami(context); return 0; }
+
+    let parsed;
+    try {
+      parsed = parseArguments(commandArgv, command.options);
+    } catch (error) {
+      if (error instanceof UsageError) error.hint = [error.hint, `Usage: ${usageLine(command)} (details: --help)`].filter(Boolean).join(' · ');
+      throw error;
     }
-    await command.run(context, commandArguments);
+    context.options = parsed.options;
+    await ensureRole(context, roleOf(command, parsed.options));
+    await command.run(context, parsed);
     return 0;
   } catch (error) {
     if (error instanceof UsageError) {
-      err(`사용법 오류: ${error.message}`);
-      return 2;
+      return report(error, error.hint ?? (command ? `Usage: ${usageLine(command)} (details: --help)` : null), 2);
+    }
+    if (error instanceof PermissionError) {
+      return report(Object.assign(error, { status: 403, code: 'insufficient_role' }),
+        `Ask an admin to run \`sentinelctl admin grant <your-email> --role ${error.required}\`. Nothing was sent to the server.`, 3);
     }
     if (error instanceof ApiError) {
-      err(`오류: ${error.message}`);
-      return error.status === 401 || error.status === 403 ? 3 : 1;
+      const exitCode = error.status === 401 || error.status === 403 || error.code === 'not_logged_in' ? 3 : 1;
+      return report(error, apiHint(error, context ?? { connection: {} }, command), exitCode);
     }
-    err(`오류: ${error.message}`);
-    return 1;
+    return report(error, null, 1);
   }
 }