# Use the CLI in terminals and scripts

Query data in a terminal or manage AskTable resources through scripts.

使用指南 · 模块: integrations · 应用开发者 · 部署形态：资料未说明 · 已确认产品版本：资料未说明 · 来源：现有文档

AskTable CLI is the official command-line tool, published as the npm package `@datamini/asktable-cli` with the command name `asktable`. It calls AskTable's REST API using a project API-Key without depending on a browser, making it suitable for scripts, pipelines, and bulk maintenance. Business users can simply use web [Conversations](https://docs.asktable.com/en/conversation) without learning the CLI.

## Before you begin

- Environment: Node.js 18 or later.
- Credentials: a project API-Key. Use `asker` for questions only; request `admin` only to create data sources or change Agents or permissions.
- Creation location: left main navigation → “Settings” → “API-Key” → “Create API-KEY”; select the type in the dialog. The full value is shown only once, on creation.
- Entry: a local terminal.

## Steps

**Install**

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

After installation, the `asktable` command is available; `asktable --help` lists all command groups.

**Log in**

Interactive login asks for the API Key and Server URL in sequence:

```bash
asktable auth login
```

For noninteractive use, pass the global options directly:

```bash
asktable auth login --api-key YOUR_API_KEY --server https://<your-AskTable-site>
```

After successful login, configuration is written to the current user's `~/.config/asktable/config.json` with keys `api_key` and `api_url`. Use `asktable auth status` to view the active Key (only its first 5 characters plus `***`) and Server; `asktable auth logout` clears local configuration.

**Use environment variables in CI**

Inject the Key through environment variables instead of writing it to a file:

```bash
export ASKTABLE_API_KEY='YOUR_API_KEY'
export ASKTABLE_API_URL='https://<your-AskTable-site>'
```

Priority from highest to lowest is: command-line `--api-key` / `--server` → environment variables `ASKTABLE_API_KEY` / `ASKTABLE_API_URL` → configuration file → built-in default `https://api.asktable.com`. Private deployments must explicitly specify Server, or requests go to Cloud.

**Ask your first question**

`query` is the only entry point for questions. Without a specified conversation, it creates a conversation, sends a message, polls until analysis finishes, and outputs the answer and `conversation_id`:

```bash
asktable query "Your data question" \
  --data-agent <agent_id> \
  --json
```

Use either `--data-agent` or `--datasources`; `--datasources` accepts multiple comma-separated data source IDs:

```bash
asktable query "Your data question" --datasources ds_xxxxxxxx --json
```

Polling runs every 1 second, waiting up to 120 seconds; a timeout reports `Conversation <id> response timed out (120s)`.

**Follow up in the same conversation**

Pass the previous output's `conversation_id` to follow up in the same conversation:

```bash
asktable query "Your follow-up question" \
  --conversation <conversation_id> \
  --json
```

For row-level permissions, pass a role and role variables; variable options can be repeated:

```bash
asktable query "Your data question" \
  --data-agent <agent_id> \
  --role <role_id> \
  --role-variable dept_id=D001 \
  --json
```

**Maintain resources in bulk as needed**

Common command groups:

| Goal                                                    | Command                                                                     |
| ------------------------------------------------------- | --------------------------------------------------------------------------- |
| View data sources                                       | `asktable ds list`, `asktable ds get <id>`                                  |
| Create/update/delete data sources                       | `asktable ds create`, `asktable ds update <id>`, `asktable ds delete <id>`  |
| Test connections, upload files                          | `asktable ds test-connection <id>`, `asktable ds upload`                    |
| Sync metadata                                           | `asktable ds meta sync <id>`, `asktable ds meta preview <id>`               |
| Export/import metadata                                  | `asktable ds meta export <id>`, `asktable ds meta import <id>`              |
| Change field descriptions, visibility, AI value indexes | `asktable ds field edit <id>`                                               |
| Change table descriptions                               | `asktable ds table edit <id>`                                               |
| Manage training question-answer pairs                   | `asktable ds training list <id>`, `create`, `update`, `delete`              |
| Manage data Agents                                      | `asktable data-agent list/get/create/update/delete`                         |
| Manage skills                                           | `asktable skill list/get/create/update/delete`                              |
| Manage roles                                            | `asktable role list/get/create/update/delete`                               |
| Manage policies                                         | `asktable policy list/get/create/update/delete`                             |
| View historical conversations                           | `asktable conv list`, `asktable conv get <id>`, `asktable conv delete <id>` |
| View available project model groups                     | `asktable model-group list`                                                 |
| View project information                                | `asktable project get`, `asktable project update`                           |

Delete commands ask for confirmation by default; `--yes` skips it. Refer to `asktable --help` and each subcommand's `--help` for full options.

**Install CLI instructions for an AI coding assistant**

`asktable get-skill` prints an instruction file teaching an AI coding assistant to use `asktable`:

```bash
asktable get-skill
```

Save the output as a Markdown file in the coding assistant's skill directory to drive these commands with natural language. “Skill” here means CLI instructions for the coding assistant, distinct from an Agent's [Skills](https://docs.asktable.com/en/agent/skill), which describe analysis methods.

The same guidance is available on the web: the top of “Settings” → “API-Key” has a collapsible “Use in AI Agent” section containing this instruction, ready to copy and send to an Agent.

## Key constraints

| Item                    | Value or default                                                                                                 | Where to change it                             |
| ----------------------- | ---------------------------------------------------------------------------------------------------------------- | ---------------------------------------------- |
| Node.js version         | 18 or later                                                                                                      | Local environment                              |
| Configuration file path | `~/.config/asktable/config.json`                                                                                 | No UI switch                                   |
| Configuration priority  | `--api-key`/`--server` > `ASKTABLE_API_KEY`/`ASKTABLE_API_URL` > configuration file > `https://api.asktable.com` | Command options or environment variables       |
| Default Server          | `https://api.asktable.com`                                                                                       | Override with `--server` or `ASKTABLE_API_URL` |
| `query` wait limit      | 120 seconds (polling once per second)                                                                            | No UI switch                                   |
| `--json`                | Off by default, producing human-readable text; enabling produces structured JSON                                 | Command options                                |
| Delete commands         | Confirmation required by default; `--yes` skips it                                                               | Command options                                |
| Project API-Key types   | `asker` asks questions only; `admin` manages all resources                                                       | “Settings” → “API-Key”                         |

## Troubleshooting

| Symptom                                                                               | Identifying condition                                               | Resolution                                                                                        |
| ------------------------------------------------------------------------------------- | ------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
| Every command says no API Key is configured and asks you to run `asktable auth login` | `asktable auth status` shows Logged out                             | Run `asktable auth login` first, or add `--api-key`                                               |
| Login fails with an invalid API Key                                                   | `auth login` receives a non-2xx response when probing with this Key | Confirm the Key was not deleted and has no extra spaces; create a new one on “API-Key”            |
| 401 error                                                                             | Response status is 401                                              | Change the Key; it may have been deleted or belong to another project                             |
| 404 error                                                                             | Response status is 404                                              | The command's ID is incorrect or the resource was deleted; confirm the ID with `list`             |
| 422 error                                                                             | Response status is 422                                              | Parameters are incorrect; fix required fields according to the response                           |
| `query` reports a conversation response timeout (120s)                                | Conversation remains `streaming` or `pending` for 120 seconds       | Open it on the web to see whether it is stuck; split a large question or use a faster model group |
| `query` ends with `[Status: warning]`, `[Status: error]`, or `[Status: paused]`       | Conversation did not end normally                                   | Check details with `asktable conv get <conversation_id>`, or open it on the web                   |
| Private deployment commands go to Cloud                                               | Server in `asktable auth status` is `https://api.asktable.com`      | Use `--server` or `ASKTABLE_API_URL` to point to your site                                        |

## Next steps

- Let an MCP-capable AI client call AskTable directly: [MCP](https://docs.asktable.com/en/integrations/mcp)
- Integrate data questions into business systems: [OpenAPI](https://docs.asktable.com/en/integrations/openapi)
- Prepare data sources and field semantics: [Connect data sources](https://docs.asktable.com/en/data/connect), [Table and field descriptions](https://docs.asktable.com/en/data/semantics)