ClickZetta CLI（cz-cli）

cz-cli 是云器 Lakehouse 的命令行操作工具。对人工用户，它让数据开发者在终端里完成查表、跑 SQL、管理任务、查看运行日志等日常操作，无需打开浏览器。对 AI Agent，它提供一套面向数仓业务场景的高层操作接口，让 Agent 用最少的上下文开销完成完整的运维动作。

为什么需要 cz-cli？

Lakehouse 已经有 Studio Web 界面、MCP Server、JDBC、REST API 等多种接入方式，但它们对 AI Agent 各有根本性限制。cz-cli 针对两类核心场景提供差异化价值：

场景一：Agent 直接调用命令（工具调用模式）

Agent 通过

cz-cli

cz-cli

命令完成数仓操作，一条命令对应一个完整业务动作。

其他接口的限制：

接口	核心限制
JDBC / SQL	Agent 必须先注入完整 schema 才能写 SQL，大型数仓 schema 动辄数万 token；没有 schema 则幻觉严重（编造不存在的表名和字段）；Studio 任务状态、运行日志等运维操作完全没有 SQL 接口
REST API	没有统一的接口发现机制，Agent 无法自动知道有哪些 endpoint；即使有 OpenAPI spec，完整规范也是上下文炸弹；一个业务动作需要拼接 3-5 个 API，中间任何一步出错都会静默失败
MCP Server	tool 描述每个约 300-600 tokens，3 个 MCP server 就可能消耗上下文窗口的 70%+；工具数量增加时 Agent 选择准确率显著下降，超过 50 个工具后质量明显劣化
Studio Web 界面	需要模拟浏览器操作，步骤多、状态不稳定，Agent 操作成本高、准确率低

cz-cli 的优势：

自描述可发现：
```
cz-cli --help
```
cz-cli --help
和
```
cz-cli <subcommand> --help
```
cz-cli <subcommand> --help
本身就是自描述的，Agent 随时按需查询，无需预加载任何文档；
```
cz-cli ai-guide
```
cz-cli ai-guide
可生成更精简的任务导向命令参考
业务语义封装：每条命令对应一个完整业务动作，Agent 一步到位，不需要多步组合，不需要处理分页、认证、错误码
覆盖 SQL 之外的能力：Studio 任务管理、运行巡检、补数、数据源浏览，JDBC 完全触达不到
内置护栏：写操作需要
```
--write
```
--write
，高危操作需要
```
-y
```
-y
确认，降低 Agent 误操作风险
结构化输出：默认 JSON，Agent 直接解析，无需处理自然语言或 HTML
无头环境友好：普通进程，无需持久连接，可在 CI/CD、定时脚本、企业机器人里直接调用

场景二：作为专业子 Agent（cz-cli agent 模式）

主 Agent（Claude Code、Cursor、Kiro 等）加载过多技能后会出现两个问题：一是上下文污染——前一个任务积累的信息干扰后续任务的推理；二是注意力分散——工具越多，选错工具的概率越高。

解决方案是 Anthropic 官方推荐的 orchestrator-subagent 模式：主 Agent 负责规划和协调，将专业领域的问题整体委托给专业子 Agent，子 Agent 在独立的干净上下文中完成，结果返回给主 Agent。

cz-cli agent

cz-cli agent

就是数仓运维场景的专业子 Agent：

主 Agent（Claude Code） └─ "检查今天失败的调度任务并给出修复建议" └─ cz-cli agent run "..." ← 独立上下文，专注数仓运维 ├─ runs list / detail / logs └─ 返回结构化结果给主 Agent

Anthropic 的 Research 功能采用同样架构，实测比单 Agent 提升 90.2%，研究时间减少 90%。数仓运维场景（查任务状态、看日志、补数、诊断 SQL）天然适合这种委托模式——任务独立、边界清晰、结果可验证。

命令概览

命令	说明
`cz-cli profile` cz-cli profile	管理连接配置（创建、切换、更新）
`cz-cli status` cz-cli status	验证当前连接是否正常
`cz-cli sql` cz-cli sql	执行 SQL 查询和 DDL/DML
`cz-cli schema` cz-cli schema	查看和管理 Schema
`cz-cli table` cz-cli table	查看表结构、预览数据、统计行数
`cz-cli workspace` cz-cli workspace	查看和切换工作空间
`cz-cli task` cz-cli task	创建、配置、发布和执行 Studio 任务
`cz-cli runs` cz-cli runs	查看任务运行记录、日志、补数、重跑
`cz-cli attempts` cz-cli attempts	查看单次运行的重试记录和日志
`cz-cli job` cz-cli job	SQL Job 性能诊断
`cz-cli datasource` cz-cli datasource	管理外部数据源，浏览数据源中的对象
`cz-cli agent` cz-cli agent	(Agent 专用) 启动 AI Agent 会话，配置 LLM，自然语言操作 Lakehouse
`cz-cli ai-guide` cz-cli ai-guide	(Agent 专用) 生成精简命令参考，供 Agent 加载使用

快速开始

# 安装 npm install -g @clickzetta/cz-cli # 配置连接 cz-cli setup --credential <CLI连接串> # 验证连接 cz-cli status # 执行查询 cz-cli sql "SELECT current_timestamp()" --sync

详细安装和配置步骤见安装配置指南。

适用场景

场景	推荐方式
日常数据查询、查表结构、看样例数据	`cz-cli sql` cz-cli sql / `cz-cli table` cz-cli table
管理和调试 Studio 任务、查看运行日志	`cz-cli task` cz-cli task / `cz-cli runs` cz-cli runs
CI/CD 流水线中自动化执行 DDL 或任务	cz-cli 命令 + `--write` --write
AI Agent 执行数仓运维操作	cz-cli 工具调用模式
AI Agent 处理复杂数仓运维任务	`cz-cli agent run` cz-cli agent run 子 Agent 模式
可视化配置数据同步、复杂任务编排	Studio Web 界面