EasyData-CLI介绍
EasyData CLI & Skill 安装与使用指南
EasyData CLI(命令行工具) 是 EasyData 平台面向 Agent 与开发者的统一操作入口——它把平台上每一个能力都封装成一条原子命令:查基线、看实例、跑 SQL、重跑任务等,一条命令即可触发一连串平台操作,让「点页面」变成「敲命令」,天然适配 Agent 调用。
前置条件一:安装 easydata-cli
使用 EasyData CLI 前,必须安装 easydata-cli 命令行工具。获取 EasyOpenAPI 服务地址 <server> 后,根据操作系统执行对应命令。
⚠️ 重要:获取地址
<server>为 EasyOpenAPI 服务地址,请咨询技术支持获取,并区分机房网络和办公网络。
macOS / Linux:
curl -fsSL http(s)://<server>/api/cli/install-script/download | bash
Windows (PowerShell):
& ([ScriptBlock]::Create(([System.Text.Encoding]::UTF8.GetString((New-Object Net.WebClient).DownloadData('http(s)://<server>/api/cli/windows-script/download'))).TrimStart([char]0xFEFF)))
Windows (CMD):
curl -fsSL http(s)://<server>/api/cli/windows-script/download/cli-install.bat >%TEMP%\cli-install.bat & %TEMP%\cli-install.bat
⚠️ 重要:激活配置
安装已完成,但新命令在当前终端中还不生效。请运行:source ~/.bashrc(根据您的 Shell 类型,可能需要改为
~/.zshrc、~/.profile等)
验证安装
执行下面命令,能列出命令列表即安装成功:
easydata-cli -h
前置条件二:安装 EasyData Skill
EasyData Skill 是一套面向 AI 助手的技能包,安装后 AI 助手可以直接调用 EasyData CLI 完成数据开发、运维等操作。
支持的 Agent
CLI 自动识别本机已安装的 Agent 环境,包括但不限于:
- Claude Code
- Codex
- Cursor
- OpenClaw
- OpenCode
- Qoder
- WorkBuddy
- CodeBuddy
若您的 Agent 不在上述列表中,可使用
--path参数手动指定 skills 目录安装。
安装 Skill
直接执行(自动检测本机 Agent 并交互选择安装目标):
easydata-cli skill install
也可以一次性全部安装(在交互列表中勾选「全部安装」):
easydata-cli skill install
指定 skills 目录安装:
easydata-cli skill install --path ~/.claude/skills
验证 Skill
easydata-cli skill version
可查看各 Agent 环境已安装 Skill 的当前版本与最新版本。在 AI 助手对话框中询问"我有哪些 skill?",能看到 easydata 相关条目即安装成功。
Skill 日常管理
# 查看当前版本(自动检测已安装的 Agent)
easydata-cli skill version
# 更新 Skill 到最新版本(无参:更新全部已安装环境)
easydata-cli skill update
# 卸载已安装的 Skill
easydata-cli skill uninstall
自动更新:CLI 在执行任意命令结束时,若距上次 Skill 更新超过 12 小时,会自动静默更新一次 Skill,无需人工干预。
第一部分:验证 EasyData Skill 已加载
步骤 1:重启 Agent(如需要)
某些情况下需要重启 Agent 才能加载新技能,请按您所用 Agent 的常规方式重启(如退出重开会话)。
步骤 2:检查技能列表
在 AI 助手中询问:
我有哪些skill?
或使用命令行查询:
easydata-cli skill version
看到聊天框输出下面类似内容,表明EasyData CLI Skill安装成功:
easydata- EasyData 大数据平台 CLI
步骤 3:测试技能响应
在聊天中输入下面内容:
easydata能做什么?
你会得到下面类似输出:
**easydata** 是大数据开发与管理平台 EasyData (ED) 的命令行工具,功能覆盖:
**数据开发运维**
- 数据传输、任务运维
- 离线开发、实时开发
**数据治理**
- 模型设计、数据标准
- 关系建模、指标平台
- 元数据中心、数据地图
- 数据质量、数据资产
**数据安全**
- 安全中心
**数据应用**
- 数据服务
**基础支撑**
- 控制台、报警系统
---
**使用前需要配置:**
- endpoint(EasyOpenAPI 服务地址)
- apiKey / secretKey(API 密钥)
- 可选:groupId、product、clusterId、user
需要我帮你检查当前配置状态,或者执行某个具体命令吗?
自定义配置目录
默认配置目录为 ~/.easydata,如需更改,可通过环境变量指定:
# 临时生效(当前会话)
export EASYDATA_CONFIG_DIR=/path/to/custom/config
easydata-cli config check
# 永久生效(写入 shell 配置文件)
echo 'export EASYDATA_CONFIG_DIR=/path/to/custom/config' >> ~/.bashrc
source ~/.bashrc
不设置此环境变量时,CLI 默认使用 ~/.easydata 目录。
第二部分:配置 EasyData
技能安装完成后,首次使用前需要配置 EasyData 连接信息。
步骤 1:检查配置状态
在聊天中让助手执行:
检查 easydata 配置
或直接运行:
easydata-cli config check
可能的返回:
{"configured": true}- 已配置,可跳过此部分{"configured": false, "missing": [...]}- 需要配置
步骤 2:准备配置信息
在配置前,请准备以下信息:
🔴 必需信息
下面endpoint信息请联系技术支持获取,aksk也可在用户的个人中心页面查看。
| 配置项 | 类型 | 说明 | 示例 |
|---|---|---|---|
| endpoint | 字符串 | EasyOpenAPI 服务地址(请根据访问位置配置办公网/机房网地址) | https:// |
| apiKey | 字符串 | EasyOpenAPI API Key | ed-ak-xxxxxxxx |
| secretKey | 字符串 | EasyOpenAPI Secret Key | ed-sk-xxxxxxxx |
🟡 可选信息
下面信息请务必根据您的实际使用场景配置。
- 如果您只使用一个项目组,建议配置groupId。否则,强烈建议不配置,在实际执行命令时指定。
- 如果您只使用一个项目,建议配置product。否则,强烈建议不配置,在实际执行命令时指定。
- 如果您只使用一个集群,建议配置clusterId。否则,强烈建议不配置,在实际执行命令时指定。
- 如果只是您自己在使用,建议配置user。否则,强烈建议不配置,在实际执行命令时指定。 当然,如果您做了配置,在调用命令时,也可以指定这些参数覆盖这里的默认值,如果不指定,会使用这里的默认值。
| 配置项 | 类型 | 说明 | 示例 |
|---|---|---|---|
| groupId | 整数 | 项目组ID | 12 |
| product | 字符串 | 项目名称 | <项目名称> |
| clusterId | 字符串 | 集群ID | hz10 |
| user | 字符串 | 您的邮箱 | user@example.com |
步骤 3:执行初始化配置
在聊天中告诉助手:
帮我配置 easydata,信息如下:
endpoint: https://<server>
apiKey: ed-ak-xxxxxxxx
secretKey: ed-sk-xxxxxxxx
groupId: 12
product: <项目名称>
clusterId: hz10
user: user@example.com
助手会执行下面命令,完成配置:
easydata-cli config init \
--endpoint https://<server> \
--apiKey ed-ak-xxxxxxxx \
--secretKey ed-sk-xxxxxxxx \
--groupId 12 \
--product <项目名称> \
--clusterId hz10 \
--user user@example.com
步骤 4:验证配置
配置完成后,再次检查:
检查 easydata 配置是否成功
或:
easydata-cli config check
会返回下面类似信息:
✅ **easydata 已配置完成**
配置状态正常,可以直接使用。需要执行什么命令吗?
第三部分:使用 EasyData Skill
基本使用方式
在 AI 助手聊天中,直接描述你的需求,助手会自动调用 easydata 技能:
示例1:能做什么?
在聊天框中输入下面内容:
easydata能做什么?
你会得到类似回复:
**easydata** 是大数据开发与管理平台 EasyData (ED) 的命令行工具,功能覆盖:
**数据开发运维**
- 数据传输、任务运维
- 离线开发、实时开发
**数据治理**
- 模型设计、数据标准
- 关系建模、指标平台
- 元数据中心、数据地图
- 数据质量、数据资产
**数据安全**
- 安全中心
**数据应用**
- 数据服务
**基础支撑**
- 控制台、报警系统
---
**使用前需要配置:**
- endpoint(EasyOpenAPI 服务地址)
- apiKey / secretKey(API 密钥)
- 可选:groupId、product、clusterId、user
需要我帮你检查当前配置状态,或者执行某个具体命令吗?
示例2:如何使用?
在对话框输入下面内容:
easydata该如何使用?
你会得到类似回复:
**easydata 使用方式:**
easydata-cli <命令> [参数]
---
**配置管理**
# 检查配置
easydata-cli config check
# 初始化配置(首次使用)
easydata-cli config init --endpoint <地址> --apiKey <密钥> --secretKey <密钥>
# 修改某项配置
easydata-cli config set --endpoint <新地址>
---
**主要功能模块**
| 模块 | 用途 | 示例 |
|------|------|------|
| **easydev** | 离线开发(任务、调度) | 创建/管理离线任务 |
| **easytaskops** | 任务运维 | 查看任务状态、日志、基线 |
| **easyolap** | 自助分析 | 执行 SQL 查询 |
| **easydmap** | 数据地图 | 查看数据血缘、资产 |
| **easymetahub** | 元数据中心 | 管理元数据 |
| **easydqc** | 数据质量 | 质量监控、规则 |
---
**查看具体命令帮助**
easydata-cli easydev --help
easydata-cli easytaskops --help
---
你想执行什么具体操作?比如:
- 查看离线任务列表?
- 执行 SQL 查询?
- 查看任务运维状态?
示例3:查看有哪些一级命令
通过对话框方式
在对话框架中输入下面内容:
easydata有哪些命令?
你会得到类似回复:
easydata 有以下 **8 个命令模块**:
| 命令 | 功能 |
|------|------|
| **config** | 配置管理(初始化、检查、修改配置) |
| **cache** | 命令缓存管理(刷新缓存) |
| **easydev** | 离线开发(任务文件夹、离线任务、调度管理) |
| **easydmap** | 数据地图 |
| **easydqc** | 数据质量中心 |
| **easymetahub** | 元数据中心 |
| **easyolap** | 自助分析(执行 SQL 语句) |
| **easytaskops** | 任务运维(大盘、任务运维、实例运维、基线管理、日志) |
想看某个具体命令的详细用法吗?比如 `easydata-cli easydev --help`
通过命令行方式
进入easydata的安装目录(即 Agent 的 skills 目录,可用 easydata-cli skill version 查看各 Agent 的安装路径),执行下面命令,得到下面输出,这里就列出了可用的第一级命令,比如配置模块、缓存模块、数据地图、离线开发、任务运维等。
$ easydata-cli -h
usage: easydata-cli [-h] <command> ...
大数据开发与管理平台 EasyData(ED) 命令行工具,用于数据开发运维(数据传输、任务运维、离线开发、实时开发)、数据治理(模型设计、数据标准、关系建模、指标平台、元数据中心、数据地图、数据质量、数据资产)、数据安全(安全中心)、数据应用(数据服务)以及基础支撑(控制台、报警系统)模块
Config: /Users/username/.easydata/cli.json
options:
-h, --help show this help message and exit
命令:
<command> 可用命令
config EasyData Cli配置管理
cache EasyData Cli命令缓存管理
schema 查看 EasyData 服务命令的详细 schema 信息, 如: schema easydqc 或 schema easydqc.get_data_quality_result
doctor 环境诊断:检查配置完整性、网络连通性、Token有效性
version EasyData Cli版本管理(查看当前版本,更新最新版本)
easydataservice 数据服务相关功能,API查询,集合管理,应用管理,API申请,API应用的绑定与解绑,策略查询,API调用监控等能力
easydev 离线开发相关操作,用于任务文件夹、离线任务、调度的管理
easydmap 数据地图相关操作
easydqc 数据质量管控中心 - 全方位保障数据准确性、合法性、有效性、完整性、及时性和一致性 提供数据质量监控、数据比对验证、数据探查分析三大能力: 质量监控:创建和运行质量规则任务,持续监控数据健康度 数据比对:跨数据源比对数据一致性,发现差异并定位问题
数据探查:自动分析表结构、数据分布、统计特征,快速了解数据面貌
easyindex 统一指标管理平台 - 从定义到应用,全生命周期管理业务指标 提供指标的标准化定义、血缘追溯和版本管理能力: 指标定义:创建和管理原子指标、派生指标,统一指标口径目了然 生命周期:指标的发布、下线、版本管理,确保指标可信可用
域化管理:按业务域组织指标,便于查找和复用 解决"同名不同义、同义不同名"的指标混乱问题
easymetahub 元数据中心相关操作
easyolap 自助分析相关操作,用于执行SQL语句的管理
easystandard 数据标准与规范中心 - 统一数据语言,确保数据定义一致性 提供企业级数据标准管理能力: 词根管理:维护标准化词根库,统一字段命名规范(如 cust = 客户, amt = 金额) 智能翻译:基于词根自动翻译字段含义,辅助数据建模和字段设计 适用于数据建模、字段命名、跨团队数据协作场景
easytaskops 任务运维相关操作,用于大盘、任务运维、实例运维、基线管理、实例日志等管理
示例4:查看有哪些二级命令
通过对话框方式
在对话框架中输入下面内容(这里以查询任务运维为例):
任务运维有哪些命令?
你会得到类似回复,这里列出了14条可用命令:
**easytaskops(任务运维)** 有以下 **14 个命令**:
**实例管理**
- `list_exec_instance` - 获取调度实例列表
- `get_exec_instance` - 获取调度实例详情
- `kill_exec_instance` - 终止调度实例
- `get_instance_job_log` - 获取实例节点日志
**补数据**
- `get_backbill` - 获取补数据详情
- `kill_backbill` - 终止补数据任务
**基线管理**
- `list_baseline` - 获取基线列表
- `list_baseline_task` - 获取基线下任务列表
- `get_baseline_for_task` - 获取任务关联的基线
**告警规则**
- `list_alert_rule_for_task` - 获取任务关联的报警规则列表
- `delete_alert_rule_for_task` - 删除任务关联的所有报警规则
**大盘统计**
- `get_exec_instance_overview` - 查询调度实例大盘统计
- `get_exec_instance_finishing_rate` - 查询调度实例完成率统计
**其他**
- `list_running_yarn_app` - 获取运行中的 Yarn 任务
- `list_tag` - 获取标签列表
想看某个具体命令的详细参数吗?
通过命令行方式
以任务运维为例,执行下面命令,得到下面输出,比如获取补数据详情,获取任务告警规则等。
$ easydata-cli easytaskops -h
任务运维相关操作,用于大盘、任务运维、实例运维、基线管理、实例日志等管理
Usage:
easydata-cli easytaskops <command> [-h]
positional arguments:
<command> 可用命令
delete_alert_rule_for_task 删除任务关联的所有报警规则
get_backbill 获取补数据详情
get_baseline_diagnose_result 获取基线诊断结果,包含基线当前运行状态和诊断原因
get_baseline_for_task 获取任务关联的基线
get_exec_instance 获取调度实例详情(已就绪实例存在实例ID,使用execId查询;未就绪实例使用flow+ project+ scheduleTime查询)
get_exec_instance_finishing_rate
查询调度实例完成率统计,统计某天调度实例的完成情况
get_exec_instance_overview 查询调度实例大盘统计,统计某天任务、实例的数量
get_exec_job_applications 获取调度实例下所有job节点的yarn application列表
get_instance_job_log 获取调度实例(任务)节点日志
get_yarn_application_log_url 获取yarn上对应application的日志链接,支持Spark和MapReduce等类型。返回列表每项包含:id(executor/attempt标识)、stdout/stderr(stdout/stderr日志地址)、logs(YARN日志聚合页面链接对象,仅MapReduce类型)、diagnostics(application级别诊断信息)。会自动提取full log链接(如果存在),优先返回完整日志地址。对于MapReduce类型,接地址。Spark任务若trackingUI=UNASSIGNED则返回仅含diagnostics的单条记录。
kill_backbill 终止补数据任务
kill_exec_instance 终止调度实例
list_alert_histories 查询报警历史记录,按时间范围和项目组过滤,支持按 objectType 对象类型和 objectSearchName 对象名过滤。默认返回100条,分页接口,按时间倒序排列,避免数据过多
list_alert_rule_for_task 获取任务关联的报警规则列表
list_baseline 获取基线列表
list_baseline_exec_detail 获取基线执行详情列表,支持按时间范围和基线ID过滤
list_baseline_exec_instance 获取基线关联的调度任务实例列表
list_baseline_failed_instance
获取基线异常调度任务实例列表
list_baseline_task 获取基线下任务列表
list_exec_instance 获取调度实例列表
list_running_yarn_app 获取运行中的Yarn任务(应用)
list_tag 获取标签列表
rerun_exec_instance 重跑调度实例。自动沿用上次运行配置重跑所有失败节点。可选传入 sparkExecutorMemory/sparkDriverMemory 覆盖 Spark 节点内存配置
resolve_alert_history 响应(处理)一条报警历史记录,标记为已处理
Flags:
-h, --help show this help message and exit
使用 "easytaskops <command> -h" 查看具体命令的详细说明
示例5:二级命令有哪些参数
通过对话框方式
在对话框架中输入下面内容(这里以查询任务运维获取基线列表list_baseline为例):
任务运维获取基线列表如何使用?
你会得到类似回复,这里告诉你需要传递哪些参数,哪些是必填的,哪些是非必填的。
**list_baseline(获取基线列表)** 用法:
easydata-cli easytaskops list_baseline \
--product <项目名称> \
--clusterId <集群ID> \
[--pageNum <页号>] \
[--pageSize <每页条数>] \
[--user <用户邮箱>]
---
**参数说明:**
| 参数 | 必填 | 说明 | 示例 |
|------|------|------|------|
| `--product` | ✅ | 项目名称 | `mammut` |
| `--clusterId` | ✅ | 集群 ID | `hz10` |
| `--pageNum` | ❌ | 页号(默认 1) | `1` |
| `--pageSize` | ❌ | 每页条数(默认 25) | `25` |
| `--user` | ❌ | 调用接口用户邮箱 | `admin@example.com` |
---
**示例:**
easydata-cli easytaskops list_baseline \
--product mammut \
--clusterId hz10 \
--pageNum 1 \
--pageSize 10
需要我帮你执行吗?如果是,请提供 `product`(项目名称)和 `clusterId`(集群 ID)。
通过命令行方式
以查询任务运维获取基线列表list_baseline为例,执行下面命令,得到下面输出,列出你需要传递哪些参数,哪些是必填的,哪些是可选的。
$ easydata-cli easytaskops list_baseline -h
获取基线列表
Usage:
Flag 模式: easydata-cli easytaskops list_baseline [flags]
JSON 模式: easydata-cli easytaskops list_baseline --json <json|@file|->
Flag 模式可选参数:
--product string 项目名称 例: mammut
--clusterId string 集群Id 例: hz10
--pageNum integer 分页页号,从1开始的整数,默认值为1 例: 1
--pageSize integer 每页个数,默认值为25 例: 25
--user string 调用该接口用户邮箱 例: admin.mammmut@163.com
Global Flags:
-h, --help show this help message and exit
-f, --format table|json|raw 输出格式(默认: json)
--timeout <秒> 请求超时时间(默认: 120)
--retry <次数> 失败后最大重试次数(默认: 0)
--dry-run 预览请求但不实际执行
-y, --yes 跳过敏感操作的交互确认
--verbose 显示请求地址、耗时、原始 HTTP 内容
Examples:
# Flag 模式
easydata-cli easytaskops list_baseline
# JSON 模式
easydata-cli easytaskops list_baseline \
--json '{}'
# 参数含特殊字符时,建议使用文件传参: --json @request.json
更多信息:
# 查看完整参数与返回值结构:
easydata-cli schema easytaskops.list_baseline
示例6:执行具体任务
通过对话框方式
这里仍以上述查询基线列表为例,在对话框输入:
使用任务运维查询基线列表
因为我未配置默认的product和clusterId,得到下面回复,如果你已经做了默认配置,将会直接展示结果。
我需要以下信息来执行查询:
**必需参数:**
- `--product`:项目名称(示例:mammut)
- `--clusterId`:集群 ID(示例:hz10)
**可选参数:**
- `--pageNum`:页号(默认 1)
- `--pageSize`:每页条数(默认 25)
- `--user`:用户邮箱
请提供项目名称和集群 ID,我就可以帮你查询基线列表。
我指定项目集群来查询:
使用任务运维查询基线列表,product为intern,clusterId为easyops-cluster
你会得到下面类似回复:
查询成功!**基线列表**(共 23 条):
| ID | 名称 | 周期 | 状态 | 预警时间 | 破线时间 | 描述 |
|----|------|------|------|----------|----------|------|
| 1 | 基线A | 日 | ✅ 启用 | 07:00 | 08:00 | - |
| 2 | 基线B | 日 | ✅ 启用 | 18:01 | 20:01 | - |
| 4 | 基线C | 周 | ✅ 启用 | 周日 05:01 | 周日 15:01 | - |
| 6 | 基线D | 日 | ✅ 启用 | 11:00 | 11:05 | - |
| 30 | 基线E | 日 | ✅ 启用 | 09:30 | 12:00 | - |
| 38 | 基线F | 日 | ✅ 启用 | 18:26 | 19:27 | - |
| 44 | 基线G | 日 | ✅ 启用 | 20:00 | 22:00 | - |
**其他基线**(未启用):基线H、基线I、基线J 等
需要查看某个基线下的任务列表,或者查看其他信息吗?
通过命令行方式
以执行查询任务运维获取基线列表list_baseline为例,执行下面命令,得到下面输出:
$ easydata-cli easytaskops list_baseline --product intern --clusterId easyops-cluster
{"pageNum": 1, "pageSize": 25, "totalPage": 1, "totalCount": 23, "list": [
{"id": 1, "name": "基线A", "period": "DAY", "enabled": true, "description": "", "alertLineTime": {"day": null, "hour": 7, "minute": 0}, "breakLineTime": {"day": null, "hour": 8, "minute": 0}},
{"id": 2, "name": "基线B", "period": "DAY", "enabled": true, "description": "", "alertLineTime": {"day": null, "hour": 18, "minute": 1}, "breakLineTime": {"day": null, "hour": 20, "minute": 1}},
{"id": 3, "name": "基线C", "period": "WEEK", "enabled": true, "description": "", "alertLineTime": {"day": 0, "hour": 5, "minute": 1}, "breakLineTime": {"day": 0, "hour": 15, "minute": 1}},
...(其余条目省略)
]}
--------------------------------------------------------------------------------
### 修改配置
如果要修改配置,可以通过下面方式。
#### 通过对话框方式
```bash
帮我修改 easydata 的 endpoint,修改为 https://new-api.example.com。
通过命令行方式
$ easydata-cli config set --endpoint https://new-api.example.com
已更新配置: endpoint
刷新命令缓存
如果发现命令找不到或参数不对,可以执行命令刷新,系统默认6小时刷新一次。
通过对话框方式
刷新 easydata 命令缓存
通过命令行方式
$ easydata-cli cache refresh
命令缓存已刷新
第四部分:故障排查
问题 1:技能未识别
症状:提到 easydata 时助手没有调用技能
可能原因:
- 技能未正确安装
- Agent 未重启
解决方案:
# 1. 检查技能目录是否存在(可先查看安装路径)
easydata-cli skill version
# 2. 重启 Agent(按您所用 Agent 的常规方式重启会话)
# 3. 再次测试
问题 2:配置检查失败
症状:config check返回{"configured": false}
可能原因:
- 配置文件不存在
- 配置文件格式错误
解决方案:
- 让 AI 助手重新执行配置。
问题 3:认证失败(403错误)
症状:API 调用返回 401/403 错误。
可能原因:
- endpoint 地址错误。
解决方案:
- 确认 endpoint 地址正确,办公网位置访问请使用办公网地址;机房网位置访问请使用机房网地址。
问题 4:鉴权失败
症状:鉴权失败,加密签名不正确;鉴权失败,传入accessKey未匹配任何APP。
可能原因:
- apiKey/secretKey不正确。
解决方案:
- 联系技术支持,获取正确的 AK/SK。
问题 5:命令找不到
症状:提示命令不存在。
解决方案(下面方案二选一):
对话框输入:刷新easydata缓存,AI 助手会重新加载命令。
命令行执行缓存刷新:easydata-cli cache refresh。