bizrouter 0.1.0 → 0.2.0

package/AGENT_MANUAL.md

@@ -0,0 +1,195 @@
+# BizRouter CLI — manual for coding agents
+
+`bizrouter docs` prints this file. It is written for an AI coding agent (Claude
+Code, Codex, OpenCode, Hermes, …) that has the `bizrouter` CLI installed and
+needs to operate a BizRouter account on the user's behalf. The human-facing
+documentation at https://bizrouter.ai/docs is mirrored, from the same source,
+at https://bizrouter.ai/llms-full.txt (`bizrouter docs <topic>` reads it).
+
+## 1. What BizRouter is
+
+BizRouter (https://bizrouter.ai) is an LLM gateway for Korean companies: one
+API key, one bill in KRW, many providers (OpenAI, Anthropic, Google, xAI,
+Perplexity, Upstage, z.AI, domestic serving). Around the gateway sits a console
+where an organization manages API keys, model access, Smart Routing, security
+filters (PII masking, forbidden words, Corepin), audit logs, statistics,
+billing and members. **Everything the console does is an HTTP API**, and this
+CLI can call all of it.
+
+## 2. Two credentials, two purposes
+
+| Credential | Used for | Where it comes from |
+| --- | --- | --- |
+| API key `sk-br-v1-…` | Model calls: `https://api.bizrouter.ai/v1/*`, `/v1/messages`, `/claude/*`. Also what the launched coding agents use. | Issued during `bizrouter login` (browser approval) or pasted with `bizrouter login --with-key`. Env override: `BIZROUTER_API_KEY`. |
+| Console session token | Console management API `https://bizrouter.ai/api/web/*` (`bizrouter api`, `keys`, `usage`, …). 30 days. | Minted when the user approves `bizrouter login` in the browser. Env override: `BIZROUTER_SESSION_TOKEN`. |
+
+Both are stored in `~/.bizrouter/credentials.json` (mode 600;
+`BIZROUTER_CONFIG_DIR` relocates it). `bizrouter auth` shows what is present
+and whether it is still valid. The session carries the **user's role**:
+`owner` can manage the whole organization, `member` sees only their own keys
+and usage.
+
+An API key cannot manage the console. A console session cannot call models.
+If a management command fails with "콘솔 세션이 없습니다", ask the user to run
+`bizrouter login` (it opens a browser; the user approves an 8-character code).
+You cannot complete that approval yourself — it is deliberately a human step.
+
+## 3. Command cheat sheet
+
+```
+bizrouter login [--with-key] [--no-browser]   sign in (browser approval; --with-key pastes an API key)
+bizrouter auth                                 which credentials exist and whether they work
+bizrouter logout                               revoke the console session, delete local credentials
+bizrouter doctor                               connectivity, key, session, installed agents, conflicts
+bizrouter models [query] [--json]              models this key may use, KRW prices per 1M tokens
+
+bizrouter claude|codex|opencode|hermes [--model ID] [--reasoning-effort L] [--no-mcp] [tool args…]
+                                               run a coding agent through BizRouter (config files untouched)
+
+bizrouter api --list [keyword]                 every console API operation (from the live OpenAPI)
+bizrouter api --schema [METHOD] <path>         request/response fields of one operation
+bizrouter api [METHOD] <path> [-q k=v]… [-d JSON|@file] [--yes]
+                                               call any console API; JSON on stdout
+
+bizrouter keys list|create|update|delete       API keys (name, limits, allowed models/IPs)
+bizrouter usage [--from D --to D] [--by key|model|user]   spend and tokens (statistics)
+bizrouter billing                               credits, monthly bills
+bizrouter org show|members|settings [k=v…]     organization, members, org-level toggles
+bizrouter audit list|show <id>|stats           request audit logs
+bizrouter routing policy|presets|profiles|logs Smart Routing
+bizrouter security show|access                 content filters, console access (MFA, IP allowlist)
+
+bizrouter docs [topic|--list|--full]           this manual; developer docs from llms-full.txt
+bizrouter mcp                                  run as an MCP server (stdio) exposing the above as tools
+```
+
+All management commands accept `--json` and print exactly the server's JSON,
+so you can pipe into `jq`. Without `--json` they print a compact table.
+Exit code 0 = success, 1 = error (message on stderr; for `api`, the server's
+structured error is also printed on stdout as `{"status":…,"error":…}`).
+
+## 4. Rules of engagement (read before mutating anything)
+
+1. **Reads are free; writes need the user's OK.** Listing keys, usage,
+   policies and logs is fine. Creating, updating or deleting anything (keys,
+   policies, security settings, members, credits) must be confirmed with the
+   user first — quote what you are about to change. `bizrouter api` enforces
+   this: `POST/PUT/PATCH/DELETE` prompt for confirmation in a terminal and
+   refuse without `--yes` in a pipe. Add `--yes` only after the user agreed.
+2. **Never print a full API key into a file, log, commit or chat reply.**
+   `keys create` returns `full_key` once; hand it to the place it belongs
+   (env var, secret store) and show the user only the masked preview.
+3. **Do not touch money without an explicit request**: `/payments/*`,
+   `/organizations/credits` (PATCH), auto-charge settings, referral payouts.
+4. **Console access controls can lock people out.** Enabling the IP
+   allowlist (`/security/console-access`) or MFA requirement affects every
+   member's sign-in. The server refuses changes that would lock out the
+   caller, but not changes that lock out others. Confirm the exact list of
+   CIDRs with the user.
+5. **Audit log on/off is an organization setting**: `skip_audit_log=true`
+   stops storing prompts/responses for new requests (billing rows remain).
+   Turning it on again does not recover skipped content. Say so.
+6. **Members** can only see and manage their own API keys; commands that
+   need `owner` return 403 — report it, do not retry with tricks.
+7. Prefer the wrapped commands (`keys`, `usage`, …) for common tasks; use
+   `bizrouter api` for everything else. Look the operation up with
+   `--list`/`--schema` before guessing a field name.
+
+## 5. Console API map (paths are relative to https://bizrouter.ai/api/web)
+
+| Area | Paths | Notes |
+| --- | --- | --- |
+| Account, sessions | `GET /auth/profile` · `GET /auth/sessions` · `DELETE /auth/sessions/{id}` · `GET/POST /auth/mfa…` | who am I; devices logged in |
+| API keys | `GET/POST /api-keys` · `PATCH/DELETE /api-keys/{key_id}` | body: `name`, `is_active`, `credit_limit` (KRW), `credit_limit_period` lifetime/daily/monthly, `limit_alert_enabled`, `limit_alert_threshold` (%), `limit_alert_recipient_emails[]`, `allowed_ips[]` (CIDR), `allowed_model_codes[]` (empty = all) |
+| Usage API keys | `/usage-api-keys` | keys for the read-only Usage API (`https://api.bizrouter.ai/usage/v1/*`) |
+| Models | `GET /models` · `GET/POST/DELETE /model-blacklist…` | catalog; org-wide model blocklist |
+| Organization | `GET /organizations/{id}` · `GET/PATCH /organizations/settings` · `GET /organizations/{id}/users` · `PATCH/DELETE /organizations/{id}/users/{user_id}` · `POST /organizations/invitations` | settings: `skip_audit_log`, `block_file_upload`, Claude Code model mappings (`claude_code_*_model_id`) |
+| Billing | `GET /organizations/credits` · `GET /organizations/billing/monthly?months=N` · `GET /organizations/billing/evidence…` · `/payments/*` | read freely; never change without being asked |
+| Statistics | `GET /statistics/?start_date&end_date&models&api_keys&users&limit&offset` · `GET /statistics/filter-options` · `GET /statistics/charts/spend|tokens|requests|api-key-model-distribution|api-key-daily-trend` · `…/export` | dates `YYYY-MM-DD`; comma-separated filters |
+| Audit logs | `GET /audit-logs/?api_key&model&status&start_date&end_date&search&cursor&limit` · `GET /audit-logs/{log_id}` · `GET /audit-logs/stats/summary` · `POST /audit-logs/exports` | request-level records incl. prompts unless `skip_audit_log` |
+| Smart Routing | `GET/PATCH /smart-routing/policy` · `POST /smart-routing/policy/presets` · `GET /smart-routing/policy/diagnostics` · `GET/POST /smart-routing/profiles` · `GET/PATCH/DELETE /smart-routing/profiles/{id}` · `GET /smart-routing/pool-models` · `GET /smart-routing/logs` · `/smart-routing/taxonomy-rules…` · `/smart-routing/review-candidates…` | the virtual model `bizrouter/route` follows the default policy |
+| Security | `GET/PATCH /security` · `GET/POST/DELETE /security/forbidden-words…` · `GET /security/corepin/catalog` · `GET/PATCH /security/console-access` · `POST/DELETE /security/console-access/allowed-ips…` | PII masking, forbidden words, Corepin; MFA/IP policy |
+| BYOK | `GET /byok/` · `PUT/DELETE /byok/{provider_name}` · `POST /byok/test` | customer's own provider keys |
+| Evals | `/evals/*` | datasets, rubrics, runs (owner-enabled feature) |
+| Release notes | `GET /release-notes` | what changed in the product |
+
+`bizrouter api --list` is authoritative — the table above is a map, not the
+contract. `bizrouter api --schema PATCH /organizations/settings` shows the
+exact fields.
+
+## 6. Worked examples
+
+Create a key for a project, limited to two models and ₩300,000 a month:
+
+```
+bizrouter api --schema POST /api-keys
+bizrouter keys create "growth-bot" --limit 300000 --period monthly \
+  --models openai/gpt-5.6-sol,anthropic/claude-sonnet-5 --json
+# → full_key appears once. Put it where it belongs; show the user key_preview only.
+```
+
+This month's spend by API key, then by model:
+
+```
+bizrouter usage --from 2026-09-01 --to 2026-09-30 --by key
+bizrouter usage --from 2026-09-01 --to 2026-09-30 --by model --json | jq '.items[] | {model, cost}'
+```
+
+Turn audit logging off for the organization (after the user confirmed):
+
+```
+bizrouter org settings skip_audit_log=true --yes
+```
+
+Why did requests fail this morning?
+
+```
+bizrouter audit list --status error --from 2026-09-06 --limit 20
+bizrouter audit show <log_id>
+```
+
+Recommend and apply a Smart Routing preset:
+
+```
+bizrouter routing presets            # server suggests presets for the org's traffic
+bizrouter routing policy             # current default policy
+bizrouter api PATCH /smart-routing/policy -d '{"strategy":"cost_optimized"}' --yes
+```
+
+Anything not wrapped:
+
+```
+bizrouter api --list byok
+bizrouter api PUT /byok/openai -d '{"api_key":"sk-…"}' --yes
+```
+
+## 7. Running coding agents
+
+`bizrouter claude|codex|opencode|hermes` launches the tool with BizRouter
+injected for that process only (env + the tool's own override mechanism); the
+user's config files are not modified. `--model <id>` picks a BizRouter model
+(`bizrouter models` lists them), `--reasoning-effort` maps to the tool's
+setting, everything after our flags is passed through untouched.
+
+When a console session exists, the launcher also registers this CLI as an MCP
+server named `bizrouter` inside Claude Code, Codex and OpenCode for that run
+(`--no-mcp` disables it). The agent then has tools `bizrouter_api`,
+`bizrouter_openapi`, `bizrouter_docs`, `bizrouter_models` and `bizrouter_whoami`
+with the same rules as above — `bizrouter_api` refuses mutating calls unless
+`confirm: true` is passed after the user agreed.
+
+Claude Code can only run Anthropic models (it always sends Anthropic-only
+fields); use Codex/OpenCode/Hermes for GPT or Gemini.
+
+## 8. Troubleshooting
+
+- `콘솔 세션이 없습니다` / 401 → `bizrouter login` (human step).
+- 403 with a message about IP → the organization's console IP allowlist blocks
+  this machine; the user must add the address in the console or from an
+  allowed network.
+- 403 on management calls → the account is a `member`; needs an `owner`.
+- Model calls return 400 `model not found` → the key's allowed-model list or
+  the organization's model policy excludes it (`bizrouter models` shows what the
+  key may use).
+- Hermes + model with output cap under 65536 → pick another model
+  (`bizrouter hermes --model anthropic/claude-sonnet-5`).

package/README.md

@@ -1,10 +1,10 @@
 # bizrouter CLI
 
-쓰던 코딩 에이전트를 그대로 두고, 명령 앞에 `bizrouter` 만 붙이면 BizRouter 로 연결됩니다.
+쓰던 코딩 에이전트를 그대로 두고 명령 앞에 `bizrouter` 만 붙이면 BizRouter 로 연결됩니다. 로그인한 뒤에는 BizRouter 콘솔(API 키·정책·감사 로그·통계)도 명령으로, 또는 에이전트의 MCP 도구로 다룰 수 있습니다.
 
 ```bash
 npm install -g bizrouter        # 또는: curl -fsSL https://bizrouter.ai/install.sh | bash
-bizrouter login                 # 브라우저에서 API 키를 발급받아 붙여 넣습니다 (한 번만)
+bizrouter login                 # 브라우저에서 코드를 확인하고 승인합니다 (한 번만)
 bizrouter claude                # Claude Code
 bizrouter codex                 # Codex CLI
 bizrouter opencode              # OpenCode
@@ -13,11 +13,20 @@ bizrouter hermes                # Hermes
 
 설치 없이 바로 써 볼 수도 있습니다: `npx bizrouter claude`
 
-## 무엇을 해 주나
+## 로그인이 해 주는 것
+
+`bizrouter login` 은 터미널에 8자리 코드를 보여주고 브라우저에서 BizRouter 콘솔을 엽니다. 콘솔에 로그인(비밀번호·Google·웍스AI·2차 인증 그대로)한 뒤 코드를 확인하고 「승인」하면
+
+- 이 기기용 **콘솔 세션**(30일)과
+- 이 기기 이름의 **API 키**(모델 호출용)가 함께 발급되어 `~/.bizrouter/credentials.json` 에 권한 600 으로 저장됩니다.
+
+키만 붙여 넣던 방식도 그대로 됩니다: `bizrouter login --with-key`. CI·컨테이너에서는 `BIZROUTER_API_KEY`(모델 호출)·`BIZROUTER_SESSION_TOKEN`(콘솔) 환경 변수가 저장된 값보다 우선합니다. 세션은 콘솔 「계정 → 로그인된 기기」에서 언제든 종료할 수 있습니다.
+
+## 코딩 에이전트 실행
 
 | 도구 | 실행 시 하는 일 | 설정 파일 변경 |
 | --- | --- | --- |
-| Claude Code | `ANTHROPIC_BASE_URL=https://api.bizrouter.ai/claude`, 토큰, 빈 `ANTHROPIC_API_KEY`, 모델 선택창 자동 채움(`CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY`)을 넘기고, 사용자 settings.json 의 다른 게이트웨이 설정이 이기지 못하도록 명령행 settings 로 고정 | 없음 |
+| Claude Code | `ANTHROPIC_BASE_URL=https://api.bizrouter.ai/claude`, 토큰, 빈 `ANTHROPIC_API_KEY`, 모델 선택창 자동 채움을 넘기고, 사용자 settings.json 의 다른 게이트웨이 설정이 이기지 못하도록 명령행 settings 로 고정 | 없음 |
 | Codex CLI | `-c` 오버라이드로 BizRouter provider(Responses API)와 모델·추론 강도 지정 | 없음 |
 | OpenCode | `OPENCODE_CONFIG_CONTENT` 로 이 키가 쓸 수 있는 모델 전체가 담긴 `bizrouter` provider 를 주입 | 없음 |
 | Hermes | `custom` provider(`CUSTOM_BASE_URL`/`CUSTOM_API_KEY`)와 모델을 이번 실행에만 지정 | 없음 |
@@ -31,20 +40,44 @@ bizrouter opencode --model google/gemini-3.5-pro
 bizrouter claude --dry-run          # 실행 대신 넘겨줄 환경 변수와 명령을 보여줍니다
 ```
 
-## 관리 명령
+콘솔 세션이 있으면 Claude Code·Codex·OpenCode 에 이 CLI 가 **MCP 서버 `bizrouter`** 로 함께 연결됩니다. 에이전트는 `bizrouter_api`(콘솔 API 호출)·`bizrouter_openapi`(API 탐색)·`bizrouter_docs`(문서)·`bizrouter_models`·`bizrouter_whoami` 도구로 API 키를 만들고, 정책을 바꾸고, 사용량을 읽습니다. 데이터를 바꾸는 호출은 사용자 확인 뒤 `confirm: true` 를 받아야만 실행됩니다. `--no-mcp` 로 끕니다.
+
+## 콘솔 관리 명령
+
+모두 `--json` 을 지원하고, 데이터를 바꾸는 명령은 터미널에서 확인을 묻거나 `--yes` 를 요구합니다.
+
+```bash
+bizrouter api --list [검색어]                      # 콘솔 API 전체 목록 (라이브 OpenAPI 기준)
+bizrouter api --schema PATCH /organizations/settings   # 필드 확인
+bizrouter api /statistics/ -q start_date=2026-09-01    # 아무 콘솔 API 호출
+bizrouter api POST /api-keys -d '{"name":"ci"}' --yes
+
+bizrouter keys list|create|update|delete           # API 키 (한도·기간·허용 모델·허용 IP)
+bizrouter usage [--from --to] [--by model|key|day] # 사용 금액·요청 수
+bizrouter billing                                  # 크레딧·월별 청구
+bizrouter org show|members|settings [k=v]          # 조직·구성원·감사 로그 저장 등 조직 설정
+bizrouter audit list|show <id>|stats               # 요청 감사 로그
+bizrouter routing policy|presets|profiles|logs     # 스마트 라우팅
+bizrouter security show|set|access                 # 보안 필터·콘솔 접근 통제
+bizrouter docs [주제]                              # 에이전트 매뉴얼(AGENT_MANUAL.md)·개발 문서
+bizrouter mcp                                      # MCP 서버(stdio)로 직접 실행
+```
+
+에이전트에게 맡길 때는 `bizrouter docs` 가 출력하는 매뉴얼을 먼저 읽히면 됩니다. 사람용 개발 문서(https://bizrouter.ai/docs)는 같은 소스에서 만든 https://bizrouter.ai/llms-full.txt 로도 제공됩니다.
+
+## 그 밖의 명령
 
 ```bash
 bizrouter models [검색어]        # 이 키로 쓸 수 있는 모델·컨텍스트·원화 단가
-bizrouter doctor                 # 키·연결·설치·충돌 점검
+bizrouter doctor                 # 키·세션·연결·설치·충돌 점검
 bizrouter setup claude|codex|opencode   # 도구 설정 파일에 BizRouter 를 영구 등록 (백업 생성)
 bizrouter auth / logout / env / update
 ```
 
-`BIZROUTER_API_KEY` 환경 변수가 있으면 저장된 키보다 우선합니다(CI·컨테이너). 설정은 `~/.bizrouter/`(`BIZROUTER_CONFIG_DIR` 로 변경) 에 권한 600 으로 저장됩니다.
-
 ## 알아둘 것
 
-- Claude Code 는 Anthropic 전용 필드(`thinking`, `cache_control`)를 항상 보내므로 Claude 모델만 실행할 수 있습니다. GPT·Gemini 는 Codex·OpenCode·Hermes 로 실행하세요.
+- Claude Code 는 Anthropic 전용 필드(`thinking`, `cache_control`)를 항상 보내므로 Claude 모델만 실행할 수 있습니다. GPT·Gemini 는 Codex·OpenCode·Hermes 로 실행하십시오.
+- 콘솔 세션은 로그인한 사용자의 권한(owner/member)을 그대로 따릅니다. 구성원(member)은 자기 API 키와 사용량만 다룰 수 있습니다.
 - 요구 사항: Node.js 18 이상. 각 코딩 에이전트는 따로 설치돼 있어야 합니다.
 
 문서: https://bizrouter.ai/docs/cli

package/dist/args.js

@@ -7,7 +7,7 @@ export class ArgError extends Error {
  * the harness untouched, so `bizrouter claude -p "hi"` still works.
  */
 export function parseLaunchArgs(argv) {
-    const out = { closedNetwork: false, dryRun: false, help: false, passthrough: [] };
+    const out = { closedNetwork: false, dryRun: false, help: false, noMcp: false, passthrough: [] };
     let i = 0;
     const takeValue = (flag) => {
         const value = argv[i + 1];
@@ -47,6 +47,10 @@ export function parseLaunchArgs(argv) {
                 out.dryRun = true;
                 i += 1;
                 continue;
+            case '--no-mcp':
+                out.noMcp = true;
+                i += 1;
+                continue;
             case '--help':
             case '-h':
                 out.help = true;

package/dist/commands/api.js

@@ -0,0 +1,152 @@
+import { readFileSync } from 'node:fs';
+import { ConsoleApiError, HTTP_METHODS, MUTATING_METHODS, consoleRequest, fetchOpenApi, findOperation, listOperations, normalizeConsolePath } from '../console.js';
+import { readLine } from '../prompt.js';
+import { c, CliError, info, padEnd, print, warn } from '../ui.js';
+const USAGE = [
+    'bizrouter api --list [검색어]                         콘솔 API 경로 목록',
+    'bizrouter api --schema [METHOD] <경로>                 요청·응답 필드',
+    'bizrouter api [METHOD] <경로> [-q k=v]… [-d JSON|@파일] [--yes]',
+].join('\n');
+function parseData(raw) {
+    const text = raw.startsWith('@') ? readFileSync(raw.slice(1) === '-' ? 0 : raw.slice(1), 'utf8') : raw;
+    try {
+        return JSON.parse(text);
+    }
+    catch (error) {
+        throw new CliError(`-d 값이 JSON 이 아닙니다: ${error instanceof Error ? error.message : String(error)}`, {
+            hint: `예: -d '{"name":"ci-key"}'  또는  -d @body.json  (표준 입력은 -d @-)`,
+        });
+    }
+}
+export function parseApiArgs(argv) {
+    const flags = { query: {}, yes: false, refresh: false, raw: false };
+    const positional = [];
+    for (let i = 0; i < argv.length; i += 1) {
+        const token = argv[i];
+        const next = () => {
+            const value = argv[i + 1];
+            if (value === undefined)
+                throw new CliError(`${token} 뒤에 값이 필요합니다.`, { hint: USAGE });
+            i += 1;
+            return value;
+        };
+        if (token === '--list' || token === '-l') {
+            flags.list = argv[i + 1] && !argv[i + 1].startsWith('-') ? (i += 1, argv[i]) : true;
+        }
+        else if (token.startsWith('--list='))
+            flags.list = token.slice(7) || true;
+        else if (token === '--schema' || token === '-s')
+            flags.schema = '';
+        else if (token === '-d' || token === '--data')
+            flags.data = parseData(next());
+        else if (token.startsWith('--data='))
+            flags.data = parseData(token.slice(7));
+        else if (token === '-q' || token === '--query') {
+            const pair = next();
+            const eq = pair.indexOf('=');
+            if (eq <= 0)
+                throw new CliError(`-q 값은 key=value 형식이어야 합니다: ${pair}`);
+            flags.query[pair.slice(0, eq)] = pair.slice(eq + 1);
+        }
+        else if (token === '--yes' || token === '-y')
+            flags.yes = true;
+        else if (token === '--refresh')
+            flags.refresh = true;
+        else if (token === '--raw')
+            flags.raw = true;
+        else if (token === '-h' || token === '--help')
+            flags.list = flags.list ?? true;
+        else if (token.startsWith('-') && !/^-\d/.test(token))
+            throw new CliError(`알 수 없는 옵션입니다: ${token}`, { hint: USAGE });
+        else
+            positional.push(token);
+    }
+    // `api GET /x`, `api /x` (GET), `api POST /x`
+    const first = positional[0]?.toUpperCase();
+    if (first && HTTP_METHODS.includes(first)) {
+        flags.method = first;
+        flags.path = positional[1];
+    }
+    else if (positional[0]) {
+        flags.path = positional[0];
+    }
+    if (flags.schema === '')
+        flags.schema = flags.path ?? '';
+    if (!flags.method && flags.path)
+        flags.method = flags.data !== undefined ? 'POST' : 'GET';
+    return flags;
+}
+function printOperations(rows, keyword) {
+    if (!rows.length) {
+        print(keyword ? `「${keyword}」에 맞는 콘솔 API 가 없습니다.` : '콘솔 API 목록이 비어 있습니다.');
+        return;
+    }
+    const pathWidth = Math.min(56, Math.max(...rows.map((r) => r.path.length), 10));
+    print(c.dim(`${padEnd('METHOD', 7)} ${padEnd('경로 (/api/web 기준)', pathWidth)}  설명 · 질의 인자(*=필수)`));
+    for (const r of rows) {
+        const method = MUTATING_METHODS.has(r.method) ? c.yellow(padEnd(r.method, 7)) : c.green(padEnd(r.method, 7));
+        const extras = [r.params.length ? `?${r.params.join('&')}` : '', r.hasBody ? c.dim('[본문]') : ''].filter(Boolean).join(' ');
+        print(`${method} ${padEnd(r.path, pathWidth)}  ${r.summary}${extras ? ` ${c.dim(extras)}` : ''}`);
+    }
+    print();
+    print(c.dim(`${rows.length}개 · 자세한 필드: bizrouter api --schema <METHOD> <경로> · 호출: bizrouter api <METHOD> <경로> [-q k=v] [-d JSON]`));
+}
+export async function apiCommand(argv) {
+    const flags = parseApiArgs(argv);
+    if (flags.list !== undefined && !flags.path) {
+        const spec = await fetchOpenApi({ force: flags.refresh });
+        const keyword = flags.list === true ? undefined : flags.list;
+        printOperations(listOperations(spec, keyword), keyword);
+        return 0;
+    }
+    if (flags.schema !== undefined) {
+        if (!flags.schema)
+            throw new CliError('--schema 뒤에 경로가 필요합니다.', { hint: USAGE });
+        const spec = await fetchOpenApi({ force: flags.refresh });
+        const method = flags.method && argv.some((a) => a.toUpperCase() === flags.method) ? flags.method : undefined;
+        const matches = findOperation(spec, method, flags.schema);
+        if (!matches.length)
+            throw new CliError(`콘솔 API 에 없는 경로입니다: ${normalizeConsolePath(flags.schema)}`, { hint: '`bizrouter api --list <검색어>` 로 찾아보십시오.' });
+        print(JSON.stringify(matches.length === 1 ? matches[0] : matches, null, 2));
+        return 0;
+    }
+    if (!flags.path || !flags.method) {
+        print(USAGE);
+        print();
+        print(c.dim('예: bizrouter api /api-keys · bizrouter api /statistics/ -q start_date=2026-09-01 · bizrouter api POST /api-keys -d \'{"name":"ci"}\''));
+        return 0;
+    }
+    const path = normalizeConsolePath(flags.path);
+    if (MUTATING_METHODS.has(flags.method) && !flags.yes) {
+        if (!process.stdin.isTTY) {
+            throw new CliError(`${flags.method} ${path} 는 데이터를 바꾸는 요청입니다. 확인 없이 실행하려면 --yes 를 붙이십시오.`, {
+                hint: '에이전트가 실행하는 경우, 사람에게 먼저 확인을 받은 뒤 --yes 를 붙여 다시 실행하십시오.',
+            });
+        }
+        warn(`${flags.method} ${path} 는 데이터를 바꾸는 요청입니다.`);
+        if (flags.data !== undefined)
+            print(c.dim(JSON.stringify(flags.data, null, 2)));
+        const answer = await readLine('실행할까요? (y/N) ');
+        if (!/^y(es)?$/i.test(answer)) {
+            info('취소했습니다.');
+            return 1;
+        }
+    }
+    try {
+        const { status, data } = await consoleRequest(flags.method, path, { query: flags.query, body: flags.data });
+        if (data === undefined)
+            print(JSON.stringify({ status }));
+        else if (typeof data === 'string')
+            print(flags.raw ? data : JSON.stringify({ status, body: data }));
+        else
+            print(JSON.stringify(data, null, 2));
+        return 0;
+    }
+    catch (error) {
+        if (error instanceof ConsoleApiError && error.body !== undefined && typeof error.body === 'object') {
+            // Keep the server's structured error on stdout too so agents can parse it.
+            print(JSON.stringify({ status: error.status, error: error.body }, null, 2));
+        }
+        throw error;
+    }
+}