# Subcommand Reference

This document contains detailed descriptions and complete parameter lists for all subcommands.

---

## ls Subcommand — Discover Data Resources

Before initiating analysis, use `ls` to understand what databases and tables are available.

> **⚠️ Important**: The `ls` command only shows databases that have been **imported into Data Agent Data Center**. If you can't find the database you need, it means the database has not been imported from DMS yet.

### List All Databases

```bash
python3 scripts/data_agent_cli.py ls
```

Output is divided into two groups:
- **Database Connections** (ImportType: RDS/DMS) — Real relational databases, can be used with `db` subcommand
- **File Data Sources** (ImportType: FILE) — Uploaded file datasets

Each database record displays:
```
  internal_data_employees  [mysql]  (RDS)
    AgentDbId     : <AGENT_DB_ID>
    DmsDbId       : <DMS_DB_ID>
    DmsInstanceId : <DMS_INSTANCE_ID>
    InstanceName  : <INSTANCE_NAME>
```

> **Tip**: `internal_data_employees` is DataAgent's built-in demo database, containing employee, department, and salary test data, suitable for first-time experience.

### Filter by Keyword

```bash
python3 scripts/data_agent_cli.py ls --search internal_data_employees
```

### List Tables for a Specific Database + Generate Usable Command

```bash
python3 scripts/data_agent_cli.py ls --db-id <AgentDbId>
```

Output includes a `db` command template ready to copy and use.

---

## db Subcommand — Database Analysis

> **⚠️ Important**: The `db` subcommand requires the database to **already exist in Data Agent Data Center**.

### Data Source Parameters

| Parameter | Description |
|------|------|
| `--dms-instance-id` | DMS Instance ID (numeric) |
| `--dms-db-id` | DMS Database ID (numeric) |
| `--instance-name` | RDS Instance Name |
| `--db-name` | Database Name |
| `--tables` | Table name list, comma-separated |
| `--engine` | Database engine, default `mysql` |

### Session Parameters

| Parameter | Description |
|------|------|
| `--session-mode` | `ASK_DATA` (default) / `ANALYSIS` / `INSIGHT` |
| `--output` | `summary` (default) / `detail` / `raw` |
| `--enable-search` | Enable search capability (default `false`) |

### Query Methods

| Parameter | Description |
|------|------|
| `-q` / `--query` | Single query (runs preset query if not specified) |

---

## file Subcommand — File Analysis

File analysis uses `ANALYSIS` mode by default.

### Parameters

| Parameter | Description |
|------|------|
| `--session-mode` | `ASK_DATA` / `ANALYSIS` (default) / `INSIGHT` |
| `--output` | `summary` (default) / `detail` / `raw` |
| `--enable-search` | Enable search capability (default `false`) |
| `-q` / `--query` | Custom query question |

---

## reports Subcommand — Get Generated Results

View and download reports and chart files generated by the session.

### Parameters

| Parameter | Description |
|------|------|
| `--session-id` | **Required**, Session ID |

---

## Session Mode Description

| Mode | Features | Duration | Report | Use Cases |
|------|------|------|------|----------|
| `ASK_DATA` | Quick SQL query + natural language response, supports follow-up questions | 30 sec - 2 min | ❌ | Simple queries, data validation |
| `ANALYSIS` | Deep analysis, generates complete report | 5-15 min | ✅ | Topic analysis, business reports |
| `INSIGHT` | Multi-dimensional, in-depth data insights | 20-40 min | ✅ | Strategic analysis, trend research |

> **⚠️ Important**: When you need to generate reports (HTML/Markdown/charts), **ANALYSIS mode is recommended**.

## dms Subcommand — DMS Tool Integration

Direct access to DMS metadata, used for discovering instances, databases, and tables.

### Tool List

| Tool | Description |
|------|------|
| `list-instances` | Search database instance list in DMS |
| `search-database` | Search databases by schema name |
| `list-tables` | List tables in specified database |

---

## import Subcommand — Import DMS Database

Import DMS database tables into Data Agent Data Center.

### Parameters

| Parameter | Description |
|------|------|
| `--dms-instance-id` | **Required**, DMS Instance ID (numeric) |
| `--dms-db-id` | **Required**, DMS Database ID (numeric) |
| `--instance-name` | **Required**, RDS Instance Name |
| `--db-name` | **Required**, Database Name |
| `--tables` | **Required**, Table name list to import (comma-separated) |
| `--engine` | Database engine type (default: mysql) |
| `--region` | Region ID (default: cn-hangzhou) |

---

## attach Subcommand — Session Reuse

Connect to an existing session to continue conversation, confirm plans, or check progress.

### Parameters

| Parameter | Description |
|------|------|
| `--session-id` | **Required**, Session ID to connect to |
| `-q` / `--query` | Send single query |
| `--from-start` | Replay session history from beginning (equivalent to --checkpoint 0) |
| `--checkpoint` | Specify exact checkpoint to resume from (e.g., `--checkpoint 219`), used for precise recovery after network interruption |
| `--output` | `summary` (default) / `detail` / `raw` |