cz-cli 安装与使用指南

cz-cli 是 云器ClickZetta Lakehouse 面向命令行和 AI Agent 的操作工具。它把 Lakehouse 的连接配置、SQL 执行、Schema 和表管理、Studio 任务开发、任务运行巡检、Job 诊断等能力封装成稳定的 CLI 命令，让你既可以在终端中直接操作，也可以让 Claude Code、Cursor、Kiro、Hermes 等 AI Agent 通过自然语言协助完成数仓开发和运维。

使用 cz-cli 后，你可以把“建一个测试数仓”“检查今天任务失败原因”“帮我回填一段时间的数据”“查询这张表的字段和样例数据”这类需求交给 cz-cli 执行；cz-cli 完成实际操作，并把结果以结构化方式返回。

适用对象

  • 数据开发、数据平台、运维和分析团队，需要通过命令行管理 ClickZetta Lakehouse。
  • 希望把 AI Agent 接入 ClickZetta，让 Agent 可以执行查询、创建任务、诊断运行问题、生成运维方案的团队。
  • 需要在本地、CI/CD、企业机器人或运维工作台中自动化调用 ClickZetta 能力的团队。

核心能力

能力说明常用命令
连接管理创建和切换不同环境的连接配置，例如生产、测试、UATcz-cli profile create、cz-cli profile list、cz-cli profile use
SQL 查询执行 SELECT、DDL、DML，支持同步等待和异步 Jobcz-cli sql、cz-cli job status、cz-cli job result
Schema 和表管理查看、创建、描述、预览、统计 Schema 和表cz-cli schema、cz-cli table
Studio 任务创建SQL、离线集成、实时等任务、并可配置调度、发布上线、和手动执行cz-cli task
运行巡检查看任务运行记录、日志、依赖、统计、失败重跑和补数cz-cli runs、cz-cli attempts
性能诊断查看 SQL Job 状态、结果和执行 Profilecz-cli job、cz-cli sql --job-profile
AI Agent 集成让 Agent 用自然语言调用 ClickZetta 能力cz-cli agent run、cz-cli ai-guide
数据源管理管理外部数据源，为同步和导入任务做准备cz-cli datasource

准备信息

安装前请确认已获得以下信息，如不确定可参考文档：

信息说明示例
服务端点ClickZetta API 服务地址cn-shanghai-alicloud.api.clickzetta.com
实例名ClickZetta 实例名称或 IDdemo_instance
Workspace工作空间名称analytics_prod
用户名和密码用于连接 ClickZetta 的账号data_user
默认 Schema登录后默认使用的 Schemapublic
默认计算组执行 SQL 或任务时使用的 Virtual ClusterDEFAULT

如使用 Personal Access Token（PAT），可用 PAT 替代用户名和密码。

安装 cz-cli

macOS / Linux

推荐使用npm 方式安装：

npm install -g @clickzetta/cz-cli

也可以使用一键安装脚本：

curl -fsSL https://github.com/clickzetta/cz-cli/releases/latest/download/install.sh | sh

安装完成后重新加载 Shell 配置：

zsh 用户

source ~/.zshrc

bash 用户

source ~/.bashrc

Windows

方式一：使用 npm 安装。

如果本机已安装 Node.js 和 npm，可直接安装 npm 包：

npm install -g @clickzetta/cz-cli

方式二：下载安装包。

  1. 打开 GitHub Releases：https://github.com/clickzetta/cz-cli/releases
  2. 下载 Windows 版本压缩包，例如 cz-cli-windows-x64.zip。
  3. 解压后将 cz-cli.exe 所在目录加入系统 PATH。
  4. 重新打开 PowerShell 或 CMD。

验证安装

cz-cli --version

能看到版本号即表示安装成功。

也可以查看帮助：

cz-cli --help

配置连接 Profile

Profile 是 cz-cli 保存连接信息的本地配置。建议为每个环境创建一个独立 profile，例如 prod、uat、dev。

使用用户名和密码创建

cz-cli profile create prod --service api.clickzetta.com --instance <实例名> --workspace <workspace名> --username <用户名> --password '<密码>' --schema public --vcluster DEFAULT

示例：

cz-cli profile create prod --service api.clickzetta.com --instance demo_instance --workspace analytics_prod --username data_user --password 'your_password' --schema public --vcluster DEFAULT

使用 JDBC 串创建

如果你已经有 JDBC 连接串，也可以直接创建 profile：

cz-cli profile create prod --jdbc "jdbc:clickzetta://<实例名>.<服务端点>/<workspace名>?username=<用户名>&password=<密码>&schema=public&virtualCluster=DEFAULT"

使用CLI Credential 创建

cz-cli setup --credencial <your cli Connection String>

如何获取PAT

1) 登录你的云器账号,在左侧菜单选择LakehouseMCP。

2) 如果你没有创建过PAT，请先完成创建。

3) 完成创建后，切换到CLI页签，复制你的CLI连接串

4) 如果你已经有PAT，请将你的PAT复制到创建CLI弹出的弹窗中，然后点击“生成连接串”按钮。

当你已经复制了CLI连接串之后，回到cz-cli弹窗将这个连接串补充到以下命令中，并执行：

cz-cli setup --credential <your cli Connection String >

执行完成后，即完成profile配置。

查看和切换 Profile

查看本机已配置的 profile

cz-cli profile list

设置默认 profile

cz-cli profile use prod

临时使用某个 profile 执行命令

cz-cli -p uat status

验证连接

cz-cli -p prod status

返回结果中 connected 为 true 表示连接成功。

第一次使用

查看当前工作空间

cz-cli -p prod workspace current

查看 Schema

cz-cli -p prod schema list

执行只读查询

cz-cli sql 默认是异步提交，适合长查询；如果希望命令直接等待并返回结果，请加 

--sync
--sync
。

cz-cli -p prod sql "SELECT current_timestamp()" --sync

也可以使用 -e 传入 SQL：

cz-cli -p prod sql -e "SELECT * FROM public.your_table LIMIT 10" --sync

执行写操作

为了避免误操作，INSERT、UPDATE、DELETE、CREATE、DROP 等写操作需要显式加 --write。

cz-cli -p prod sql --write --sync -e "CREATE TABLE IF NOT EXISTS public.demo_orders (id INT, amount DECIMAL(18,2))"

查看表结构和样例数据

cz-cli -p prod table describe public.demo_orderscz-cli -p prod table preview public.demo_orders

Studio 任务开发与运维

cz-cli 可以操作 ClickZetta Studio 中的任务，适合数据开发和日常运维。

创建 SQL 任务

cz-cli -p prod task create daily_order_summary --type SQL --description "每日订单汇总"

保存任务 SQL

cz-cli -p prod task save-content daily_order_summary --content "INSERT INTO public.order_summary SELECT current_date(), COUNT(*) FROM public.orders"

配置调度

下面示例表示每天 02:00 执行：

cz-cli -p prod task save-cron daily_order_summary --cron "0 0 2 * * ? *"

发布任务

cz-cli -p prod task deploy daily_order_summary

手动执行任务

cz-cli -p prod task execute daily_order_summary --max-wait-seconds 300

查看运行记录和日志

查看最近运行

cz-cli -p prod runs list --task daily\_order\_summary --limit 5

查看某次运行详情

cz-cli -p prod runs detail \<run\_id>

查看某次运行日志

cz-cli -p prod runs logs \<run\_id>

等待某次运行完成

cz-cli -p prod runs wait \<run\_id>

配合 AI Agent 使用

cz-cli 的重要价值是让 AI Agent 拥有可控、可审计的 ClickZetta 操作入口。你可以在 Claude Code、Cursor、Kiro、Hermes 等工具中，让 Agent 通过命令行调用 cz-cli。

推荐给 Agent 的提示词

将下面这段话发给你的 AI Agent：

你可以使用 cz-cli 操作 ClickZetta Lakehouse。请先运行 cz-cli status 确认连接；涉及写操作、任务发布、补数、删除、下线等高风险动作时，必须先给出执行计划并等待我确认；查询和巡检可以直接执行，结果请用简明表格或要点总结。

常见自然语言请求

下面示例中的 <profile>、<task_name>、<job_id> 需要替换成你自己的连接配置、任务名和 Job ID。建议让 Agent 先执行 cz-cli -p <profile> status 确认连接可用。

请使用 <profile> 环境，先确认 cz-cli 连接状态，然后列出当前 workspace 中有哪些 schema，再列出 public schema 下的前 20 张表。请使用测试环境 <profile>，帮我在 demo schema 下创建一张订单明细表，插入几行测试数据，然后验证能查到数据。执行写操作前请先给出计划并等待我确认。请使用 <profile> 环境，检查任务 <task_name> 今天是否有失败运行。如果有，请查看运行详情和日志，并给出失败原因与修复建议。请使用 <profile> 环境，分析 SQL job <job_id> 的执行情况，查看 job 状态、结果和执行 profile，判断是否存在性能瓶颈。

通过 cz-cli 自带 Agent 入口执行

如果当前环境已经配置好 cz-cli Agent 所需的大模型参数，也可以直接运行：

cz-cli -p \<profile> agent run "帮我检查今天失败的调度任务，并按失败原因分类"

如需给外部 Agent 生成命令说明：

cz-cli ai-guide cz-cli ai-guide --wide cz-cli ai-guide -f json

在企业机器人场景中使用

如果你使用 Hermes 等企业机器人承载 AI Agent，建议将 cz-cli 安装在机器人执行环境中，并采用以下策略：

  • 只给机器人配置必要的 ClickZetta 权限，避免使用高权限管理员账号。
  • 对写入、删除、发布、下线、补数等操作启用人工确认。
  • 对可访问机器人的用户做白名单或审批控制。
  • 将 profile、PAT、密码等凭据放在受控环境变量或本机配置中，不要写入公开文档、聊天记录或代码仓库。

输出格式与自动化

cz-cli 默认输出 JSON，便于 AI Agent 和脚本解析。也可以指定其他格式：

表格格式，适合人工阅读

cz-cli -p prod -o table status

CSV 格式，适合导出

cz-cli -p prod -o csv sql "SELECT \* FROM public.orders LIMIT 100" --sync

提取单个字段

cz-cli -p prod --field data.connected status

在 CI/CD 或自动化脚本中，建议：

  • 使用固定 profile 名称，例如 prod-readonly、uat-admin。
  • 查询类命令使用 --sync 和 --timeout 控制等待时间。
  • 写操作显式加 --write，并在流程中保留审批或人工确认。
  • 优先使用 JSON 输出，避免解析自然语言文本。

升级

查看当前版本：

cz-cli --version

升级到最新版本：

cz-cli update

如果是通过 npm 安装：

npm install -g @clickzetta/cz-cli

常见问题

Q: 安装后提示 cz-cli: command not found？

通常是 PATH 没有生效。重新加载 Shell 配置：

source \~/.zshrc

或手动加入 PATH：

echo 'export PATH="$$HOME/.clickzetta/bin$$PATH"' >> \~/.zshrc source \~/.zshrc

Q: status 显示 connected: false？

按顺序检查：

cz-cli profile list cz-cli -p \<profile名称> status

确认 profile 中的 service、instance、workspace、用户名、密码或 PAT 是否正确。如果你的Lakehouse实例配置有网络策略，确认本机所在网络能访问Lakehouse服务。

Q: 如何修改 profile 中的字段？

profile配置文件在你当前用户目录下的.clickzetta/profiles.toml路径下的profile.toml文件中。

你可以使用 profile update 命令修改：

cz-cli profile update prod workspace <新的workspace名> cz-cli profile update prod password '<新密码>' cz-cli profile update prod schema public cz-cli profile update prod vcluster DEFAULT

Q: 查询能成功，但任务运行相关命令失败？

task、runs、attempts 等命令依赖 Studio 侧能力。请确认当前 profile 对应的环境已开通 Studio 任务能力，并且账号具备查看或管理任务的权限。

Q: 执行 CREATE TABLE 或 INSERT 被拒绝？

写操作需要加 --write：

cz-cli -p prod sql --write --sync -e "INSERT INTO public.demo\_orders VALUES (1, 99.9)"

Q: SQL 返回了 job_id，没有直接返回数据？

这是因为默认异步执行。需要直接返回查询结果时，加 --sync：

cz-cli -p prod sql "SELECT \* FROM public.demo\_orders LIMIT 10" --sync

如果已经拿到 job_id，可以继续查询：

cz-cli -p prod job status \<job\_id> cz-cli -p prod job result \<job\_id>

Q: 如何降低误操作风险？

  • 查询、巡检、诊断可以让 Agent 直接执行。
  • 写入、删除、任务发布、任务下线、补数、失败重跑等动作建议要求 Agent 先给出计划并等待人工确认。
  • 为 Agent 单独配置低权限账号或只读 profile。
  • 在生产环境使用明确的 profile 名称，例如 prod-readonly、prod-operator。

推荐上手路径

  1. 安装 cz-cli，并确认 cz-cli --version 正常。
  2. 创建 profile，并通过 cz-cli -p <profile> status 验证连接。
  3. 用 schema list、table list、sql --sync 完成一次只读查询。
  4. 在测试环境中尝试一次建表或插入，熟悉 --write 保护机制。
  5. 查看 task --help 和 runs --help，了解任务开发和运维命令。
  6. 将 cz-cli 交给 AI Agent 使用，并约定高风险操作必须人工确认。

账户名称（account_name）、服务名称（instance_name）等概念和查找方式，详见：https://www.yunqi.tech/documents/Key_Concepts

相关文档

ClickZetta-CLI
SQL 执行与数据探索
Yunqi © 2024 Yunqi, Inc. All Rights Reserved.
联系我们
预约咨询
微信咨询
电话咨询