# 配置与认证

`moi-cli` 通过产品 API 端点与个人访问令牌（PAT）访问 MatrixOne Intelligence。配置可写入 `~/.moi-cli.json`，之后多数命令可省略全局参数。

## 准备凭据与端点

1. 在控制台领取个人访问令牌，见 [访问凭据](https://docs.matrixorigin.cn/moi/zh/5.0/guides/billing/credentials.html.md)。
2. 取得当前环境的产品 API 端点。端点必须包含产品 API 前缀（例如 `/newmoi`），见 [Product API 通用约定](https://docs.matrixorigin.cn/moi/zh/5.0/developer/api/product-api/conventions.html.md)。
3. 准备要操作的工作区 ID。

不要把 Genesis 模型密钥、浏览器 Cookie 或系统级部署密钥当作 `moi-cli` 的 `-api-key`。

## 写入配置

```bash
moi-cli config set-endpoint https://<product-host>/newmoi
moi-cli config set-api-key <personal-access-token>
moi-cli config set-workspace <workspace-id>
moi-cli config show
```

`config show` 对任意非空 PAT 只显示固定掩码 `********`，不会回显明文。

也可在单次命令上覆盖配置：

```bash
moi-cli \
  -endpoint https://<product-host>/newmoi \
  -api-key <personal-access-token> \
  -workspace-id <workspace-id> \
  workspace list
```

命令行参数优先于配置文件中的同名项。

## 全局选项

| 选项 | 说明 |
| --- | --- |
| `-endpoint` | 产品 API 端点；默认读取配置，否则为本地开发默认值 |
| `-api-key` | 个人访问令牌；默认读取配置 |
| `-workspace-id` | 本次命令使用的工作区；默认读取配置 |
| `-verbose` | 输出更详细的日志 |
| `-o` | 以 JSON 输出结果 |
| `-no-interactive` | 关闭交互提示（例如分页确认） |
| `-version` / `-help` | 版本或帮助 |

## 工作区与 Role

PAT 只标识人，不固化工作区或 Role。

- 未传 `-workspace-id` 且未配置当前工作区时，需要工作区上下文的命令会失败并提示先配置。
- 可用 `config set-role <workspace-id> <role-id>` 为指定工作区保存 Role Candidate；`config unset-role <workspace-id>` 清除后，该工作区改用服务端 Default Role。
- Role 只能通过持久化配置切换。重新执行 `set-role` / `unset-role` 后启动的**新进程**才会生效。CLI 不提供一次性的全局 `-role-id`，也不会按子命令临时推断 Role。

```bash
moi-cli config set-role <workspace-id> <role-id>
moi-cli config unset-role <workspace-id>
```

## 配置校验

启动业务命令前，CLI 会校验配置中全部 workspace→Role 映射。任一映射非法时：

- 列出排序后的工作区、原因与修复命令；
- 显示 `No request was sent.`，不向服务端发送业务请求；
- 仍可执行 `config show`、`config set-role`、`config unset-role` 等配置命令以便修复。

`config show` 会在非法映射旁标记 `[invalid: ...]`。Role ID 须为规范的正十进制整数；Role 是否属于当前 PAT 用户、工作区与生命周期由服务端校验，失败时不会回退到 Default Role。

## 安全

- 将 PAT 保存在本机配置、环境变量或密钥管理中；不要写入源码、镜像、工单或日志。
- 不要依赖会打印 WebSocket 握手凭据的命令；`moi-cli` 不提供此类输出。
- 轮换或禁用令牌后，同步更新 `~/.moi-cli.json` 或命令行传入的 `-api-key`。