calibra CLI

CalibraOps Operating Layer 的独立命令行客户端（#131 S4/S6）。任何 coding agent / 人，加载角色 bundle 后经本 CLI 操作 CalibraOps——薄 HTTP 客户端，治理逻辑在 服务端：

• 写只走 POST /api/apply（受治理内核 Calibra.Cli.apply + 同事务不可变 ChangeRecord）；身份（actor / customer / actor_kind / actor_role）由 服务端从认证 token 派生，CLI 不自证。
• 读走 GET /api/calibra/{query,search,get,changelog}，认证 actor 传 Ash， 租户隔离策略生效。

与 mix calibra（dev / 本地运维，in-process 无认证）相对——本 CLI 是 production 写入路径。

运行

bun install            # 首次
bun run bin/calibra.ts <command>
# 或链接为 calibra：bun link

认证

两种模式，都存 ~/.calibra/credentials.json（0600，多 profile）；token 过期自动刷新。

OAuth Authorization Code + PKCE（人，浏览器交互）——calibra login 默认走此：

calibra login [--profile <name>]

打开浏览器经 Hydra 登录，loopback 127.0.0.1:18988 收回调。

client_credentials（agent / 机器，非交互）——给 --client-id/--client-secret：

calibra login --profile agent --client-id calibra-agent --client-secret <secret>

环境变量：CALIBRA_API_URL（默认 https://api.calibraops.com）、 CALIBRA_AUTH_URL（默认 https://api.calibraops.com/.ory/hydra，也兼容直接传 …/oauth2/auth）、CALIBRA_TOKEN_URL（默认从 auth URL 派生 …/oauth2/token）、CALIBRA_TOKEN（直供 token，跳过 login，CI / 调试用）。

多 profile

每个 --profile <name> 是独立身份（人 / agent / 不同租户）。所有命令支持 --profile，缺省用 current。

calibra profile list          # 列出所有 profile，标 current
calibra profile use <name>    # 切换 current
calibra status [--profile N]  # 某 profile 的身份 / 过期时间
calibra logout [--profile N]

注册 Hydra client（一次性运维）

两个 client 由运维在 Hydra（dev admin 端口 4545）注册一次：

# 人——PKCE public client（无 secret）
hydra create client --endpoint http://localhost:4545 \
  --grant-type authorization_code,refresh_token --response-type code \
  --token-endpoint-auth-method none --scope "openid offline_access" \
  --redirect-uri http://127.0.0.1:18988/callback --id calibra-cli

# agent——client_credentials confidential client
hydra create client --endpoint http://localhost:4545 \
  --grant-type client_credentials --token-endpoint-auth-method client_secret_post \
  --id calibra-agent --secret <secret>

calibra-agent 已在 config :calibra, :machine_principals 白名单里映射到受控 service-principal Member（[email protected]，role compliance_admin）。

命令

calibra login [--profile <name>] [--client-id <id> --client-secret <s>]
              [--login-hint <email>] [--force-login]
calibra logout [--profile <name>]
calibra status [--profile <name>]
calibra profile list | use <name>
calibra context show

calibra query <name> [--<arg> <value> ...]   # 必答查询 / 列表
calibra query tasks-due --date today --agent-role compliance-manager
calibra query task-queue --agent-role compliance-manager
calibra search <text> [--limit <n>]          # 纯 Postgres FTS
calibra get <kind> <id>
calibra changelog <kind> <id>
calibra apply --kind <k> --op <create|update|...> \
  --data '<json>' --rationale '<text>' [--cite a,b] [--target-id <id>]
calibra apply --batch batch.json --rationale "bulk source_chunk backfill"
calibra document update <doc_id> --file path/to/file.md --rationale "replace content"
calibra document reindex <doc_id> --rationale "rebuild chunks"

calibra platform-users list
calibra platform-users create --name "Admin" --email [email protected]

calibra users list
calibra users create --name "Admin" --email [email protected] \
  --role compliance_admin --department Security --job-title "GRC Owner"

calibra people list
calibra people create --name "Auditor" --email [email protected] \
  --role compliance_auditor --department Security --job-title "GRC Analyst"

calibra departments list
calibra departments create --name Security --code SEC --rationale "create org unit"
calibra departments update dep_xxx --manager-id mem_xxx --rationale "assign department manager"

calibra apply --kind task --op create \
  --data '{"title":"Run evidence health check","kind":"compliance_operation","skill_name":"compliance-evidence-health","agent_role":"compliance-manager","input":{"mode":"read_only_first"},"idempotency_key":"evidence-health:2026-W23","owner_id":"mem_xxx"}' \
  --rationale "schedule weekly compliance operation"
calibra apply --kind execution --op create \
  --data '{"task_id":"tsk_xxx","skill_name":"compliance-evidence-health","agent_role":"compliance-manager","status":"running","rationale":"daily compliance operation"}' \
  --rationale "start task execution"
calibra apply --kind task_template --op create \
  --data '{"title":"Weekly evidence health check","kind":"compliance_operation","skill_name":"compliance-evidence-health","agent_role":"compliance-manager","cadence":"weekly","next_run_at":"2026-06-01T01:00:00Z","idempotency_key_template":"evidence-health:{iso_week}","plan_id":"pln_xxx"}' \
  --rationale "create recurring compliance operation"
calibra apply --kind task_template --op generate_due --target-id tpl_xxx \
  --rationale "generate due recurring task"
calibra apply --kind event --op generate_tasks --target-id evt_xxx \
  --rationale "generate event preparation tasks"

成功输出单个 JSON（stdout）；失败 stderr + 退出码 1。

platform-users 走 /api/platform/users，仅 platform_admin 可用；users 走 /api/users，只管理当前租户系统用户；people / 兼容别名 members 走 /api/people， 只管理 Organization → Department → People 的人员目录，不发送登录激活邮件。

calibra login 完成 token exchange 后会调用 /api/me，把当前 member、role、 tenant 与 platform 标记写入 profile；calibra context show 可直接查看该上下文。