@krab-jw/perm-cli

权限平台接入一条链工具（Node 零依赖单文件版）。下游无需安装 Node 依赖，npx 随用随跑。

使用

npx @krab-jw/perm-cli <command> [options]

| 命令 | 说明 | 必填参数 | | --- | --- | --- | | login | 保存凭据到本地配置（推荐 --browser 浏览器 SSO 一键登录；或 --admin-token X-Dev-Auth / --session-token 既有会话 / --username 账号登录换会话） | — | | logout | 清除本地配置 | — | | doctor | 环境体检：Node/env/网络/签名链路 | — | | create-app | 自助创建接入应用 | --code --name | | app-status | 查我的应用审批状态 | [--id] | | credentials | 查看应用 ak/sk | --id | | self-check | HMAC 签名自检 | — | | grant | 编程化授权 | --email --role-code | | snippet | 生成接入代码片段 | --lang curl\|python\|java\|oidc | | register | 批量注册权限资源（默认预检） | --bl-id --file [--apply --yes] | | export-codes | 导出业务线权限配置 | --bl-id [--out] | | role-create | 创建角色 | --bl-id --code --name [--bind-codes] | | role-bind | 给角色绑定权限（替换全部） | --bl-id --role-code [--codes\|--all] | | role-list | 查询角色列表 | --bl-id [--keyword] | | datascope | 数据范围 v2 工具族（契约见 perm/docs/data-scope-v2-design.md）：example/validate/evaluate/sql | --file --row/--map [--dims] | | skill-pack | 把 SKILL.md + SKILL-DATA-SCOPE.md + llms*.txt 打成 zip（含各 agent 放置说明） | [--out --force] |

环境变量：PERM_API_BASE / PERM_SESSION_TOKEN / PERM_ADMIN_TOKEN / PERM_APP_ID / PERM_APP_SECRET / PERM_GATEWAY_SYSID / PERM_GATEWAY_SECRET（另有浏览器登录用的 PERM_BROWSER_PATH / PERM_LOGIN_URL）。

管理端凭据优先级：PERM_SESSION_TOKEN（Bearer 会话，业务线管理员自助，受 managedBusinessLineIds 约束）> PERM_ADMIN_TOKEN（X-Dev-Auth，测试环境超管后门）> login 本地配置。管理命令按此自适应上报 Authorization: Bearer 或 X-Dev-Auth 头。

数据范围 v2（datascope）

下游做行级数据过滤时用。语义：命中任一 Allow 组 且 不命中任何 Deny 组 = 可见；不认识的 scopeType/维度一律 fail-closed。详见 SKILL-DATA-SCOPE.md。

npx @krab-jw/perm-cli datascope example --type partner > scope.json
npx @krab-jw/perm-cli datascope validate --file scope.json
npx @krab-jw/perm-cli datascope evaluate --file scope.json --row '{"COUNTRY":"ID","CONTRACT_TYPE":"ISP_ELITE"}' --dims COUNTRY,CONTRACT_TYPE,CHANNEL
npx @krab-jw/perm-cli datascope sql --file scope.json --map COUNTRY=country_code,CONTRACT_TYPE=contract_type,CHANNEL=channel_code

登录方式

方式一：浏览器 SSO 一键登录（推荐，零复制零手填）——CLI 自动打开浏览器，你在页面完成 SSO 登录，CLI 自动抓登录态保存：

npx @krab-jw/perm-cli login --browser

• 自动打开测试环境中台登录页（默认 https://bop-test.ruijie.com/perm-center/_，--login-url 可覆盖），登录完成后 CLI 自动检测 localStorage 会话 token 并保存到 ~/.perm-cli/config.json。
• API 地址与网关签名凭据（sysId/secret）从中台页面 _env_ 自动抓取，无需任何手填参数。
• 保存前自动调 auth/me 校验 token，浏览器显示「登录成功」后自动关闭。
• 要求 Node >= 22（内置 WebSocket）与本机 Chrome/Edge（可用 PERM_BROWSER_PATH 指定浏览器）。
• 交互模式直接 perm-cli login 回车即走此方式。SSO 会话保留在 CLI 专属浏览器 profile（~/.perm-cli/browser-profile），下次登录通常免输密码。
• 注意：本地 dev 页面（X-Dev-Auth 模式）不落 localStorage token，浏览器登录适用测试/生产环境页面。

方式二：账密登录（本地/直连中台）——账号支持工号或邮箱（后端 login 匹配 account 或 email）：

npx @krab-jw/perm-cli login --api-base http://localhost:8080/intern-perm-center \
  --username [email protected]        # 回车后输入密码

方式三：SSO 登录态手动复用（浏览器自动登录不可用时的兜底）——浏览器 SSO 登录后把会话 token 交给 CLI：

1. 浏览器打开 https://bop-test.ruijie.com/perm-center/ 完成 SSO 登录
2. F12 → Console → 输入 localStorage.getItem('token') → 复制返回值
3. 一条命令保存登录态（api-base、token、网关凭据全进本地配置，之后零参数）：

npx @krab-jw/perm-cli login \
  --api-base https://web-e-test-gw.ruijie.com.cn/api/intern-perm-center \
  --session-token <粘贴token> \
  --gateway-sysid <网关sysId> --gateway-secret <网关secret>

网关 sysId/secret 在中台前端页面 _env_ 中公开注入（DevTools Network 可见）。会话有效期 2 小时，过期后命令报 HTTP 401 并提示重新登录；重取 token 后再跑一次 login 即可。网关签名走 web 侧约定（sysId + web-sign-server-auth，毫秒时间戳）。

全局选项 --json：stdout 只出稳定信封 {"ok","command","data"|"error"}，人类消息走 stderr，退出码 0/1/2 不变。

register --apply（replace 全量覆盖）会先拉现网配置打印 diff 摘要（+N 新增 / -N 删除 / =N 保留），TTY 需输入 y 确认；CI 非交互环境必须显式 --yes（会打 WARN 留痕）。

发布

1. 版本号走 SemVer：bugfix → patch，新命令/新选项 → minor，breaking → major。
2. 发布公网 npmjs（publishConfig 已配 registry + access: public；账号需开 2FA，用恢复码作 --otp）：

cd perm/perm-cli/node
npm publish --access public --otp=<恢复码>

3. 公司内网 registry（@ruijie/perm-cli）补发：先临时改 package.json 的 name，再 npm publish --registry https://registry.ruijie.com.cn。
4. 下游使用锁定主版本：npx @krab-jw/perm-cli@^0 <cmd>。注意 npx 缓存可能拉旧版，必要时指定具体版本号。

本包零运行时依赖，engines 要求 Node >= 18.17（原生 fetch / node:test）；login --browser 浏览器登录需 Node >= 22（内置 WebSocket）。