认证与连接

先配置目标实例

CLI 执行任何业务动作前，都需要知道自己连接的是哪一个 HENGSHI SENSE 实例。

export HBI_API_URL="https://<你的-everest-实例>"

在多环境切换时，建议把不同实例放到明确的 shell profile、CI secret 或 Agent runtime 配置里，而不是在命令执行时临时猜测目标环境。 对外文档统一使用 HBI_* 环境变量；CLI 在迁移期仍兼容读取旧的 EVEREST_*。

方式一：使用 client credentials 登录

这是最常见的登录方式，适合本地终端、服务账号和大多数 Agent runtime。

hbi auth login --client-id <client_id> --client-secret <client_secret>
hbi auth status

完成后，CLI 会把访问令牌缓存到本地，后续命令会自动复用。

方式二：交互式登录

如果你更希望在当前机器上通过交互方式输入凭据，并把凭据写入系统钥匙串，可以使用：

hbi auth login --interactive

这条路径更适合人工使用的本地桌面环境。

方式三：提供 client credentials，让 CLI 自动换取令牌

在 Agent runtime、CI 或后台任务里，也可以直接提供 client credentials：

export HBI_CLIENT_ID="<client_id>"
export HBI_CLIENT_SECRET="<client_secret>"

对需要认证的业务命令，CLI 可以自动换取访问令牌，并把 token cache 到本地以便后续复用。

方式四：直接注入 access token

如果你已经有现成的访问令牌，也可以直接注入：

export HBI_TOKEN="<token>"

这条路径适合：

• 已有外部系统统一分发短期 token
• 临时自动化任务
• 不希望在当前环境保存 client credentials 的场景

常用认证命令

# 查看当前认证状态
hbi auth status --output json

# 主动刷新访问令牌
hbi auth refresh

# 退出登录
hbi auth logout

# 列出系统支持的认证方式
hbi auth methods

# 查看当前激活的认证方式
hbi auth active

对外使用建议

本地人工终端

优先使用：

hbi auth login --interactive

这样更适合长期复用，也更贴合桌面环境的凭据管理习惯。

Agent runtime / CI

优先使用：

export HBI_CLIENT_ID="<client_id>"
export HBI_CLIENT_SECRET="<client_secret>"

如果运行时不希望依赖系统钥匙串，也可以只走环境变量与本地 token cache。

已有现成 access token

优先使用：

export HBI_TOKEN="<token>"

凭据安全建议

• 不要把 token、client secret 硬编码到脚本、文档或仓库里
• 自动化环境优先使用 Secret / 环境变量注入
• 人工桌面环境优先使用交互式登录
• 不要把完整的 auth status 输出原样贴到公开渠道

如果某些容器或受限环境不适合访问系统钥匙串，可以显式设置：

export HBI_DISABLE_KEYRING=true

常见连接问题

HBI_API_URL 未设置

CLI 无法知道目标实例，通常会在首个请求时报连接错误。先确认：

echo "$HBI_API_URL"

登录成功但没有看到目标资源

优先排查这几类问题：

1. 当前连到的不是预期实例
2. 当前账号没有对应应用、数据连接或空间的访问权限
3. Agent 执行时继承的环境变量与当前终端不一致

token 过期或认证状态不稳定

建议优先检查：

hbi auth status --output json
hbi auth refresh

如果你使用的是 client credentials，也请确认 HBI_CLIENT_ID 和 HBI_CLIENT_SECRET 仍然有效。