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 mcp init、cz-cli agent run
数据源管理管理外部数据源，为同步和导入任务做准备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

安装 cz-cli

macOS / Linux

使用一键安装脚本：

curl -fsSL https://cz-cli.ai/install.sh | bash

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

zsh 用户

source ~/.zshrc

bash 用户

source ~/.bashrc

Windows

安装脚本需要在 Bash 环境中运行。请在 WSL（适用于 Linux 的 Windows 子系统）或 Git Bash 中执行：

curl -fsSL https://cz-cli.ai/install.sh | bash

验证安装

cz-cli --version

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

也可以查看帮助：

cz-cli --help

配置连接 Profile

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

使用 
cz-cli login
cz-cli login
登录（推荐）

cz-cli login
cz-cli login
默认使用浏览器 OAuth 登录。登录成功后，cz-cli 会保存登录会话和令牌，发现当前账号可访问的实例与 Workspace，并为每个实例与 Workspace 组合自动创建一个 Profile；同时会配置云器内置 LLM，便于后续使用 
cz-cli agent
cz-cli agent
。

为登录会话指定一个名称，例如 

prod
prod
：

cz-cli login prod

执行命令后，按终端提示在浏览器中完成登录和授权，再返回终端等待配置完成。

prod
prod
是登录会话名称，不一定是最终 Profile 名称；自动创建的 Profile 通常命名为 
prod_0
prod_0
、
prod_1
prod_1
等。

如果要跳过区域选择，可显式指定区域：

cz-cli login prod --partition cn

中国站使用 

cn
cn
，国际站（Singdata）使用 
intl
intl
。无浏览器的自动化场景可通过 
cz-cli login --help
cz-cli login --help
查看 
--pat
--pat
、
--username
--username
和 
--password
--password
等非 OAuth 选项。

登录完成后，查看会话和自动生成的 Profile：

cz-cli auth status cz-cli auth list cz-cli profile list

选择要使用的 Profile 并验证连接：

cz-cli profile use prod_0 cz-cli -p prod_0 status

使用 JDBC 串创建 Profile

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

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

上例中的 

prod
prod
是自定义的 Profile 名称。

查看和切换 Profile

以下命令中的 

prod
prod
请替换为实际 Profile 名称：OAuth 登录通常使用 
prod_0
prod_0
、
prod_1
prod_1
等自动生成的名称，JDBC 方式则使用创建命令中的名称。

查看本机已配置的 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 list

查看 Schema

cz-cli -p prod schema list

执行只读查询

cz-cli sql 默认同步执行（

--sync
--sync
），会等待并直接返回结果；如果是大查询或长耗时查询，可加 
--async
--async
只返回 job_id，稍后再取结果。

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_orders cz-cli -p prod table preview public.demo_orders

Studio 任务开发与运维

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

创建 SQL 任务

创建任务时必须用 

--folder
--folder
指定所属文件夹。先查看已有文件夹（或用 
cz-cli -p prod task create-folder <名称>
cz-cli -p prod task create-folder <名称>
新建一个）：

cz-cli -p prod task folder-tree

然后在指定文件夹下创建任务：

cz-cli -p prod task create daily_order_summary --type SQL --description "每日订单汇总" --folder <文件夹名或ID>

保存任务 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 操作入口。你可以通过 MCP 把 cz-cli 注册到 Claude Code、Cursor、Codex、Kiro 等外部 Agent，也可以直接使用 cz-cli 自带的 

agent run
agent run
入口。

两种方式的区别如下：

方式适用场景模型来源配置入口
外部 Agent 通过 MCP 调用 cz-cli已在使用 Claude Code、Cursor、Codex、Kiro 等工具外部 Agent 自己使用的模型
cz-cli mcp init
cz-cli mcp init
或手工配置 MCP
使用 cz-cli 自带 Agent希望直接从终端发起自然语言任务
~/.clickzetta/llm.json
~/.clickzetta/llm.json
中配置的模型
cz-cli agent llm
cz-cli agent llm

无论使用哪种方式，都应先完成 cz-cli 安装和 Lakehouse Profile 配置，并确认连接正常：

cz-cli profile list cz-cli status

为外部 Agent 配置 cz-cli MCP

cz-cli mcp init
cz-cli mcp init
会把本机 cz-cli 注册为标准输入输出（stdio）类型的 MCP Server，并写入外部 Agent 所需的配置。用户只需执行 
cz-cli mcp init
cz-cli mcp init
，无需手动运行 
cz-cli mcp serve
cz-cli mcp serve
；外部 Agent 会在需要时自动启动 MCP Server 并调用 cz-cli。

直接运行初始化命令时，cz-cli 会自动检测本机支持的客户端：

cz-cli mcp init

也可以显式指定客户端。当前版本原生支持 

claude
claude
、
cursor
cursor
和 
codex
codex
，
-a
-a
/ 
--client
--client
可以重复使用：

# Claude Code cz-cli mcp init -a claude # Codex cz-cli mcp init -a codex # 同时配置 Claude Code、Cursor 和 Codex cz-cli mcp init -a claude -a cursor -a codex # 配置所有原生支持的客户端 cz-cli mcp init --all

默认写入当前用户的全局配置，适合在多个项目中使用。如果只希望对当前项目生效，可在项目根目录执行：

cz-cli mcp init -a claude --no-global cz-cli mcp init -a codex --no-global

初始化命令会在 MCP 配置中使用 cz-cli 可执行文件的绝对路径。可先通过以下命令取得该路径：

command -v cz-cli

将命令返回的绝对路径填入 

command
command
。初始化命令写入的配置等价于下面的 MCP 定义：

{ "mcpServers": { "cz-cli": { "command": "/absolute/path/to/cz-cli", "args": ["mcp", "serve"] } } }

Claude Code

推荐直接初始化：

cz-cli mcp init -a claude

重启 Claude Code 后查看 MCP 状态：

claude mcp list

Codex

推荐直接初始化：

cz-cli mcp init -a codex

重启 Codex 后查看 MCP 状态：

codex mcp list

Kiro

当前 

cz-cli mcp init
cz-cli mcp init
尚未提供 
kiro
kiro
客户端选项，需要手工配置。Kiro 的项目级配置文件为 
.kiro/settings/mcp.json
.kiro/settings/mcp.json
，用户级配置文件为 
~/.kiro/settings/mcp.json
~/.kiro/settings/mcp.json
。在所需配置文件中加入：

{ "mcpServers": { "cz-cli": { "command": "/absolute/path/to/cz-cli", "args": ["mcp", "serve"] } } }

将 

/absolute/path/to/cz-cli
/absolute/path/to/cz-cli
替换为 
command -v cz-cli
command -v cz-cli
返回的实际路径。重启 Kiro 后，在交互式聊天中输入 
/mcp
/mcp
查看服务状态和可用工具。

指定 Lakehouse Profile

默认生成的 MCP 配置不固定 Profile，

cz-cli mcp serve
cz-cli mcp serve
会在启动时读取 
profiles.toml
profiles.toml
中的 
default_profile
default_profile
。如需切换默认环境，先执行：

cz-cli profile use <profile>

如果某个 Agent 必须固定使用指定环境，可手工把 MCP 参数改为：

{ "mcpServers": { "cz-cli": { "command": "/absolute/path/to/cz-cli", "args": ["mcp", "serve", "--profile", "<profile>"] } } }

为生产环境配置 MCP 时，建议使用单独的低权限或只读 Profile，并在名称中明确标识环境，例如 

prod-readonly
prod-readonly
。

推荐给 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 "帮我检查今天失败的调度任务，并按失败原因分类"

在企业机器人场景中使用

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

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

配置 cz-cli Agent 大模型

cz-cli agent run
cz-cli agent run
需要先配置一个大模型。大模型配置和 Lakehouse 连接 Profile 相互独立：

配置保存位置用途
Lakehouse Profile
~/.clickzetta/profiles.toml
~/.clickzetta/profiles.toml
连接实例、Workspace、Schema 和计算组
Agent LLM
~/.clickzetta/llm.json
~/.clickzetta/llm.json
为 
cz-cli agent run
cz-cli agent run
提供模型

使用 cz-cli 登录配置云器内置 LLM

推荐使用浏览器 OAuth 登录。首次登录会配置 OAuth 会话、Lakehouse Profile 和云器内置 LLM：

cz-cli login prod

prod
prod
是登录会话名称。登录后，cz-cli 会根据账号可访问的实例和 Workspace 创建 
prod_0
prod_0
、
prod_1
prod_1
等 Profile，并把 LLM 配置写入 
~/.clickzetta/llm.json
~/.clickzetta/llm.json
。

重复登录同一个会话时，cz-cli 默认保留现有 LLM 配置，避免覆盖用户自行配置的 AI Gateway Key。如果需要从当前账号重新写入内置 LLM 配置，使用：

cz-cli login prod --refresh-llm

接入外部 LLM

cz-cli agent llm add
cz-cli agent llm add
支持 
clickzetta
clickzetta
、
anthropic
anthropic
、
openai
openai
、
openai-compatible
openai-compatible
、
bedrock
bedrock
、
google
google
、
azure
azure
和 
openrouter
openrouter
等 Provider。

接入 OpenAI：

cz-cli agent llm add my-openai \ --provider openai \ --api-key "$OPENAI_API_KEY"

接入 OpenAI 兼容的企业网关或转发服务：

cz-cli agent llm add my-gateway \ --provider openai-compatible \ --base-url https://your-gateway.example.com/v1 \ --api-key "$LLM_API_KEY"

--base-url
--base-url
应填写网关实际提供的 OpenAI 兼容 API 地址，不要填写控制台页面地址。不要把真实 API Key 写入文档、代码仓库或聊天记录。

验证和管理 LLM

查看当前激活的模型和全部配置：

cz-cli agent llm show

列出所有 LLM 配置：

cz-cli agent llm list

测试指定配置的 API 连通性：

cz-cli agent llm test my-openai

列出指定配置可用的模型：

cz-cli agent llm models my-openai

设置默认模型时，必须使用完整的 

<配置名>/<模型ID>
<配置名>/<模型ID>
：

cz-cli agent llm use my-openai/gpt-4.1

删除某个 LLM 配置：

cz-cli agent llm remove my-openai

完成配置后运行一个简单任务，确认 Agent 可以正常调用模型和 Lakehouse Profile：

cz-cli -p <profile> agent run "先检查连接状态，再列出当前 workspace 中的 schema"

输出格式与自动化

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

表格格式，适合人工阅读

cz-cli -p prod --format table status

CSV 格式，适合导出

cz-cli -p prod --format 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

也可以重新运行安装脚本升级到最新版本：

curl -fsSL https://cz-cli.ai/install.sh | bash

常见问题

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: 如何降低误操作风险？

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

推荐上手路径

  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 mcp init
    cz-cli mcp init
    将 cz-cli 注册到外部 Agent，或配置 LLM 后使用 
    cz-cli agent run
    cz-cli agent run
    。
  7. 与 Agent 约定高风险操作必须人工确认。

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

相关文档

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