GenAuth CLI

genauth-cli 是 GenAuth 的命令行工具。它面向开发者，也面向 agent 和 CI 流程，用来管理用户池、应用、OIDC scope，并快速生成接入 OIDC 所需的配置。

CLI 的设计目标是让接入方不必手动在控制台完成所有配置。开发者可以通过交互式命令完成初始化，agent 可以通过 --json 和 --no-input 以稳定、可解析的方式完成同样的操作。

Requirements

• Node.js >= 20
• pnpm
• 可访问的 Genauth 服务地址，默认是 https://console.genauth.ai
• 管理凭据：AccessKey ID/Secret，或支持 CLI browser login 的服务端环境

在本地开发环境中进入 CLI 项目：

cd ../genauth-cli
pnpm install
pnpm build

本地开发时可以直接运行：

pnpm dev -- --help

构建后可以使用：

node dist/index.js --help

Login

CLI 支持两种登录方式。

AccessKey 登录

AccessKey 登录适合脚本、CI 和 agent。它会调用 Genauth 管理 Token 接口，并把当前 server、userpool 和 access token 保存到本地 profile。

genauth login \
  --access-key-id <userpool-id> \
  --access-key-secret <access-key-secret>

Browser 登录

Browser 登录适合开发者在本机交互使用。

genauth login --browser

执行后，CLI 会打开浏览器完成授权，并把登录结果保存到当前 profile。

Profiles and environment

CLI 使用 profile 保存不同环境的 server、当前用户池和 token。

genauth config set server https://console.genauth.ai
genauth config get

为不同环境设置独立 profile：

genauth config set server http://localhost:3000 --profile dev
genauth login --profile dev --browser
genauth userpools use <userpool-id> --profile dev

常用环境变量：

export GENAUTH_SERVER=http://localhost:3000
export GENAUTH_USERPOOL_ID=<userpool-id>

命令行参数优先级高于环境变量，环境变量优先级高于 profile。

User pools

用户池是 GenAuth 资源隔离的主要边界。应用和 OIDC scope 都需要在某个用户池下管理。

genauth userpools list
genauth userpools get <userpool-id>
genauth userpools create --name Demo --domain demo
genauth userpools use <userpool-id>

设置当前用户池后，后续应用和 scope 命令会默认使用它。

Applications

应用命令用于创建和管理 OIDC 应用。

genauth apps list
genauth apps get <app-id>

创建 Web OIDC 应用：

genauth apps create \
  --name Demo \
  --identifier demo \
  --type web \
  --callback http://localhost:3000/callback \
  --logout-callback http://localhost:3000/logout

更新回调地址：

genauth apps update <app-id> \
  --callback http://localhost:3000/callback

查看或轮换应用密钥：

genauth apps secret <app-id>
genauth apps rotate-secret <app-id> --yes

删除应用需要显式确认：

genauth apps delete <app-id> --yes

OIDC setup

oidc setup 是推荐的快速接入命令。它会创建 OIDC 应用、配置回调地址、按需创建自定义 scope，并输出接入参数。

genauth oidc setup \
  --app-name Demo \
  --identifier demo \
  --callback http://localhost:3000/callback \
  --logout-callback http://localhost:3000/logout

输出中包含：

• issuer
• authorization_endpoint
• token_endpoint
• userinfo_endpoint
• jwks_uri
• client_id
• client_secret
• redirect_uris

Authorization server scopes

auth-servers scopes 用于管理 OIDC 应用可请求的自定义 scope 和对应 claims。通过这些 scope，可以把业务 API 的访问边界表达为 OIDC 授权请求中的权限声明。

genauth auth-servers scopes list --app <app-id>

创建自定义 scope：

genauth auth-servers scopes create \
  --app <app-id> \
  --name orders:read \
  --claim orders

更新或删除 scope：

genauth auth-servers scopes update <scope-id> --app <app-id> --name orders:write
genauth auth-servers scopes delete <scope-id> --app <app-id> --yes

Agent and CI usage

Agent 和 CI 应使用非交互式参数，并开启 JSON 输出。

genauth oidc setup \
  --userpool "$GENAUTH_USERPOOL_ID" \
  --app-name Demo \
  --identifier demo \
  --callback http://localhost:3000/callback \
  --scope orders:read \
  --claim orders \
  --json \
  --no-input

推荐约定：

• 使用 --json 获取稳定 JSON 输出。
• 使用 --no-input 禁止 prompt，缺少必要参数时直接失败。
• 使用 genauth config set server <url> 固化 server，避免每次命令重复传 --server。
• 使用 --profile 隔离 dev、staging、prod。
• 对删除、密钥轮换等破坏性操作始终显式传 --yes。

Output

默认输出面向人类阅读，资源列表会使用表格。加上 --json 后，CLI 输出稳定 JSON，适合 agent 解析。

genauth apps list --json

错误会输出简洁错误信息。需要调试接口响应时，可以设置：

DEBUG=1 genauth apps list --json

Next step

阅读 GenAuth 了解 GenAuth 的身份与授权边界，再使用 genauth oidc setup 完成第一个 OIDC 应用接入。