# 使用 MOI-CLI 完成第一次工作区检查

MOI-CLI 是 MOI 提供的命令行工具。它通过 Product API 在终端中管理 AI Studio 工作区资源，并可以用 JSON 格式输出结果。

使用 MOI-CLI 可以把资源查询和状态检查写成一组可重复执行的命令。它适合在本地排查问题、批量执行操作，或将 MOI 操作接入 Shell 脚本和 CI，让每次操作都保留清晰的资源 ID 和返回结果，便于复核和后续处理。

你可以在以下场景使用 MOI-CLI：

- 第一次接入工作区时，确认服务地址、账号和工作区是否正确；
- 在终端中快速查看当前身份、工作区和成员信息；
- 在脚本或 CI 中读取 JSON 结果，执行连接检查或权限检查；
- 在不打开浏览器的环境中进行工作区资源的日常检查。

本教程以“新成员第一次接入一个工作区”为例，手把手完成从连接服务、选择工作区到确认当前身份的完整流程。整个流程只读取信息，不会创建、运行、修改或删除任何资源。

## 你将完成什么

- 验证 `moi-cli` 已安装并能正常运行；
- 配置 Product API 服务地址和个人访问令牌；
- 列出当前身份可以访问的工作区，并保存目标工作区；
- 确认当前登录身份和工作区成员信息。

## 开始前准备

- 已安装 `moi-cli`，并能运行 `moi-cli -version`。安装方式请参阅 [MOI-CLI 下载](../developer/quickstart/downloads/cli.md)。
- 已创建个人访问令牌。创建方式请参阅 [访问凭据](../guides/billing/credentials.md#personal-access-token)。
- 个人访问令牌对至少一个 AI Studio 工作区具有读取权限。
- 准备一个安全的本地终端。不要把令牌写入脚本、代码仓库或共享终端记录。

## 操作步骤

### 1. 验证 CLI 是否可用

先查看版本和帮助，确认终端能够找到 `moi-cli`：

```shell
moi-cli -version
moi-cli --help
```

下面的输出表示 CLI 已成功启动：终端显示版本号、Product API 说明、全局选项和可用命令。

```{image} ../assets/images/tutorials/moi-cli-version-help.png
:alt: 在终端执行 moi-cli -version 和 moi-cli --help，显示版本号、全局选项和命令列表
```

如果能看到版本号和命令帮助，就可以继续配置连接信息。如果终端提示找不到命令，请先完成 [MOI-CLI 下载](../developer/quickstart/downloads/cli.md)中的安装步骤。

### 2. 配置服务地址和个人访问令牌

使用 Product API 服务地址和个人访问令牌配置 CLI：

```shell
moi-cli config set-endpoint "https://api.moi.matrixorigin.cn/v5"
moi-cli config set-api-key "<个人访问令牌>"
```

令牌按原始值传入，不要添加 `Bearer` 前缀。配置完成后检查保存的配置：

```shell
moi-cli config show
```

下面的输出表示服务地址已经保存，个人访问令牌已被掩码；工作区 ID 尚未设置，下一步将从可访问的工作区列表中选择目标工作区。

```{image} ../assets/images/tutorials/moi-cli-config-auth.png
:alt: 执行配置命令并查看 CLI 配置，服务地址已保存且个人访问令牌显示为掩码
```

输出中的服务地址应为 `https://api.moi.matrixorigin.cn/v5`，`api_key` 应显示为掩码。若令牌未被掩码显示，不要继续操作，先检查终端和 CLI 版本，避免凭据出现在屏幕或日志中。

### 3. 找到并选择工作区

先列出当前身份可以访问的工作区：

```shell
moi-cli -o workspace list
```

从 JSON 结果中找到要检查的工作区，核对工作区名称和 ID。将 ID 保存到变量，并写入 CLI 配置：

```shell
export WORKSPACE_ID='<目标工作区 ID>'
moi-cli config set-workspace "$WORKSPACE_ID"
```

再次查看配置，确认工作区 ID 已保存：

```shell
moi-cli config show
```

下面的输出表示工作区 ID 已经保存到配置文件中，个人访问令牌仍以掩码显示：

```{image} ../assets/images/tutorials/moi-cli-config-workspace.png
:alt: 执行 config show，显示已保存的工作区 ID 和掩码后的个人访问令牌
```

如果工作区列表为空，说明当前令牌没有可访问的工作区；请检查令牌所属账号和工作区成员权限，不要随意填写工作区 ID。

### 4. 确认当前身份

工作区配置完成后，确认 CLI 使用的身份：

```shell
moi-cli -o workspace-member current-principal
```

返回结果中的 `user`、`role` 和 `status` 可以帮助你确认当前登录身份及其状态。例如，下面的输出显示当前用户、角色为 `SuperAdmin`，用户状态为 `enabled`：

```{image} ../assets/images/tutorials/moi-cli-current-principal.png
:alt: 使用 workspace-member current-principal 查看当前用户、角色和启用状态
```

检查返回的用户或主体信息是否与预期一致。身份不正确时，先回到第 2 步检查个人访问令牌，不要继续执行其他命令。

### 5. 查看工作区成员

确认身份后，读取当前工作区的成员列表：

```shell
moi-cli -o workspace-member members
```

返回结果中的 `total` 表示成员总数，`user_list` 中可以查看成员状态和角色。例如，下面的输出显示当前工作区有 1 名成员，成员状态为 `enabled`，角色为 `superadmin`：

```{image} ../assets/images/tutorials/moi-cli-members.png
:alt: 使用 workspace-member members 查看工作区成员总数、状态和角色
```

检查目标账号是否出现在成员列表中，并记录其当前角色或状态。成员列表为空或无权读取时，不代表工作区不存在；这通常表示当前身份缺少成员读取权限。

## 教程完成

现在，你已经完成了第一次 MOI-CLI 工作区检查：确认了 CLI 版本和服务连接，选择了目标工作区，并核对了当前身份和成员信息。后续可以使用同样的方法检查其他工作区资源；需要在脚本或 CI 中处理 JSON 时，请参阅 [脚本与 CI 自动化](../developer/cli/json-output-automation.md)，需要了解更多资源命令时，请参阅 [常见任务](../developer/cli/tasks/index.md)。