# 在终端和脚本里使用 CLI

在终端中查询数据，或通过脚本管理 AskTable 资源。

AskTable CLI 是官方命令行工具，发布为 npm 包 `@datamini/asktable-cli`，命令名 `asktable`。它通过项目 API-Key 调用 AskTable 的 REST API，不依赖浏览器，适合脚本、流水线和批量维护。业务人员不需要学它，直接在网页里[对话](https://docs.asktable.com/conversation)即可。

## 开始前

- 环境：Node.js 18 或更高版本。
- 凭证：一个项目 API-Key。只要提问就用 `asker` 类型；要建数据源、改智能体或权限才申请 `admin` 类型。
- 创建位置：左侧主导航 → 「设置」 → 「API-Key」 → 「创建 API-KEY」，弹窗里选类型。完整值只在创建时显示一次。
- 入口：本地终端。

## 操作步骤

**安装**

```bash
npm install --global @datamini/asktable-cli
```

装好后 `asktable` 命令可用，`asktable --help` 列出全部命令组。

**登录**

交互式登录会依次问 API Key 和 Server URL：

```bash
asktable auth login
```

非交互场景直接把全局参数带上：

```bash
asktable auth login --api-key YOUR_API_KEY --server https://<你的 AskTable 站点>
```

登录成功后配置写到当前用户的 `~/.config/asktable/config.json`，键名是 `api_key` 和 `api_url`。用 `asktable auth status` 查看当前生效的 Key（只显示前 5 位加 `***`）和 Server；`asktable auth logout` 清掉本地配置。

**在 CI 里改用环境变量**

不把 Key 写进文件，用环境变量注入：

```bash
export ASKTABLE_API_KEY='YOUR_API_KEY'
export ASKTABLE_API_URL='https://<你的 AskTable 站点>'
```

取值优先级从高到低是：命令行 `--api-key` / `--server` → 环境变量 `ASKTABLE_API_KEY` / `ASKTABLE_API_URL` → 配置文件 → 内置默认 `https://api.asktable.com`。私有部署必须显式给 Server，否则会打到云端。

**发起第一次提问**

`query` 是提问的唯一入口。不指定会话时它新建一个对话、发消息、轮询等分析跑完，再输出回答和 `conversation_id`：

```bash
asktable query "你的数据问题" \
  --data-agent <agent_id> \
  --json
```

`--data-agent` 和 `--datasources` 二选一即可；`--datasources` 用逗号分隔多个数据源 ID：

```bash
asktable query "你的数据问题" --datasources ds_xxxxxxxx --json
```

轮询间隔 1 秒，最多等 120 秒；超时会报 `对话 <id> 响应超时（120s）`。

**追问同一个会话**

把上一步输出的 `conversation_id` 带上，就在同一个会话里追问：

```bash
asktable query "你的追问" \
  --conversation <conversation_id> \
  --json
```

需要行级权限时传入角色和角色变量，变量可重复传：

```bash
asktable query "你的数据问题" \
  --data-agent <agent_id> \
  --role <role_id> \
  --role-variable dept_id=D001 \
  --json
```

**按需批量维护资源**

常用命令组：

| 目标               | 命令                                                                        |
| ---------------- | ------------------------------------------------------------------------- |
| 查看数据源            | `asktable ds list`、`asktable ds get <id>`                                 |
| 建/改/删数据源         | `asktable ds create`、`asktable ds update <id>`、`asktable ds delete <id>`  |
| 测连接、传文件          | `asktable ds test-connection <id>`、`asktable ds upload`                   |
| 同步元数据            | `asktable ds meta sync <id>`、`asktable ds meta preview <id>`              |
| 导出/导入元数据         | `asktable ds meta export <id>`、`asktable ds meta import <id>`             |
| 改字段说明、可见性、AI 值索引 | `asktable ds field edit <id>`                                             |
| 改表描述             | `asktable ds table edit <id>`                                             |
| 管理训练问答对          | `asktable ds training list <id>`、`create`、`update`、`delete`               |
| 管理数据智能体          | `asktable data-agent list/get/create/update/delete`                       |
| 管理技能             | `asktable skill list/get/create/update/delete`                            |
| 管理角色             | `asktable role list/get/create/update/delete`                             |
| 管理策略             | `asktable policy list/get/create/update/delete`                           |
| 查历史对话            | `asktable conv list`、`asktable conv get <id>`、`asktable conv delete <id>` |
| 查项目可用模型组         | `asktable model-group list`                                               |
| 查看项目信息           | `asktable project get`、`asktable project update`                          |

删除类命令默认会问一次确认，加 `--yes` 跳过。完整参数以 `asktable --help` 和各子命令的 `--help` 为准。

**给 AI 编程助手装上 CLI 说明**

`asktable get-skill` 会把一份教 AI 编程助手使用 `asktable` 的说明文件打印出来：

```bash
asktable get-skill
```

把输出保存成 markdown 文件放进编程助手的 skill 目录，它就能用自然语言驱动这套命令。注意这里的“Skill”是给编程助手看的 CLI 使用说明，和智能体上挂的[技能](https://docs.asktable.com/agent/skill)（分析方法）是两回事。

在网页里也能拿到同样的引导：「设置」 → 「API-Key」页面顶部有「在 AI Agent 中使用」折叠区，里面直接给出这句话，复制发给 Agent 即可。

## 关键约束

| 项目            | 值或默认                                                                                               | 在哪里改                                 |
| ------------- | -------------------------------------------------------------------------------------------------- | ------------------------------------ |
| Node.js 版本    | 18 或更高                                                                                             | 本地环境                                 |
| 配置文件路径        | `~/.config/asktable/config.json`                                                                   | 无界面开关                                |
| 配置优先级         | `--api-key`/`--server` > `ASKTABLE_API_KEY`/`ASKTABLE_API_URL` > 配置文件 > `https://api.asktable.com` | 命令行参数或环境变量                           |
| 默认 Server     | `https://api.asktable.com`                                                                         | 用 `--server` 或 `ASKTABLE_API_URL` 覆盖 |
| `query` 等待上限  | 120 秒（每秒轮询一次）                                                                                      | 无界面开关                                |
| `--json`      | 默认关，输出人类可读文本；打开后输出结构化 JSON                                                                         | 命令行参数                                |
| 删除类命令         | 默认要求确认，`--yes` 跳过                                                                                  | 命令行参数                                |
| 项目 API-Key 类型 | `asker` 只问数；`admin` 管全部资源                                                                          | 「设置」 → 「API-Key」                     |

## 出问题怎么判断

| 现象                                                            | 判定条件                                                         | 处理                                                    |
| ------------------------------------------------------------- | ------------------------------------------------------------ | ----------------------------------------------------- |
| 任何命令都提示未配置 API Key、需要先运行 `asktable auth login`                | `asktable auth status` 显示为未登录                                | 先 `asktable auth login`，或给命令加 `--api-key`             |
| 报登录失败、API Key 无效                                              | `auth login` 用这个 Key 探测接口时返回非 2xx                            | 确认 Key 没被删、没有多余空格；重新在「API-Key」页建一个                    |
| 报 401                                                         | 响应状态是 401                                                    | 换 Key；Key 可能已删除或属于别的项目                                |
| 报 404                                                         | 响应状态是 404                                                    | 命令里的 ID 写错，或资源已被删；用 `list` 确认 ID                      |
| 报 422                                                         | 响应状态是 422                                                    | 参数错误，按返回信息改正必填项                                       |
| `query` 报对话响应超时（120s）                                         | 120 秒内会话状态一直是 `streaming` 或 `pending`                        | 到网页里打开这条对话看是否卡住；问题过大时拆小或换更快的模型组                       |
| `query` 输出末尾出现 `[状态: warning]`、`[状态: error]` 或 `[状态: paused]` | 会话没有正常结束                                                     | 用 `asktable conv get <conversation_id>` 看详情，或到网页打开该对话 |
| 私有部署上命令打到云端                                                   | `asktable auth status` 的 Server 是 `https://api.asktable.com` | 加 `--server` 或设 `ASKTABLE_API_URL` 指向自己的站点            |

## 下一步

- 让支持 MCP 的 AI 客户端直接调用 AskTable：[MCP](https://docs.asktable.com/integrations/mcp)
- 把问数接进业务系统：[OpenAPI](https://docs.asktable.com/integrations/openapi)
- 了解数据源和字段语义怎么准备：[连接数据源](https://docs.asktable.com/data/connect)、[表、字段备注](https://docs.asktable.com/data/semantics)