鉴权与登录

auth 命令组用于 SSO 鉴权：通过浏览器登录并存储短时 STS 凭据或仅保存用户 OIDC 会话、清除会话、查看当前身份、管理登录配置，以及为组织准备 CLI SSO 登录资源。login、logout、whoami 同时提供为顶层命令（如 agentkit login）。通过浏览器 SSO 完成鉴权。默认模式会使用 OIDC 登录结果换取短时 STS 凭据；--identity-only 只保存用户 OIDC 会话，可供 harness invoke 在匹配的 custom_jwt Runtime 上自动转发用户 id_token，但不创建 AgentKit 管理凭据。通用 invoke run 调用 custom_jwt Runtime 时仍需通过 --headers 显式传入 Authorization。

标志/参数	说明	默认值
`[address]`	登录地址	无
`-p, --profile <name>`	使用预置的命名配置，替代直接传入地址	无
`--duration <seconds>`	请求的 STS 凭据有效期（秒）	`3600`
`--identity-only`	只保存用户 OIDC 会话，不执行 STS 角色交换。	`false`
`--no-open`	不打开浏览器，仅打印登录 URL（用于无头环境/SSH）	`false`

agentkit auth login
agentkit auth login --identity-only <sso-address>

登录地址与发现文档

传入 [address] 时，CLI 会从该地址读取 /.well-known/agentkit-cli 登录发现文档。地址可以省略 https://；正式远程地址必须使用 HTTPS，只有本地测试地址可以使用 http://localhost、http://127.0.0.1 或 http://[::1]。地址不能包含用户名、密码、查询参数或 fragment。使用共享登录域名时，可以在域名后追加一个租户路径，例如 https://login.example.com/team-a；该路径必须是单段小写 slug，不能包含多级路径、路径遍历或编码后的路径分隔符。远程发现文档必须直接返回 JSON 对象，不能依赖重定向，响应体大小不能超过 64 KiB。自定义租户地址的发现文档只能使用以下字段：

字段	说明	默认值
`issuer`	UserPool issuer，必须是官方 UserPool 的 HTTPS origin。	必填
`client_id`	公开 OAuth client id。	必填
`role_trn`	STS role TRN；普通登录必填，身份仅登录可省略。	—
`provider_trn`	IAM OIDC provider TRN；与 `role_trn` 同时提供或同时省略。	—
`cloud_provider`	云厂商：`volcengine` 或 `byteplus`，必须与 `issuer` 匹配。	必填
`region`	云区域，必须与 `issuer` 中的区域一致。	必填
`transport`	使用 STS 坐标时必须为 `sts`。	—
`scope`	OAuth scope 列表，必须包含 `openid`。	`openid profile email offline_access`

agentkit auth login https://login.example.com/team-a
agentkit auth login --identity-only ./local-discovery.json

身份仅登录不会提供控制面权限。需要解析 Runtime、管理资源或查询项目时，请另外配置 AK/SK，或使用普通 agentkit login 获取 STS 凭据。通过远程发现文档登录时，CLI 只会在浏览器登录和后续凭据处理成功后保存 profile。

auth logout

清除已存储的 SSO 会话（刷新令牌与缓存的 STS 凭据）。

标志/参数	说明	默认值
`-p, --profile <name>`	SSO 配置名称	当前活跃配置
`--all`	清除所有配置的会话	`false`

agentkit auth logout

auth whoami

显示当前凭据背后的身份。

标志/参数	说明	默认值
`-p, --profile <name>`	SSO 配置名称	当前活跃配置

agentkit auth whoami

auth profile set

创建或更新某个配置的登录坐标（非机密信息）。

标志/参数	说明	默认值
`<name>`	配置名称（必填）	无
`--issuer <url>`	OIDC issuer URL	无
`--client-id <id>`	公开的 OAuth client id	无
`--role-trn <trn>`	STS role TRN；未使用 `--identity-only` 时必填。	无
`--provider-trn <trn>`	IAM OIDC provider TRN	无
`--region <region>`	区域	`cn-beijing`
`--identity-only`	保存无需 STS 角色的 OIDC-only profile。	`false`

agentkit auth profile set my-profile \
  --issuer https://example.com \
  --client-id abc123 \
  --identity-only

登录状态保存在 ~/.agentkit/auth。长效 refresh token 会优先写入操作系统密钥环；无法使用密钥环时，CLI 将会话文件以 0600 权限写入本地。身份仅会话不会保留 OAuth access token，CLI 也不会打印已存储的 token。

auth profile list

列出已保存的配置。该命令不接受任何参数或选项。

agentkit auth profile list

auth profile show

显示某个配置的坐标。

标志/参数	说明	默认值
`[name]`	配置名称	当前活跃配置

agentkit auth profile show my-profile

auth admin 子命令需要能管理 Identity、IAM 和 TOS 资源的云端凭证。可以使用 AK/SK，也可以使用当前 CLI SSO profile 中仍然有效的 STS 凭据。为避免管理操作被项目或全局端点覆盖影响，auth admin 会使用内置服务端点。

auth admin doctor

以只读方式检查账号能否完成 CLI SSO 接入，包括身份资源权限与凭证托管前置条件。检查未通过时命令返回非零退出码，并输出修复建议。

标志/参数	说明	默认值
`--account <account>`	预期的账号 ID；当前凭证不属于该账号时拒绝继续	—
`--region <region>`	云区域	当前云厂商的默认区域
`--data-plane`	同时检查凭证托管前置条件	`true`
`--no-data-plane`	跳过凭证托管前置条件检查	—

agentkit auth admin doctor --account <account-id> --region cn-beijing

auth admin create-userpool

创建用于 CLI SSO 登录的用户池，并以 JSON 输出用户池 ID。

该命令会在指定账号和区域创建身份资源。执行前先用 auth admin doctor 检查账号、区域和权限。

标志/参数	说明	默认值
`--name <name>`	用户池名称（必填）	—
`--account <account>`	预期的账号 ID；当前凭证不属于该账号时拒绝继续	—
`--region <region>`	云区域	当前云厂商的默认区域

agentkit auth admin create-userpool --name agentkit-cli-pool --account <account-id>

auth admin provision

为已有用户池创建或复用公开 CLI 客户端、IAM OIDC provider 和 STS 角色，并输出可发布的登录发现配置。

该命令会修改用户池和 IAM 资源。确认用户池属于目标账号与区域，并仅授予终端用户所需的角色权限。

标志/参数	说明	默认值
`--user-pool <uid>`	用户池 ID（必填）	—
`--account <account>`	预期的账号 ID；当前凭证不属于该账号时拒绝继续	—
`--region <region>`	云区域	当前云厂商的默认区域

agentkit auth admin provision --user-pool <user-pool-id> --account <account-id>

auth admin sso-setup

一次性准备用户池、公开 CLI 客户端、IAM OIDC provider、STS 角色和 TOS 登录发现文档，最后输出可分发给终端用户的 agentkit login <address> 地址。交互终端会询问是否复用用户池、是否配置上游身份提供方和是否使用自定义域名；非交互环境使用默认值或显式标志。

该命令会创建或修改身份、IAM 和 TOS 资源，并发布可公开访问的登录发现文档。上游身份提供方的 secret 属于敏感凭证；优先在交互提示中输入，避免把它写入仓库或 shell 历史。

标志/参数	说明	默认值
`-y, --yes`	非交互执行，接受默认值和显式传入的标志	`false`
`--user-pool <uid>`	复用已有用户池	—
`--create-pool <name>`	创建指定名称的用户池	`agentkit-cli-pool`
`--account <account>`	预期的账号 ID；当前凭证不属于该账号时拒绝继续	当前凭证所属账号
`--region <region>`	云区域	当前云厂商的默认区域
`--idp <type>`	上游身份提供方：`bytedance` \| `feishu`	不配置上游身份提供方
`--idp-client-id <id>`	上游身份提供方 Client ID；非交互模式下与 `--idp-secret` 一同使用	—
`--idp-secret <secret>`	上游身份提供方 Client Secret	—
`--bucket <bucket>`	托管登录发现文档的 TOS bucket	`agentkit-cli-<account-id>`
`--domain <domain>`	已完成 CNAME 与 HTTPS 证书配置的自定义登录域名；只填写主机名，不包含协议、端口或路径。	TOS bucket 的 HTTPS 地址
`--client-name <name>`	公开 CLI 用户池客户端名称	CLI 内置名称
`--provider-name <name>`	IAM OIDC provider 名称	CLI 内置名称
`--role-name <name>`	STS 角色名称	CLI 内置名称

# 交互配置；敏感的上游身份凭证可在隐藏输入提示中填写
agentkit auth admin sso-setup --account <account-id> --region cn-beijing

# 在自动化环境中复用已有用户池
agentkit auth admin sso-setup --yes \
  --user-pool <user-pool-id> \
  --account <account-id> \
  --bucket <discovery-bucket>

传入 --domain 时，命令会在发布后通过该 HTTPS 域名读取发现文档并校验内容。请先完成 CNAME 和证书配置；未通过公开访问校验时，命令不会把自定义域名作为最终登录地址输出。

auth admin publish

为已有用户池创建或复用 CLI 登录资源，并把 /.well-known/agentkit-cli 发现文档发布到指定 TOS bucket。也可以传入已有的 OIDC 与 IAM 坐标，仅发布发现文档而不重新创建 CLI 客户端、OIDC provider 或角色。

未传入显式坐标时，该命令会修改身份和 IAM 资源，并向指定 bucket 写入公开登录配置。确认 bucket、账号、用户池和显式坐标均属于目标环境；使用 --domain 前还需完成 CNAME 与 HTTPS 证书配置。

标志/参数	说明	默认值
`--user-pool <uid>`	用户池 ID（必填）	—
`--bucket <bucket>`	托管发现文档的 TOS bucket（必填）	—
`--account <account>`	预期的账号 ID；当前凭证不属于该账号时拒绝继续	—
`--region <region>`	云区域	当前云厂商的默认区域
`--domain <domain>`	已完成 CNAME 与 HTTPS 证书配置的自定义登录域名；输出会包含需要指向的 TOS 域名。	TOS bucket 的 HTTPS 地址
`--issuer <url>`	已有 OIDC issuer；与 `--client-id`、`--role-trn`、`--provider-trn` 同时传入后进入仅发布模式。	—
`--client-id <id>`	已有公开 OAuth client id；仅发布模式必填。	—
`--role-trn <trn>`	已有目标账号 STS role TRN；仅发布模式必填，且必须属于当前鉴权账号。	—
`--provider-trn <trn>`	已有目标账号 IAM OIDC provider TRN；仅发布模式必填，且必须属于当前鉴权账号。	—

agentkit auth admin publish \
  --user-pool <user-pool-id> \
  --bucket <discovery-bucket> \
  --account <account-id>

agentkit auth admin publish \
  --user-pool <user-pool-id> \
  --bucket <discovery-bucket> \
  --domain login.example.com \
  --issuer https://userpool-<id>.userpool.auth.id.cn-beijing.volces.com \
  --client-id <client-id> \
  --role-trn trn:iam::<account-id>:role/<role-name> \
  --provider-trn trn:iam::<account-id>:oidc-provider/<provider-name> \
  --account <account-id>

仅发布模式要求 --issuer、--client-id、--role-trn 和 --provider-trn 四个参数同时提供。--issuer 必须是 HTTPS URL，不能包含用户名、密码、查询参数或 fragment；--role-trn 与 --provider-trn 必须属于当前鉴权账号。--bucket 必须是 3 到 63 个小写字母、数字或连字符组成的 TOS bucket 名称，并以字母或数字开头和结尾。

开始使用

AI-Friendly

命令参考

登录地址与发现文档

auth logout

auth whoami

auth profile set

auth profile list

auth profile show

auth admin doctor

auth admin create-userpool

auth admin provision

auth admin sso-setup

auth admin publish

​auth login

​登录地址与发现文档

​auth logout

​auth whoami

​auth profile set

​auth profile list

​auth profile show

​auth admin doctor

​auth admin create-userpool

​auth admin provision

​auth admin sso-setup

​auth admin publish

auth login

登录地址与发现文档

auth logout

auth whoami

auth profile set

auth profile list

auth profile show

auth admin doctor

auth admin create-userpool

auth admin provision

auth admin sso-setup

auth admin publish