npm package: @kesi/cli
Description: CLI for KESI platform
Latest version: 1.0.1

# @kesi/cli

> kesi IoT 平台命令行工具

[![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
[![npm version](https://img.shields.io/npm/v/@kesi/cli.svg)](https://www.npmjs.com/package/@kesi/cli)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.6-blue.svg)](https://www.typescriptlang.org/)

## 简介

`@kesi/cli` 是 kesi IoT 平台的官方命令行工具（CLI），提供了一套完整的 API 访问能力，让你可以通过终端高效地管理 IoT 平台资源。

### 主要功能

- **报警管理** - 报警规则配置、报警查询、确认与统计
- **数据表管理** - 表结构定义与 CRUD 操作
- **记录管理** - 表记录的增删改查
- **时序数据** - 最新数据与历史数据查询
- **属性点查询** - 设备属性点信息获取
- **设备控制** - 单个与批量设备控制命令
- **文件管理** - 文件上传、下载与删除
- **报表管理** - 报表配置、生成与管理
- **用户管理** - 用户信息查询
- **统计分析** - 设备在线状态统计

## 安装

```bash
# 全局安装
npm install -g @kesi/tools

# 或使用 yarn
yarn global add @kesi/tools

# 或使用 pnpm
pnpm add -g @kesi/tools
```

## 快速开始

### 1. 登录配置

首次使用需要登录配置：

```bash
# 使用用户名密码登录
kesi login --url https://your-kesi-server.com --project your-project-id -u username -p password

# 或直接使用 token
kesi login --url https://your-kesi-server.com --project your-project-id -t your-token
```

### 2. 查看配置

```bash
kesi config
```

### 3. 登出

```bash
kesi logout
```

## 命令使用

### 输出格式

所有查询命令都支持多种输出格式：

```bash
# 表格格式（默认）
kesi warnings list -o table

# JSON 格式
kesi warnings list -o json

# 纯文本格式
kesi warnings list -o plain
```

### 报警管理

```bash
# 查询报警列表
kesi warnings list
kesi warnings ls                           # 别名

# 带过滤条件查询
kesi warnings list --level 3 --status 0
kesi warnings list --device-id "xxx" --limit 20

# 获取报警详情
kesi warnings get <id>

# 确认报警
kesi warnings confirm <id> -n "已处理"

# 标记已恢复
kesi warnings resolve <id> -n "故障已修复"

# 批量确认
kesi warnings batch-confirm id1 id2 id3 -n "批量确认"

# 获取报警统计
kesi warnings stats

# 获取最新报警
kesi warnings latest -l 10
```

### 报警规则管理

```bash
# 查询规则列表
kesi rules list

# 获取规则详情
kesi rules get <id>

# 创建规则
kesi rules create -n "温度报警" -l 3 -d "温度超过阈值时报警"

# 更新规则
kesi rules update <id> -n "新名称" -e false

# 删除规则
kesi rules delete <id>
```

### 数据表管理

```bash
# 查询表列表
kesi tables
kesi tbl                                   # 别名

# 获取表详情
kesi table <id>

# 创建表（从 JSON 文件）
kesi table-create --file table-schema.json

# 更新表
kesi table-update <id> --file table-schema.json

# 删除表
kesi table-delete <id>
```

### 记录管理

```bash
# 查询记录
kesi records <table>
kesi rec <table>                           # 别名

# 带过滤条件查询
kesi records <table> -f '{"status":"active"}' -l 20

# 获取单条记录
kesi record <table> <id>

# 创建记录
kesi record-create <table> --json '{"field1":"value1"}'
kesi record-create <table> --file data.json --upsert

# 更新记录
kesi record-update <table> <id> --json '{"field1":"newvalue"}'

# 删除记录
kesi record-delete <table> <id>
kesi record-delete <table> <id> --attachment  # 级联删除附件

# 批量删除
kesi records-batch-delete <table> id1 id2 id3
```

### 时序数据查询

```bash
# 查询最新数据
kesi data-latest --device <device-id> --tag <tag-id>

# 从文件批量查询
kesi data-latest --file device-tags.json

# 查询历史数据
kesi data-history --device <device-id> --tag <tag-id> --start 1672531200000 --end 1672617600000
```

### 设备控制

```bash
# 发送单条控制命令
kesi control-send --device <device-id> --tag <tag-name> --value <value>

# 批量控制
kesi control-batch --file commands.json
```

### 文件管理

```bash
# 上传文件
kesi file-upload /path/to/file.png

# 查看文件信息
kesi file-info <file-id>

# 删除文件
kesi file-delete <file-id>
```

### 报表管理

```bash
# 查询报表列表
kesi reports
kesi rpt                                    # 别名

# 获取报表详情
kesi report <id>

# 执行报表
kesi report-execute <id> --json '{"param1":"value1"}'

# 创建报表
kesi report-create -n "日报表" -t "daily" -d "每日数据统计"

# 更新报表
kesi report-update <id> -n "新报表名称"

# 删除报表
kesi report-delete <id>
```

### 用户管理

```bash
# 获取当前用户信息
kesi user

# 获取用户列表
kesi users
```

### 统计分析

```bash
# 统计设备在线状态
kesi stats-online table1 table2 table3
```

## 配置文件

配置文件位于 `~/.kesirc.json`，格式如下：

```json
{
  "baseUrl": "https://your-kesi-server.com",
  "projectId": "your-project-id",
  "token": "your-token-here",
  "username": "",
  "password": "",
  "timeout": 30000,
  "logLevel": "info",
  "retries": 3
}
```

你也可以在项目根目录创建 `.kesirc.json` 文件（参考 [`.kesirc.json.example`](.kesirc.json.example)）。

## 开发

```bash
# 安装依赖
npm install

# 构建
npm run build

# 监听模式构建
npm run watch

# 运行测试
npm test

# 运行测试（带覆盖率）
npm run test:coverage

# 本地运行 CLI
npm run cli -- <command>
```

## 项目结构

```
src/
├── commands/          # 命令实现
│   ├── warning.ts     # 报警相关命令
│   ├── tables.ts      # 表管理命令
│   ├── records.ts     # 记录管理命令
│   ├── tags.ts        # 属性点查询
│   ├── data.ts        # 时序数据查询
│   ├── stats.ts       # 统计命令
│   ├── files.ts       # 文件管理
│   ├── control.ts     # 设备控制
│   ├── reports.ts     # 报表管理
│   └── users.ts       # 用户管理
├── api.ts             # API 客户端
├── config.ts          # 配置管理
├── formatter.ts       # 输出格式化
├── logger.ts          # 日志工具
├── errors.ts          # 错误定义
├── types.ts           # 类型定义
└── index.ts           # CLI 入口
```

## License

MIT

## 支持

- 提交 Issue: [GitHub Issues](https://github.com/kesi/tools/issues)
- 官方文档: [kesi 文档中心](https://docs.kesi.cc)