> ## Documentation Index
> Fetch the complete documentation index at: https://avala.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI

> 从终端管理 Avala 资源

Avala CLI 让您直接从命令行列出数据集、创建导出、管理云存储等。

## 安装

<CodeGroup>
  ```bash Recommended theme={null}
  curl -fsSL https://avala.ai/install.sh | bash
  ```

  ```bash pip theme={null}
  pip install avala[cli]
  ```
</CodeGroup>

安装脚本会检测您的 Python 版本，通过 pip 安装 `avala[cli]`，并验证设置。需要 Python 3.9+。

这将安装 `avala` 命令以及 [Click](https://click.palletsprojects.com/) 和 [Rich](https://rich.readthedocs.io/) 用于格式化终端输出。

## 认证

将 API 密钥设置为环境变量（推荐）：

```bash theme={null}
export AVALA_API_KEY="avk_your_api_key"
```

或在任何命令中作为标志传递：

```bash theme={null}
avala --api-key avk_your_api_key datasets list
```

交互式设置凭证：

```bash theme={null}
avala configure
```

这将引导您输入 API 密钥和基础 URL，然后打印要添加到 shell 配置文件的 `export` 语句。

## 全局选项

| 选项                | 描述                                                                       |
| ----------------- | ------------------------------------------------------------------------ |
| `--api-key TEXT`  | Avala API 密钥（或设置 `AVALA_API_KEY` 环境变量）。                                  |
| `--base-url TEXT` | API 基础 URL（或设置 `AVALA_BASE_URL` 环境变量）。默认值：`https://api.avala.ai/api/v1`。 |
| `--help`          | 显示任何命令的帮助。                                                               |

## 命令

### datasets

```bash theme={null}
# 列出所有数据集
avala datasets list

# 限制结果数量
avala datasets list --limit 10

# 获取特定数据集
avala datasets get <uid>
```

**`list` 选项：**

| 选项                | 描述        |
| ----------------- | --------- |
| `--limit INTEGER` | 返回的最大结果数。 |

**`get` 输出字段：** UID、名称、Slug、项数、类型、创建时间、更新时间。

***

### projects

```bash theme={null}
# 列出所有项目
avala projects list

# 获取特定项目
avala projects get <uid>
```

**`list` 选项：**

| 选项                | 描述        |
| ----------------- | --------- |
| `--limit INTEGER` | 返回的最大结果数。 |

**`get` 输出字段：** UID、名称、状态、创建时间、更新时间。

***

### tasks

```bash theme={null}
# 列出所有任务
avala tasks list

# 限制结果数量
avala tasks list --limit 50

# 获取特定任务
avala tasks get <uid>
```

**`list` 选项：**

| 选项                | 描述        |
| ----------------- | --------- |
| `--limit INTEGER` | 返回的最大结果数。 |

**`get` 输出字段：** UID、名称、类型、状态、项目、创建时间、更新时间。

***

### exports

```bash theme={null}
# 列出所有导出
avala exports list

# 获取导出详情
avala exports get <uid>

# 创建新导出
avala exports create --project <uid>
avala exports create --dataset <uid>
```

**`create` 选项：**

| 选项               | 描述           |
| ---------------- | ------------ |
| `--dataset TEXT` | 要导出的数据集 UID。 |
| `--project TEXT` | 要导出的项目 UID。  |

***

### storage-configs

管理云存储连接（AWS S3、Google Cloud Storage）。

```bash theme={null}
# 列出存储配置
avala storage-configs list

# 添加 S3 存储桶
avala storage-configs create \
  --name "Production S3" \
  --provider aws_s3 \
  --s3-bucket-name my-bucket \
  --s3-bucket-region us-west-1 \
  --s3-access-key-id $AWS_ACCESS_KEY_ID \
  --s3-secret-access-key $AWS_SECRET_ACCESS_KEY

# 添加 GCS 存储桶
avala storage-configs create \
  --name "Production GCS" \
  --provider gc_storage \
  --gc-bucket-name my-gcs-bucket \
  --gc-auth-json '{"type":"service_account",...}'

# 测试存储连接
avala storage-configs test <uid>

# 删除存储配置（会提示确认）
avala storage-configs delete <uid>
```

**`create` 选项：**

| 选项                  | 描述                           |
| ------------------- | ---------------------------- |
| `--name TEXT`       | 存储配置的名称（必需）。                 |
| `--provider CHOICE` | `aws_s3` 或 `gc_storage`（必需）。 |

**AWS S3 选项：**

| 选项                            | 描述                      |
| ----------------------------- | ----------------------- |
| `--s3-bucket-name TEXT`       | S3 存储桶名称。               |
| `--s3-bucket-region TEXT`     | AWS 区域（例如 `us-west-1`）。 |
| `--s3-bucket-prefix TEXT`     | 对象键前缀。                  |
| `--s3-access-key-id TEXT`     | AWS 访问密钥 ID。            |
| `--s3-secret-access-key TEXT` | AWS 秘密访问密钥。             |

**Google Cloud Storage 选项：**

| 选项                      | 描述            |
| ----------------------- | ------------- |
| `--gc-bucket-name TEXT` | GCS 存储桶名称。    |
| `--gc-prefix TEXT`      | 对象键前缀。        |
| `--gc-auth-json TEXT`   | 服务账户 JSON 凭证。 |

***

### agents

管理自动化代理。

```bash theme={null}
# 列出代理
avala agents list

# 获取代理详情
avala agents get <uid>

# 创建代理
avala agents create \
  --name "QA Bot" \
  --events "task.completed,result.submitted" \
  --callback-url https://example.com/hook

# 删除代理（会提示确认）
avala agents delete <uid>

# 列出代理执行
avala agents executions <uid>

# 测试代理
avala agents test <uid>
```

***

### webhooks

管理 Webhook 订阅。

```bash theme={null}
# 列出 Webhook
avala webhooks list

# 创建 Webhook
avala webhooks create \
  --target-url https://example.com/webhook \
  --events "task.completed,export.ready"

# 删除 Webhook（会提示确认）
avala webhooks delete <uid>

# 测试 Webhook
avala webhooks test <uid>

# 列出 Webhook 投递
avala webhooks deliveries
```

***

### quality-targets

管理项目的质量目标。

```bash theme={null}
# 列出项目的质量目标
avala quality-targets list --project <uid>

# 创建质量目标
avala quality-targets create \
  --project <uid> \
  --name "Accuracy Target" \
  --metric accuracy \
  --threshold 0.95 \
  --operator gte \
  --severity critical

# 评估项目的所有质量目标
avala quality-targets evaluate --project <uid>
```

***

### consensus

管理项目的共识评分。

```bash theme={null}
# 获取项目的共识摘要
avala consensus summary --project <uid>

# 列出共识分数
avala consensus scores --project <uid>

# 计算共识分数
avala consensus compute --project <uid>

# 查看或更新共识配置
avala consensus config --project <uid>
avala consensus config --project <uid> --iou-threshold 0.7 --min-annotations 3
```

***

### fleet

<Info>
  车队命令处于预览阶段。此处描述的命令可能会更改。
</Info>

管理车队设备、录制、事件、规则和警报。

```bash theme={null}
# 列出在线设备
avala fleet devices list --status online

# 注册新设备
avala fleet devices register --name "robot-arm-01" --type manipulator --firmware "2.4.1"

# 列出设备的录制
avala fleet recordings list --device dev_abc123 --since 7d

# 创建时间轴事件
avala fleet events create --recording rec_abc123 --type anomaly --label "Gripper force spike"

# 列出活跃警报
avala fleet alerts list --status open
```

***

### configure

CLI 凭证的交互式设置向导。

```bash theme={null}
avala configure
```

提示输入 API 密钥和基础 URL，然后输出要添加到 shell 配置文件（`~/.bashrc`、`~/.zshrc` 等）的 `export` 命令。

## 示例

### 列出数据集并导出项目

```bash theme={null}
# 查看拥有的数据集
avala datasets list

# 从项目导出标注
avala exports create --project proj_abc123

# 检查导出状态
avala exports get exp_xyz789
```

### 设置云存储

```bash theme={null}
# 连接 S3 存储桶
avala storage-configs create \
  --name "Training Data" \
  --provider aws_s3 \
  --s3-bucket-name ml-training-data \
  --s3-bucket-region us-east-1 \
  --s3-access-key-id $AWS_ACCESS_KEY_ID \
  --s3-secret-access-key $AWS_SECRET_ACCESS_KEY

# 验证连接是否正常
avala storage-configs test sc_abc123
```

### 在 CI/CD 中使用

```bash theme={null}
# 在 CI 管道中
export AVALA_API_KEY="${AVALA_API_KEY}"

# 触发导出并获取 UID
avala exports create --project proj_abc123
```

## 环境变量

| 变量               | 描述               | 默认值                           |
| ---------------- | ---------------- | ----------------------------- |
| `AVALA_API_KEY`  | 您的 Avala API 密钥。 | 必需                            |
| `AVALA_BASE_URL` | API 基础 URL 覆盖。   | `https://api.avala.ai/api/v1` |

## 输出格式

CLI 使用 [Rich](https://rich.readthedocs.io/) 进行格式化输出：

* **列表命令**以格式化表格显示结果。
* **获取命令**显示键值详情视图。
* **创建/删除命令**打印确认消息。

当输出被管道传递或重定向时，颜色和格式会自动禁用。

<Note>
  CLI 尚不支持 `--output json` 或 `--format` 标志。所有输出都针对终端可读性进行格式化。如需机器可读输出，请直接使用 [Python SDK](/docs/zh/sdks/python) 或 [REST API](/docs/sdks/rest-api)。
</Note>