面向 AI Agent 的 Sudomimus CLI

当 AI 助手需要直接操作 Sudomimus 时，Sudomimus CLI 是最合适的控制面。它把操作暴露成普通 shell 命令，方便助手调用；真正的身份认证仍然通过 device authorization flow 在用户浏览器中完成。

适用场景包括：

• 确认当前登录的是哪个 Sudomimus 账户；
• 在 CLI 会话过期前自动刷新，不反复要求用户重新登录；
• 随着命令增加，调用 With 的账户管理或开发者操作；
• 在编辑器、终端或类 CI 的 agent 环境中工作，此时没有浏览器 cookie 可用。

CLI 用来操作 Sudomimus 自身。如果你是在开发一个让用户登录的 CLI 应用，请选择原生应用接入路径。

首次登录

安装后的 CLI 使用 sudomimus 这个二进制命令：

sudomimus login

CLI 会打印验证 URL 和用户代码，能打开浏览器时会自动打开，并等待 device grant 完成。远程 agent 或纯终端环境中，可以让浏览器步骤保持手动：

sudomimus login --no-open

本地会话会写入 $SUDOMIMUS_CLI_HOME/credentials.json；未设置该环境变量时写入 ~/.sudomimus/credentials.json。该文件包含 bearer 凭据；AI 助手应该调用 CLI，而不是读取或打印这个文件。

机器可读输出

面向 agent 的数据命令应优先使用 JSON 输出。当前第一个可用读取命令是：

sudomimus whoami --json

它会以 JSON 返回当前 With 账户身份。如果 access token 临近过期，CLI 会先通过 Connect 刷新，再调用 With。

给 AI 助手的提示词可以这样写：

使用 Sudomimus CLI 完成 Sudomimus 账户操作。命令支持 --json 时优先使用 JSON。
如果 CLI 尚未登录，请让我运行 `sudomimus login --no-open`，然后把验证 URL
和用户代码放到浏览器中完成登录。不要读取或打印 ~/.sudomimus/credentials.json。

端点覆盖

本地开发时，CLI 支持显式覆盖端点：

sudomimus login \
  --device-api-base-url http://localhost:7701 \
  --connect-api-base-url http://localhost:7101 \
  --with-api-base-url http://localhost:7301

也可以用环境变量提供相同配置：

SUDOMIMUS_DEVICE_API_BASE_URL=http://localhost:7701
SUDOMIMUS_CONNECT_API_BASE_URL=http://localhost:7101
SUDOMIMUS_WITH_API_BASE_URL=http://localhost:7301
SUDOMIMUS_WITH_APPLICATION_ANCHOR=sudomimus-with
SUDOMIMUS_CLI_HOME=.sudomimus-cli

端点覆盖对在仓库检出内运行的 agent 很有用：助手可以把 CLI 指向本地 Serverless 进程，而不需要改动已保存的生产凭据。

安全模型

CLI 不需要 sudomimus-with 的 client-auth 私钥。登录使用通用 device authorization flow：CLI 向 device-api 请求 device code，用户在浏览器中完成正常的 Sudomimus 认证；只有用户批准后，CLI 才拿到 access/refresh token。

这样可以把高风险步骤保留给用户确认，同时让登录后的操作适合 agent 调用：

• 浏览器负责通行密钥、邮箱验证码、OAuth 和企业联合登录；
• CLI 负责 token 刷新和 API 调用；
• AI 助手负责选择命令和解析 JSON；
• 凭据保留在本地 CLI store 中，不复制进提示词。