ClickZetta Lakehouse · AI Agent CLI

让 AI Agent
真正操作数仓

Give AI Agents
Warehouse Access

cz-cli 是面向 ClickZetta Lakehouse 的 AI Agent CLI，让 Codex、Claude Code、Cursor、Gemini CLI 等 AI 工具通过自然语言安全地查询、开发和运维数仓。

cz-cli is an AI Agent CLI for ClickZetta Lakehouse — enabling tools like Codex, Claude Code, Cursor, and Gemini CLI to query, build, and operate your warehouse through natural language.

GitHub 数仓 SkillsWarehouse Skills

terminal

# 安装# Install
$ curl -fsSL https://cz-cli.ai/install.sh | bash

# 配置连接# Configure profile
$ cz-cli setup

# 让 AI Agent 操作数仓# Let your AI agent query
$ cz-cli -p prod agent run "帮我检查今天失败的调度任务，并按失败原因分类""Check today's failed tasks and group by failure reason"
✓ Connected to prod · workspace: my_workspace
→ 正在查询失败任务 ...→ Querying failed tasks ...
        

# 安装 (PowerShell)# Install (PowerShell)
PS> irm https://cz-cli.ai/install.ps1 | iex

# 配置连接# Configure profile
PS> cz-cli setup

# 让 AI Agent 操作数仓# Let your AI agent query
PS> cz-cli -p prod agent run "帮我检查今天失败的调度任务，并按失败原因分类""Check today's failed tasks and group by failure reason"
✓ Connected to prod · workspace: my_workspace
→ 正在查询失败任务 ...→ Querying failed tasks ...
        

为什么需要 cz-cliWhy cz-cli

让 AI Agent 不止会写 SQL，
而是真的会操作数仓

Give AI agents a controlled way
to understand your warehouse

告别把表结构、SQL 错误、任务日志复制粘贴给 AI 的流程，让 Agent 直接基于真实 workspace、schema、任务和运行日志回答问题。

Stop copying schema, SQL errors, and task logs into AI tools. Let agents work directly with real workspace context, metadata, task runs, and job profiles.

减少手动复制粘贴

No more copy-paste

不再需要手动把表结构、SQL、错误日志、任务信息复制给 AI，cz-cli 帮 Agent 直接拿到所有上下文。

No more manually pasting schemas, SQL errors, or task logs. cz-cli gives agents direct access to all warehouse context.

减少工具切换

Fewer context switches

减少在 Studio、命令行、文档、AI IDE 之间来回切换，在 AI 工具内完成完整的数仓工作流。

Reduce switching between Studio, CLI, docs, and AI IDE. Complete full warehouse workflows without leaving your AI tool.

基于真实数仓状态

Real warehouse context

AI Agent 基于真实的 workspace、schema、表、任务、运行日志和 job 信息回答问题，而不是猜测。

Agents answer based on real workspace, schema, task runs, and job profiles — not guesses.

可控的 CLI 入口

Controlled execution

将 AI Agent 的操作收敛到可控的 CLI 入口，便于权限管理、审计和自动化，不绕过 ClickZetta 权限体系。

Converge agent operations through a controlled CLI entry point — manageable permissions, auditable actions, no permission bypass.

快速安装Quick Start

三步接入 Lakehouse

Up and running in minutes

安装

Install

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

irm https://cz-cli.ai/install.ps1 | iex

cz-cli --version

配置连接

Configure profile

cz-cli setup

支持：用户名/密码、PAT、CLI Credential、JDBC 连接串

Supports: username/password, PAT, CLI Credential, JDBC connection string

验证并运行

Verify & run

cz-cli -p prod status

多 Profile 管理

Multi-environment Profiles

为不同环境配置独立 profile，生产、测试、开发完全隔离。

Configure isolated profiles for production, staging, and development environments.

prod 生产 · 只读 production · read-only

uat 验收测试 acceptance test

dev 开发 development

Agent 可用能力Agent Capabilities

AI Agent 能做什么

What agents can do

SQL 查询

SQL Queries

执行 SELECT、DDL、DML，支持同步和异步 Job，查看结果和执行计划。

Execute SELECT, DDL, DML. Supports sync and async jobs. View results and execution plans.

cz-cli -p prod sql "..." --sync

Schema & 表管理

Schema & Tables

列出 schema、查看表结构、预览数据、统计行数、查看分区和索引。

List schemas, describe tables, preview data, count rows, view partitions and indexes.

cz-cli -p prod table describe <table>

Studio 任务

Studio Tasks

创建 SQL 任务、保存内容、配置调度、发布、手动执行。

Create SQL tasks, save content, configure schedules, deploy, and run ad-hoc.

cz-cli -p prod task deploy <task>

运行巡检

Run Inspection

查看任务运行记录、运行详情、日志、依赖和失败原因。

View task run history, run details, logs, dependencies, and failure reasons.

cz-cli -p prod runs list --limit 10

Job 诊断

Job Diagnostics

查看 SQL Job 状态、结果和执行 profile，辅助性能分析和故障定位。

Inspect SQL job status, results, and execution profiles to identify bottlenecks.

cz-cli -p prod job status <job_id>

连接管理

Connection Management

创建、切换、验证不同环境的 profile，浏览外部数据源和 catalog。

Create, switch, and verify environment profiles. Browse external data sources and catalogs.

cz-cli profile list

代表命令Example commands
$ cz-cli -p prod status
$ cz-cli -p prod schema list
$ cz-cli -p prod table describe public.orders
$ cz-cli -p prod sql "SELECT ..." --sync
$ cz-cli -p prod runs list --task daily_summary --limit 5
$ cz-cli -p prod agent run "检查失败任务"

示例 WorkflowExample Workflows

复制 Prompt，立即开始

Copy a prompt, start right away

以下 prompt 可直接粘贴给任意 AI Agent。

These prompts can be pasted directly into any AI agent.

环境检查和元数据浏览

Environment check and metadata browse

请使用 <profile> 环境，先确认 cz-cli 连接状态，然后列出当前 workspace 中有哪些 schema，再列出 public schema 下的前 20 张表。

Use the <profile> environment. First check the cz-cli connection status, then list schemas in the current workspace and show the first 20 tables under the public schema.

测试环境建表和验证

Create table in test env and verify

请使用测试环境 <profile>，帮我在 demo schema 下创建一张订单明细表，插入几行测试数据，然后验证能查到数据。执行写操作前请先给出计划并等待我确认。

Use the test <profile>. Create an order detail table under the demo schema, insert a few test rows, and verify the data can be queried. Before any write operation, show me the plan and wait for confirmation.

任务失败诊断

Task failure diagnosis

请使用 <profile> 环境，检查任务 <task_name> 今天是否有失败运行。如果有，请查看运行详情和日志，并给出失败原因与修复建议。

Use the <profile> environment to check whether task <task_name> has failed runs today. If it does, inspect the run details and logs, then summarize the root cause and suggested fix.

SQL Job 性能分析

SQL Job performance analysis

请使用 <profile> 环境，分析 SQL job <job_id> 的执行情况，查看 job 状态、结果和执行 profile，判断是否存在性能瓶颈。

Use the <profile> environment to analyze SQL job <job_id>. Check the job status, result, and execution profile, then identify potential performance bottlenecks.

调度任务巡检

Scheduled task inspection

帮我检查今天失败的调度任务，并按失败原因分类。

Check today's failed scheduled tasks and group them by failure reason.

Recommended system prompt

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

You can use cz-cli to operate ClickZetta Lakehouse. First run cz-cli status to verify the connection. For high-risk actions such as writes, task deployment, backfill, delete, or undeploy, present an execution plan and wait for my confirmation. Read-only queries and inspections can be executed directly. Summarize results in concise tables or bullet points.

安全与权限Security & Permissions

权限可控，操作可审计

Governed access, auditable execution

⚠️

高风险操作建议人工确认

Confirm before high-risk actions

生产环境建议使用最小权限 profile，并对以下操作启用人工确认：

For production, use least-privilege profiles and require confirmation for:

▸SQL 写操作（需显式 --write）SQL writes (requires explicit --write)
▸任务发布和下线Task deploy and undeploy
▸补数和重跑Backfill and rerun
▸删除操作Delete operations

查询和巡检可直接执行

Reads and inspections are safe to run

SELECT、DESC、SHOW、runs list、job status、schema list 等只读操作无需额外确认。

SELECT, DESC, SHOW, runs list, job status, schema list and other read-only operations can run directly without confirmation.

企业能力Enterprise

面向企业数仓运维，
可治理、可审计

Built for enterprise
warehouse operations

权限可控、操作可审计、结果结构化、自动化可治理。

Governed access, auditable execution, structured outputs, and controlled automation.

多环境隔离

Multi-environment isolation

多 profile 管理，支持生产、测试、UAT、开发环境完全隔离，互不影响。

Multi-profile management with isolated prod, staging, UAT, and dev environments — fully separated.

原生权限体系

Native permission system

使用 ClickZetta 原生账号权限体系，支持账号级权限控制，不需要额外授权层。

Uses ClickZetta's native permission system. Account-level access control, no extra authorization layer required.

结构化输出

Structured output

支持 JSON、CSV、table 输出格式，适合自动化脚本和企业机器人集成。

JSON, CSV, and table output formats — suitable for automation scripts and enterprise bot integration.

操作可审计

Auditable operations

所有实际操作仍落在 ClickZetta 账号、任务和 Job 体系中，便于审计和合规管理。

All operations are executed under ClickZetta accounts, tasks, and jobs — traceable and compliant by design.

让 AI Agent真正操作数仓

Give AI AgentsWarehouse Access

让 AI Agent 不止会写 SQL，而是真的会操作数仓

Give AI agents a controlled wayto understand your warehouse