---
title: 面向 AI Agent 的 Sudomimus CLI
description: 把 Sudomimus CLI 作为 AI 编程助手、本地自动化和账户检查的命令行控制面。
editUrl: true
head: []
template: doc
sidebar:
  order: 4
  hidden: false
  attrs: {}
pagefind: true
draft: false
---

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

适用场景包括：

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

CLI 用来操作 Sudomimus 自身。如果你是在开发一个让用户登录的 CLI 应用，请选择[原生应用接入路径](/zh-cn/native/overview/)。

## 首次登录

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

```bash
sudomimus login
```

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

```bash
sudomimus login --no-open
```

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

## 机器可读输出

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

```bash
sudomimus whoami --json
```

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

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

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

## 端点覆盖

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

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

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

```bash
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 中，不复制进提示词。