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) 的命令行工具,功能覆盖:

**数据开发运维**
- 数据传输、任务运维
- 离线开发、实时开发

**数据治理**
- 模型设计、数据标准
- 关系建模、指标平台
- 元数据中心、数据地图
- 数据质量、数据资产

**数据安全**
- 安全中心

**数据应用**
- 数据服务

**基础支撑**
- 控制台、报警系统

---

**使用前需要配置:**
- endpointEasyOpenAPI 服务地址)
- apiKey / secretKeyAPI 密钥)
- 可选:groupIdproductclusterIduser

需要我帮你检查当前配置状态,或者执行某个具体命令吗?

自定义配置目录

默认配置目录为 ~/.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

🟡 可选信息

下面信息请务必根据您的实际使用场景配置。

  1. 如果您只使用一个项目组,建议配置groupId。否则,强烈建议不配置,在实际执行命令时指定。
  2. 如果您只使用一个项目,建议配置product。否则,强烈建议不配置,在实际执行命令时指定。
  3. 如果您只使用一个集群,建议配置clusterId。否则,强烈建议不配置,在实际执行命令时指定。
  4. 如果只是您自己在使用,建议配置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) 的命令行工具,功能覆盖:

**数据开发运维**
- 数据传输、任务运维
- 离线开发、实时开发

**数据治理**
- 模型设计、数据标准
- 关系建模、指标平台
- 元数据中心、数据地图
- 数据质量、数据资产

**数据安全**
- 安全中心

**数据应用**
- 数据服务

**基础支撑**
- 控制台、报警系统

---

**使用前需要配置:**
- endpointEasyOpenAPI 服务地址)
- apiKey / secretKeyAPI 密钥)
- 可选:groupIdproductclusterIduser

需要我帮你检查当前配置状态,或者执行某个具体命令吗?

示例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的日志链接,支持SparkMapReduce等类型。返回列表每项包含:idexecutor/attempt标识)、stdout/stderrstdout/stderr日志地址)、logsYARN日志聚合页面链接对象,仅MapReduce类型)、diagnosticsapplication级别诊断信息)。会自动提取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,我就可以帮你查询基线列表。

我指定项目集群来查询:

使用任务运维查询基线列表,productinternclusterIdeasyops-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