@intflow/sentinelctl 0.1.0

package/README.md

@@ -0,0 +1,91 @@
+# sentinelctl
+
+Sentinel Fleet Console(`https://monitor.intflow.dev`)을 터미널에서 쓰는 명령행 도구입니다. 로그 검색, 장비 조회, 메타데이터 변경, 사용자 권한 관리를 지원합니다. 웹 콘솔과 같은 Intflow(Google Workspace) 로그인과 같은 역할 검사를 사용합니다.
+
+- Node.js 20 이상, 외부 의존성 없음
+- 권한: `viewer`는 조회만, `editor`는 메타데이터 변경까지, `admin`은 원본 로그 필드·가져오기/내보내기·사용자 관리까지 가능합니다. 권한은 서버가 판정하며 CLI는 서버 결과를 그대로 보여 줍니다.
+
+## 설치
+
+```bash
+npm install -g @intflow/sentinelctl
+```
+
+## 로그인
+
+```bash
+sentinelctl login
+```
+
+1. 터미널에 승인 주소와 확인 코드(예: `BCDF-GHJK`)가 나타나고 브라우저가 열립니다. 원격 셸이면 `--no-browser`를 주고 주소를 직접 엽니다.
+2. 브라우저에서 Intflow 계정으로 로그인한 뒤, 화면의 확인 코드가 터미널과 같은지 보고 **승인**합니다.
+3. CLI가 토큰(기본 30일)을 받아 자격 증명 파일에 0600 권한으로 저장합니다.
+
+```bash
+sentinelctl whoami
+sentinelctl sessions list          # 내 웹 세션·CLI 토큰
+sentinelctl logout                 # 서버에서 토큰 폐기 + 로컬 삭제
+```
+
+자격 증명 파일 위치는 Linux/macOS `~/.config/sentinelctl/credentials.json`, Windows `%APPDATA%\sentinelctl\credentials.json`이며 `SENTINELCTL_CONFIG`로 바꿀 수 있습니다. 서버는 `--server`, `SENTINEL_URL`, 저장된 프로필, 기본값 순서로 정합니다. 자동화에서는 파일 대신 `SENTINEL_TOKEN` 환경 변수를 쓸 수 있습니다.
+
+## 로그
+
+```bash
+sentinelctl logs search timeout -r 1h                      # 최근 1시간 "timeout" 검색
+sentinelctl logs search -a agent-123 -l error -r 24h --all # 장비·수준 필터, 모든 페이지
+sentinelctl logs search -s sshd.service --from 2026-09-30T00:00:00Z --to 2026-09-30T06:00:00Z
+sentinelctl logs search -l error -f                        # 새 오류 로그 따라가기(Ctrl+C 종료)
+sentinelctl logs search -q boom -o ndjson | jq .message    # 기계 처리용 출력
+sentinelctl logs context -a agent-123 -s app.service -t 2026-09-30T01:02:03.456Z
+sentinelctl logs histogram -l error -r 24h
+sentinelctl logs sources -r 24h
+```
+
+검색 범위는 `15m`·`1h`·`6h`·`24h`·`7d` 또는 최대 30일의 `--from`/`--to`입니다. 한 페이지는 `-n 50|100|250`건이고 서버 상한 때문에 최대 10,000건까지 이어서 가져옵니다. `--fields`(원본 필드)는 관리자 전용이며 감사 로그에 남습니다.
+
+## 장비와 메타데이터
+
+```bash
+sentinelctl devices list --status offline
+sentinelctl devices list 서울 --site seoul --all -o json
+sentinelctl devices show agent-123 -r 24h
+sentinelctl devices lookup edge-01
+sentinelctl health
+
+sentinelctl metadata get agent-123
+sentinelctl metadata history agent-123
+sentinelctl metadata set agent-123 --display-name "엣지 1" --maintainer 홍길동 --label site=seoul   # editor 이상
+sentinelctl metadata set agent-123 --lifecycle maintenance --maintenance-until 2026-10-01T09:00:00+09:00
+sentinelctl metadata rollback agent-123 --to 3
+sentinelctl metadata export --file backup.json                                                     # admin
+sentinelctl metadata import backup.json --dry-run                                                  # admin
+```
+
+`metadata set`은 현재 변경 버전을 읽은 뒤 그 버전으로 수정합니다. 그 사이 다른 사람이 바꿨으면 서버가 `409`로 거부하므로 다시 실행하면 됩니다.
+
+## 관리자
+
+```bash
+sentinelctl admin users
+sentinelctl admin grant kim@intflow.ai --role editor   # 첫 로그인 전에도 지정 가능
+sentinelctl admin reset kim@intflow.ai                 # 콘솔 지정 권한 삭제(기본 viewer)
+sentinelctl admin disable kim@intflow.ai               # 접근 중지 + 모든 세션·CLI 토큰 즉시 종료
+sentinelctl admin sessions --kind cli
+sentinelctl admin revoke <세션 ID>
+```
+
+그 밖의 API는 `sentinelctl api /api/operations?range=7d`처럼 직접 호출할 수 있습니다.
+
+## 출력과 종료 코드
+
+- `-o table`(기본), `-o json`(`--json`), `-o ndjson`
+- 종료 코드: `0` 성공, `1` 서버·네트워크 오류, `2` 사용법 오류, `3` 인증 필요 또는 권한 부족
+
+## 배포
+
+```bash
+cd cli
+npm test
+npm publish --access public
+```

package/bin/sentinelctl.mjs

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { main } from '../src/main.mjs';
+
+process.exitCode = await main(process.argv.slice(2));

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@intflow/sentinelctl",
+  "version": "0.1.0",
+  "description": "Sentinel Fleet Console 명령행 도구: 로그 검색, 장비 조회, 메타데이터·권한 관리",
+  "type": "module",
+  "bin": {
+    "sentinelctl": "bin/sentinelctl.mjs"
+  },
+  "exports": {
+    ".": "./src/main.mjs"
+  },
+  "files": [
+    "bin",
+    "src",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "test": "node --test test/*.test.mjs",
+    "check": "node --check bin/sentinelctl.mjs && node --check src/main.mjs && node --check src/args.mjs && node --check src/credentials.mjs && node --check src/client.mjs && node --check src/login.mjs && node --check src/format.mjs && node --check src/commands.mjs"
+  },
+  "license": "UNLICENSED",
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/args.mjs

@@ -0,0 +1,72 @@
+export class UsageError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'UsageError';
+  }
+}
+
+// 옵션 정의: { name: { alias, type: 'string'|'boolean'|'integer', multiple } }
+// "--name value", "--name=value", "-a value", "--flag", "--no-flag"를 지원한다.
+export function parseArguments(argv, definitions) {
+  const options = {};
+  const positionals = [];
+  const aliases = new Map(Object.entries(definitions).filter(([, spec]) => spec.alias).map(([name, spec]) => [spec.alias, name]));
+  for (let index = 0; index < argv.length; index += 1) {
+    const argument = argv[index];
+    if (argument === '--') {
+      positionals.push(...argv.slice(index + 1));
+      break;
+    }
+    if (!argument.startsWith('-') || argument === '-') {
+      positionals.push(argument);
+      continue;
+    }
+    let name;
+    let value;
+    if (argument.startsWith('--')) {
+      const body = argument.slice(2);
+      const separator = body.indexOf('=');
+      name = separator >= 0 ? body.slice(0, separator) : body;
+      value = separator >= 0 ? body.slice(separator + 1) : undefined;
+      if (!definitions[name] && name.startsWith('no-') && definitions[name.slice(3)]?.type === 'boolean' && value === undefined) {
+        options[name.slice(3)] = false;
+        continue;
+      }
+    } else {
+      name = aliases.get(argument.slice(1));
+      if (!name) throw new UsageError(`알 수 없는 옵션입니다: ${argument}`);
+    }
+    const spec = definitions[name];
+    if (!spec) throw new UsageError(`알 수 없는 옵션입니다: --${name}`);
+    if (spec.type === 'boolean') {
+      if (value !== undefined) throw new UsageError(`--${name}에는 값을 줄 수 없습니다.`);
+      options[name] = true;
+      continue;
+    }
+    if (value === undefined) {
+      value = argv[index + 1];
+      if (value === undefined) throw new UsageError(`--${name}에 값이 필요합니다.`);
+      index += 1;
+    }
+    let parsed = value;
+    if (spec.type === 'integer') {
+      parsed = Number(value);
+      if (!Number.isInteger(parsed)) throw new UsageError(`--${name}은 정수여야 합니다.`);
+    }
+    if (spec.choices && !spec.choices.includes(parsed)) {
+      throw new UsageError(`--${name}은 ${spec.choices.join(', ')} 중 하나여야 합니다.`);
+    }
+    if (spec.multiple) (options[name] ??= []).push(parsed);
+    else options[name] = parsed;
+  }
+  for (const [name, spec] of Object.entries(definitions)) {
+    if (options[name] === undefined && spec.default !== undefined) options[name] = spec.default;
+  }
+  return { options, positionals };
+}
+
+export function keyValue(value, label) {
+  const separator = String(value).indexOf('=');
+  if (separator < 1) throw new UsageError(`${label}은 key=value 형식이어야 합니다: ${value}`);
+  return [value.slice(0, separator), value.slice(separator + 1)];
+}

package/src/client.mjs

@@ -0,0 +1,66 @@
+export class ApiError extends Error {
+  constructor(message, { status, code, retryAfterSeconds, body } = {}) {
+    super(message);
+    this.name = 'ApiError';
+    this.status = status;
+    this.code = code;
+    this.retryAfterSeconds = retryAfterSeconds;
+    this.body = body;
+  }
+}
+
+const userAgent = 'sentinelctl';
+
+export function createClient({ server, token = null, fetch: fetchImplementation = globalThis.fetch, timeoutMs = 60_000, maxRetries = 2, sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)) }) {
+  async function request(method, path, { query, body, auth = true, allowStatuses = [] } = {}) {
+    const url = new URL(path, server);
+    for (const [key, value] of Object.entries(query ?? {})) {
+      if (value === undefined || value === null || value === '') continue;
+      if (Array.isArray(value)) for (const item of value) url.searchParams.append(key, String(item));
+      else url.searchParams.set(key, String(value));
+    }
+    const headers = { accept: 'application/json', 'user-agent': userAgent };
+    if (auth) {
+      if (!token) throw new ApiError('로그인이 필요합니다. sentinelctl login을 먼저 실행하세요.', { status: 401, code: 'not_logged_in' });
+      headers.authorization = `Bearer ${token}`;
+    }
+    if (body !== undefined) headers['content-type'] = 'application/json';
+    for (let attempt = 0; ; attempt += 1) {
+      let response;
+      try {
+        response = await fetchImplementation(url, {
+          method, headers, body: body === undefined ? undefined : JSON.stringify(body),
+          redirect: 'error', signal: AbortSignal.timeout(timeoutMs),
+        });
+      } catch (error) {
+        const reason = error?.name === 'TimeoutError' ? '응답 시간이 초과되었습니다' : '연결하지 못했습니다';
+        throw new ApiError(`${url.origin}에 ${reason}.`, { code: 'network_error' });
+      }
+      const text = await response.text();
+      let payload = {};
+      try {
+        payload = text ? JSON.parse(text) : {};
+      } catch {
+        payload = { error: text.slice(0, 200) };
+      }
+      const retryAfterSeconds = Number(response.headers.get('retry-after')) || null;
+      // 429는 서버가 알려 준 시간만큼 기다렸다가 GET만 다시 시도한다. 변경 요청은 중복 실행을 막기 위해 재시도하지 않는다.
+      if (response.status === 429 && method === 'GET' && attempt < maxRetries) {
+        await sleep(Math.min(retryAfterSeconds ?? 1, 30) * 1_000);
+        continue;
+      }
+      if (response.ok || allowStatuses.includes(response.status)) return { status: response.status, body: payload };
+      let message = payload.error || `HTTP ${response.status}`;
+      if (response.status === 401 && auth) message = `${message} (sentinelctl login으로 다시 로그인하세요)`;
+      if (retryAfterSeconds) message += ` · ${retryAfterSeconds}초 뒤 다시 시도해 주세요.`;
+      throw new ApiError(message, { status: response.status, code: payload.code, retryAfterSeconds, body: payload });
+    }
+  }
+  return {
+    server,
+    request,
+    get: async (path, query, options) => (await request('GET', path, { ...options, query })).body,
+    post: async (path, body, options) => (await request('POST', path, { ...options, body })).body,
+    patch: async (path, body, options) => (await request('PATCH', path, { ...options, body })).body,
+  };
+}

package/src/commands.mjs

@@ -0,0 +1,478 @@
+import { readFile, writeFile } from 'node:fs/promises';
+import { keyValue, parseArguments, UsageError } from './args.mjs';
+import { ageText, localTime, percentText, renderKeyValues, renderTable, singleLine } from './format.mjs';
+
+const roleLabels = { viewer: '조회 전용', editor: '편집 가능', admin: '관리자' };
+const outputChoices = ['table', 'json', 'ndjson'];
+const logRanges = ['15m', '1h', '6h', '24h', '7d'];
+const logLevels = ['emergency', 'critical', 'error', 'warning', 'info', 'debug'];
+
+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' },
+};
+
+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는 함께 쓸 수 없습니다.');
+  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,
+  };
+}
+
+function emit(context, value, table) {
+  const { output } = context.global;
+  if (output === 'json') context.out(JSON.stringify(value, null, 2));
+  else if (output === 'ndjson') for (const item of Array.isArray(value) ? value : [value]) context.out(JSON.stringify(item));
+  else context.out(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 },
+];
+
+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);
+  const logs = [];
+  let cursor;
+  let last;
+  for (let page = 0; page < maxPages; page += 1) {
+    last = await context.client.get('/api/logs', { ...criteria, 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)}`);
+  }
+}
+
+async function followLogs(context, criteria, 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 };
+  let first = true;
+  context.err('새 로그를 기다립니다. Ctrl+C로 종료합니다.');
+  while (!context.signal?.aborted) {
+    const body = await context.client.get('/api/logs', followCriteria);
+    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을 줄이세요.`);
+    }
+    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);
+    const visible = first ? fresh.slice(-20) : fresh;
+    if (visible.length) {
+      if (context.global.output === 'table') {
+        const rendered = renderTable(visible, logColumns, { width: context.width, wide: options.wide }).split('\n');
+        context.out((first ? rendered : rendered.slice(1)).join('\n'));
+      } else {
+        for (const log of visible) context.out(JSON.stringify(log));
+      }
+    }
+    first = false;
+    await context.sleep(intervalMs);
+  }
+}
+
+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 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 }));
+}
+
+async function logsHistogram(context, argv) {
+  const { options, positionals } = parseArguments(argv, logFilterOptions);
+  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: '', value: (bucket) => '█'.repeat(Math.round((bucket.total / peak) * 30)) },
+    ], { width: context.width, wide: true });
+  });
+}
+
+async function logsSources(context, argv) {
+  const { options } = parseArguments(argv, { range: { alias: 'r', type: 'string', choices: logRanges, default: '24h' } });
+  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) },
+  ], { width: context.width }));
+}
+
+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: '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) },
+];
+
+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' },
+  });
+  for (const label of options.label ?? []) keyValue(label, '--label');
+  const query = {
+    query: [options.query, ...positionals].filter(Boolean).join(' ') || undefined,
+    status: options.status, lifecycle: options.lifecycle, role: options.role, site: options.site, group: options.group,
+    maintainer: options.maintainer, fleet: options.fleet, focus: options.focus, inventory: options.inventory,
+    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;
+  }
+  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 ?? ''}` : ''}`);
+  }
+}
+
+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 });
+  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 ?? ''})` : '최신'],
+  ]));
+}
+
+async function devicesLookup(context, argv) {
+  const { positionals } = parseArguments(argv, {});
+  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 },
+  ], { width: context.width }));
+}
+
+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가 필요합니다.');
+  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(', ')],
+  ]));
+}
+
+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]]),
+    '',
+    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 ?? '' },
+    ], { width: context.width }),
+  ].join('\n'));
+}
+
+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`);
+  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],
+  ]));
+}
+
+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 });
+  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(', ') },
+  ], { width: context.width }));
+}
+
+const metadataFieldOptions = {
+  'display-name': 'displayName', role: 'role', maintainer: 'maintainer', contact: 'maintainerContact',
+  description: 'description', lifecycle: 'lifecycle', 'maintenance-until': 'maintenanceUntil', 'maintenance-reason': 'maintenanceReason',
+};
+
+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);
+  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;
+  }
+  if (options.label?.length || options['remove-label']?.length) {
+    const labels = { ...(current.labels ?? {}) };
+    for (const item of options.label ?? []) {
+      const [key, value] = keyValue(item, '--label');
+      labels[key] = value;
+    }
+    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"');
+  const updated = await context.client.patch(path, patch);
+  emit(context, updated, () => `${agentId} 메타데이터를 변경 버전 ${updated.revision}으로 저장했습니다.`);
+}
+
+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 <변경 버전>이 필요합니다.');
+  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}).`);
+}
+
+async function metadataExport(context, argv) {
+  const { options } = parseArguments(argv, { file: { type: 'string' } });
+  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}에 저장했습니다.`);
+    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 파일 경로가 필요합니다.');
+  let payload;
+  try {
+    payload = JSON.parse(await readFile(positionals[0], 'utf8'));
+  } catch {
+    throw new UsageError(`JSON 파일을 읽을 수 없습니다: ${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));
+}
+
+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) },
+];
+
+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 },
+  ));
+}
+
+async function sessionsRevoke(context, argv) {
+  const { positionals } = parseArguments(argv, {});
+  if (!positionals[0]) throw new UsageError('폐기할 세션 ID가 필요합니다.');
+  await context.client.post(`/api/auth/sessions/${encodeURIComponent(positionals[0])}/revoke`, {});
+  context.out(`세션 ${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) },
+  ], { 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)}`);
+}
+
+async function adminSessions(context, argv) {
+  const { options } = parseArguments(argv, { kind: { type: 'string', choices: ['web', 'cli'] } });
+  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가 필요합니다.');
+  await context.client.post(`/api/admin/sessions/${encodeURIComponent(positionals[0])}/revoke`, {});
+  context.out(`세션 ${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' },
+  });
+  const [path] = positionals;
+  if (!path?.startsWith('/api/')) throw new UsageError('/api/로 시작하는 경로가 필요합니다.');
+  let body;
+  if (options.data !== undefined) {
+    try {
+      body = JSON.parse(options.data);
+    } catch {
+      throw new UsageError('--data는 JSON이어야 합니다.');
+    }
+  }
+  const url = new URL(path, context.client.server);
+  const result = await context.client.request(options.method, url.pathname, { query: Object.fromEntries(url.searchParams), body });
+  context.out(JSON.stringify(result.body, null, 2));
+}
+
+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]' },
+    },
+  },
+  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]' },
+    },
+  },
+  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]' },
+    },
+  },
+  sessions: {
+    summary: '내 웹 세션·CLI 토큰 조회와 폐기',
+    commands: {
+      list: { run: sessionsList, usage: 'sessions list' },
+      revoke: { run: sessionsRevoke, usage: 'sessions revoke <세션 ID>' },
+    },
+  },
+  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>' },
+    },
+  },
+};
+
+export const standaloneCommands = {
+  health: { run: health, usage: 'health', summary: '백엔드 연결 상태' },
+  api: { run: rawApi, usage: 'api <경로> [-X GET|POST|PATCH] [-d JSON]', summary: '콘솔 API 직접 호출(JSON 출력)' },
+};
+
+export { outputChoices, singleLine };

package/src/credentials.mjs

@@ -0,0 +1,76 @@
+import { chmod, mkdir, readFile, rename, rm, writeFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+
+export const defaultServer = 'https://monitor.intflow.dev';
+
+export function credentialsPath(environment = process.env, platform = process.platform) {
+  if (environment.SENTINELCTL_CONFIG) return environment.SENTINELCTL_CONFIG;
+  if (platform === 'win32' && environment.APPDATA) return join(environment.APPDATA, 'sentinelctl', 'credentials.json');
+  const base = environment.XDG_CONFIG_HOME || join(homedir(), '.config');
+  return join(base, 'sentinelctl', 'credentials.json');
+}
+
+export function normalizeServer(value) {
+  let url;
+  try {
+    url = new URL(String(value ?? ''));
+  } catch {
+    throw new Error(`서버 주소가 올바르지 않습니다: ${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');
+  }
+  if (url.protocol !== 'https:' && !(url.protocol === 'http:' && loopback)) {
+    throw new Error('서버 주소는 HTTPS여야 합니다(localhost만 HTTP 허용).');
+  }
+  return url.origin;
+}
+
+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('형식');
+    }
+    return parsed;
+  } catch (error) {
+    if (error.code === 'ENOENT') return { version: 1, profiles: {} };
+    throw new Error(`자격 증명 파일을 읽을 수 없습니다: ${path}`);
+  }
+}
+
+// 토큰 파일은 소유자만 읽을 수 있게 0600으로 쓰고, 임시 파일을 거쳐 원자적으로 교체한다.
+export async function writeCredentials(path, credentials) {
+  await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+  const temporary = `${path}.${process.pid}.tmp`;
+  await writeFile(temporary, `${JSON.stringify(credentials, null, 2)}\n`, { mode: 0o600 });
+  await chmod(temporary, 0o600).catch(() => {});
+  await rename(temporary, path);
+}
+
+export async function saveProfile(path, profileName, profile) {
+  const credentials = await readCredentials(path);
+  credentials.profiles[profileName] = profile;
+  await writeCredentials(path, credentials);
+}
+
+export async function removeProfile(path, profileName) {
+  const credentials = await readCredentials(path);
+  if (!credentials.profiles[profileName]) return false;
+  delete credentials.profiles[profileName];
+  if (Object.keys(credentials.profiles).length) await writeCredentials(path, credentials);
+  else await rm(path, { force: true });
+  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 token = environment.SENTINEL_TOKEN
+    ?? (saved && normalizeServer(saved.server) === resolvedServer ? saved.token : null);
+  return { server: resolvedServer, token: token ?? null, profile: saved, profileName: profile, path };
+}

package/src/format.mjs

@@ -0,0 +1,73 @@
+// 한글·CJK 전각 문자는 터미널에서 두 칸을 차지한다.
+const wideCharacter = /[ᄀ-ᅟ⺀-꓏가-힣豈-﫿︰-﹏＀-｠￠-￦]/u;
+
+export function displayWidth(value) {
+  let width = 0;
+  for (const character of String(value)) width += wideCharacter.test(character) ? 2 : 1;
+  return width;
+}
+
+export function truncate(value, maximum) {
+  const text = String(value ?? '');
+  if (maximum <= 0) return '';
+  if (displayWidth(text) <= maximum) return text;
+  let result = '';
+  let width = 0;
+  for (const character of text) {
+    const characterWidth = wideCharacter.test(character) ? 2 : 1;
+    if (width + characterWidth > maximum - 1) break;
+    result += character;
+    width += characterWidth;
+  }
+  return `${result}…`;
+}
+
+function pad(value, width) {
+  return `${value}${' '.repeat(Math.max(0, width - displayWidth(value)))}`;
+}
+
+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,
+    Math.max(displayWidth(column.header), ...cells.map((row) => displayWidth(row[index])))));
+  if (!wide && columns.length > 1) {
+    const fixed = widths.slice(0, -1).reduce((sum, value) => sum + value + 2, 0);
+    widths[widths.length - 1] = Math.max(10, Math.min(widths.at(-1), width - fixed));
+  }
+  const line = (values) => values.map((value, index) => (index === values.length - 1
+    ? (wide ? value : truncate(value, widths[index]))
+    : pad(truncate(value, widths[index]), widths[index]))).join('  ').trimEnd();
+  return [line(columns.map((column) => column.header)), ...cells.map(line)].join('\n');
+}
+
+export function renderKeyValues(entries) {
+  const visible = entries.filter(([, value]) => value !== undefined && value !== null && value !== '');
+  const width = Math.max(0, ...visible.map(([key]) => displayWidth(key)));
+  return visible.map(([key, value]) => `${pad(key, width)}  ${singleLine(value)}`).join('\n');
+}
+
+export function localTime(value) {
+  if (!value) return '-';
+  const date = typeof value === 'number' ? new Date(value * 1000) : new Date(value);
+  if (!Number.isFinite(date.getTime())) return String(value);
+  const offset = -date.getTimezoneOffset();
+  const local = new Date(date.getTime() + offset * 60_000).toISOString().slice(0, 19).replace('T', ' ');
+  return local;
+}
+
+export function percentText(value) {
+  return Number.isFinite(value) ? `${Math.round(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)}일 전`;
+}

package/src/login.mjs

@@ -0,0 +1,54 @@
+import { spawn } from 'node:child_process';
+import { createHash, randomBytes } from 'node:crypto';
+import { hostname } from 'node:os';
+import { ApiError } from './client.mjs';
+
+export function openBrowser(url, platform = process.platform) {
+  const [command, args] = platform === 'win32'
+    ? ['rundll32', ['url.dll,FileProtocolHandler', url]]
+    : [platform === 'darwin' ? 'open' : 'xdg-open', [url]];
+  try {
+    const child = spawn(command, args, { stdio: 'ignore', detached: true });
+    child.on('error', () => {});
+    child.unref();
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+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(),
+}) {
+  const pollSecret = randomBytes(32).toString('base64url');
+  const pollChallenge = createHash('sha256').update(pollSecret).digest('base64url');
+  const started = await client.post('/api/cli/login', { pollChallenge, clientName }, { auth: false });
+  notify({ verificationUrl: started.verificationUrl, userCode: started.userCode, expiresIn: started.expiresIn });
+  if (launchBrowser) open(started.verificationUrl);
+  const deadline = now() + started.expiresIn * 1_000;
+  const intervalMs = Math.max(1, Number(started.interval) || 2) * 1_000;
+  while (now() < deadline) {
+    await sleep(intervalMs);
+    let result;
+    try {
+      result = await client.request('POST', '/api/cli/login/redeem', {
+        auth: false, body: { requestId: started.requestId, pollSecret }, allowStatuses: [202],
+      });
+    } catch (error) {
+      if (error instanceof ApiError && error.status === 429) {
+        await sleep(Math.min(error.retryAfterSeconds ?? 5, 30) * 1_000);
+        continue;
+      }
+      throw error;
+    }
+    if (result.status === 202) continue;
+    return result.body;
+  }
+  throw new ApiError('브라우저 승인 시간이 지났습니다. sentinelctl login을 다시 실행하세요.', { code: 'expired_token' });
+}

package/src/main.mjs

@@ -0,0 +1,177 @@
+import { readFileSync } from 'node:fs';
+import { 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 { 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 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' },
+};
+
+// 전역 옵션은 명령 앞뒤 어디에 와도 되게 먼저 떼어 낸다.
+export function splitGlobalOptions(argv) {
+  const global = [];
+  const rest = [];
+  for (let index = 0; index < argv.length; index += 1) {
+    const argument = argv[index];
+    if (argument === '--') {
+      rest.push(...argv.slice(index));
+      break;
+    }
+    const name = argument.startsWith('--') ? argument.slice(2).split('=', 1)[0] : null;
+    const alias = argument.length === 2 && argument.startsWith('-') ? argument.slice(1) : null;
+    const spec = globalDefinitions[name] ?? Object.values(globalDefinitions).find((item) => item.alias && item.alias === alias);
+    if (!spec) {
+      rest.push(argument);
+      continue;
+    }
+    global.push(argument);
+    if (spec.type !== 'boolean' && !argument.includes('=') && index + 1 < argv.length) global.push(argv[++index]);
+  }
+  return { global: parseArguments(global, globalDefinitions).options, rest };
+}
+
+function helpText() {
+  const lines = [
+    `sentinelctl ${version} — Sentinel Fleet Console 명령행 도구`,
+    '',
+    '사용법: sentinelctl [--server URL] [--profile 이름] [-o table|json|ndjson] <명령> …',
+    '',
+    '인증:',
+    '  login [--no-browser]   브라우저에서 Intflow 계정으로 승인하고 CLI 토큰을 저장',
+    '  logout                 서버의 CLI 토큰을 폐기하고 로컬 자격 증명을 삭제',
+    '  whoami                 현재 사용자·권한 확인',
+    '',
+    '명령:',
+  ];
+  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 [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()}`);
+  return lines.join('\n');
+}
+
+async function login(context, argv) {
+  const { options } = parseArguments(argv, { 'no-browser': { type: 'boolean' }, name: { type: 'string' } });
+  const client = createClient({ server: context.connection.server, fetch: context.fetch });
+  const result = await browserLogin(client, {
+    clientName: options.name,
+    launchBrowser: !options['no-browser'],
+    open: context.openBrowser,
+    sleep: context.sleep,
+    notify: ({ verificationUrl, userCode, expiresIn }) => {
+      context.err('아래 주소를 브라우저에서 열고 Intflow 계정으로 로그인한 뒤 승인하세요.');
+      context.err(`  ${verificationUrl}`);
+      context.err(`확인 코드: ${userCode}  (브라우저에 표시된 코드와 같은지 확인하세요 · ${Math.round(expiresIn / 60)}분 안에 승인)`);
+    },
+  });
+  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}`);
+}
+
+async function logout(context) {
+  const profileName = context.global.profile ?? 'default';
+  if (context.connection.token) {
+    try {
+      await context.client.post('/api/logout', {});
+    } catch (error) {
+      if (!(error instanceof ApiError) || error.status !== 401) {
+        context.err(`서버에서 토큰을 폐기하지 못했습니다: ${error.message}. 로컬 자격 증명은 삭제합니다.`);
+      }
+    }
+  }
+  const removed = await removeProfile(context.connection.path, profileName);
+  context.out(removed ? '로그아웃했습니다.' : '저장된 로그인 정보가 없습니다.');
+}
+
+async function whoami(context) {
+  const identity = await context.client.get('/api/session');
+  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],
+  ]));
+}
+
+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`);
+  try {
+    const { global, rest } = splitGlobalOptions(argv);
+    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;
+    }
+    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));
+      return 0;
+    }
+    if (name === 'logout') {
+      await logout(context);
+      return 0;
+    }
+    if (name === 'whoami') {
+      await whoami(context);
+      return 0;
+    }
+    if (standaloneCommands[name]) {
+      await standaloneCommands[name].run(context, [subcommand, ...commandArguments].filter((item) => item !== undefined));
+      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')}`);
+    }
+    await command.run(context, commandArguments);
+    return 0;
+  } catch (error) {
+    if (error instanceof UsageError) {
+      err(`사용법 오류: ${error.message}`);
+      return 2;
+    }
+    if (error instanceof ApiError) {
+      err(`오류: ${error.message}`);
+      return error.status === 401 || error.status === 403 ? 3 : 1;
+    }
+    err(`오류: ${error.message}`);
+    return 1;
+  }
+}