cz-cli

AI-Agent-friendly command-line interface for ClickZetta Lakehouse.

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

Features

Multiple Authentication Methods: Profile, PAT, JDBC URL, environment variables, or inline CLI arguments
AI-Friendly: JSON output by default, structured error messages with auto-correction hints
Safety Guardrails: Write protection, dangerous operation blocking, row limits, sensitive data masking
Async SQL Execution: Support for long-running queries with automatic polling
Studio Task Scheduling: Create, configure, publish, and monitor scheduled tasks and flows
Rich Commands: Profile, SQL, workspace, schema, table, task, runs, attempts, agent, and job management
Auto-Update: Standalone binaries check for updates and self-upgrade automatically

Manual Zip Install

Download the zip from GitHub Releases, then run the bundled setup script:

# macOS / Linux
./setup.sh  && source ~/.zshrc

# Windows
setup.bat

Auto-Update

Standalone binaries automatically check GitHub Releases for newer versions after each command (throttled to once per 4 hours). Updates are downloaded and installed via install.sh.

Disable auto-update:

# Environment variable
export CZ_SKIP_UPDATE=1

# Or in state file (~/.clickzetta/.update_state.json)
{"skip_update": true}

Build Standalone Binaries (PyInstaller)

Use PyInstaller to build a standalone executable that can run on target machines without installing Python packages.

Install build dependencies on the build machine:

pip install -r requirement.txt

Build standalone binaries (single or multi-version):

make build-fat

Default behavior uses version from cz_cli/version.py.

Output layout:

dist/<version>/<platform-arch>/cz-cli
Windows output name remains cz-cli.exe

Notes:

Default targets: linux-x86_64 windows-x86_64 windows-arm64 macos-x86_64 macos-arm64.
Targets that cannot be built on the current host are skipped by default. Set CZ_FAIL_ON_SKIP=1 to fail instead.
During multi-version build, cz_cli/version.py is updated per version and automatically restored when done.
For true multi-OS release in one shot, use GitHub Actions matrix build (Linux/Windows/macOS runners) via .github/workflows/build-fat-binaries.yml.
Build-time performance knobs for PyInstaller spec:
- CZ_PYI_BUNDLE_MODE=onedir|onefile (default onedir) controls bundle mode; onedir has the fastest startup.
- CZ_PYI_OPTIMIZE=0|1|2 (default 1) controls Python bytecode optimization level.
- CZ_PYI_OPTIMIZE=2 may break numpy/pyarrow import in frozen binaries; prefer 1 for production.
- CZ_PYI_STRIP=true|false (default true on non-Windows, false on Windows) controls binary strip.
- CZ_PYI_RUNTIME_TMPDIR=/abs/path pins onefile extraction base directory (onefile mode only).
- In onefile mode, if CZ_PYI_RUNTIME_TMPDIR is not set, build script default is ${CLICKZETTA_HOME}/pyinstall; if CLICKZETTA_HOME is unset, fallback is ~/.clickzetta/pyinstall.
- runtime_tmpdir is baked at build time, so use an absolute path that exists on target machines.

One-shot Multi-OS Release (Recommended)

Push a tag (for example v0.1.0) to trigger matrix build and automatic GitHub Release asset upload:

git tag v0.1.0
git push origin v0.1.0

The workflow will produce and attach:

linux-x86_64/cz-cli
windows-x86_64/cz-cli.exe
windows-arm64/cz-cli.exe
macos-x86_64/cz-cli
macos-arm64/cz-cli

Where to find outputs:

In the GitHub Actions run page: per-job Artifacts section (linux-x86_64, windows-x86_64, windows-arm64, macos-x86_64, macos-arm64).
In GitHub Releases page: the same binaries are attached as release assets for the tag.

Release notes:

The workflow enables auto-generated GitHub Release Notes (generate_release_notes: true), so each tag release gets notes automatically.

Quick Start

1. Create a Profile

# Username/password authentication
cz-cli profile create dev \
  --username your_username \
  --password your_password \
  --service dev-api.clickzetta.com \
  --instance your_instance \
  --workspace your_workspace

# PAT authentication
cz-cli profile create dev \
  --pat your_personal_access_token \
  --service dev-api.clickzetta.com \
  --instance your_instance \
  --workspace your_workspace

2. Test Connection

cz-cli --profile dev status

3. Execute SQL

# Simple query
cz-cli --profile dev sql "SELECT * FROM my_table LIMIT 10"

# From file
cz-cli --profile dev sql -f query.sql

# With variables
cz-cli --profile dev sql -e "SELECT * FROM users WHERE id = %(id)s" --variable id=123

# Async execution
cz-cli --profile dev sql --async "SELECT COUNT(*) FROM large_table"

Configuration

Profile Configuration

Profiles are stored in ~/.clickzetta/profiles.toml (see profiles.toml.example):

default_profile = "dev"

[profiles.dev]
username = "your_username"
password = "your_password"
service = "dev-api.clickzetta.com"
instance = "your_instance"
workspace = "your_workspace"
schema = "public"
vcluster = "default"

[profiles.prod]
pat = "your_personal_access_token"
service = "api.clickzetta.com"
instance = "prod_instance"
workspace = "prod_workspace"
schema = "public"
vcluster = "default"

JDBC URL Format

jdbc:clickzetta://host/instance?username=user&password=pass&workspace=ws&schema=schema&virtualCluster=vc

Example:

cz-cli --jdbc "jdbc:clickzetta://dev-api.clickzetta.com/myinst?username=user&password=pass&workspace=ws" sql "SELECT 1"

Inline Connection Arguments

Connect without a profile by passing credentials directly:

cz-cli --username user --password pass --service dev-api.clickzetta.com \
  --instance myinst --workspace ws sql "SELECT 1"

# Or with PAT
cz-cli --pat your_token --service dev-api.clickzetta.com \
  --instance myinst --workspace ws sql "SELECT 1"

Environment Variables

export CZ_USERNAME=your_username
export CZ_PASSWORD=your_password
export CZ_SERVICE=dev-api.clickzetta.com
export CZ_PROTOCOL=https
export CZ_INSTANCE=your_instance
export CZ_WORKSPACE=your_workspace
export CZ_SCHEMA=public
export CZ_VCLUSTER=default

cz-cli sql "SELECT 1"

Commands

AI Skills Installation

# Install AI skills for coding assistants (interactive)
cz-cli install-skills

# Install to global skills directory non-interactively
cz-cli install-skills -g -y

This command provides an interactive installer to add bundled skills (from cz_cli/skills and cz_mcp/skills) to your AI coding assistant:

Supports Claude Code, OpenClaw, Cursor, Codex, and more
Interactive selection of tools and skills
Automatic installation to the correct directory

Profile Management

# List profiles
cz-cli profile list

# Show a single profile
cz-cli profile detail <name>

# Create profile (username/password)
cz-cli profile create <name> --username <user> --password <pass> \
  --service <host> --instance <inst> --workspace <ws>

# Create profile (PAT)
cz-cli profile create <name> --pat <token> \
  --service <host> --instance <inst> --workspace <ws>

# Create profile with custom headers and skip verification
cz-cli profile create <name> --pat <token> --service <host> \
  --instance <inst> --workspace <ws> --header "X-Custom=value" --skip-verify

# Update profile
cz-cli profile update <name> <key> <value>

# Delete profile
cz-cli profile delete <name>

# Set default profile
cz-cli profile use <name>

# Discover regions/instances from a Studio URL
cz-cli profile discover --studio-url <url> --username <user> --password <pass>

# List workspaces for an instance
cz-cli profile list-workspaces --studio-url <url> --username <user> --password <pass>

# Render a ready-to-use profile create command
cz-cli profile render-command --studio-url <url> --username <user> --password <pass>

SQL Execution

# Execute SQL
cz-cli sql "SELECT * FROM table LIMIT 10"
cz-cli sql -e "SELECT 1"
cz-cli sql -f query.sql

# Write operations (require --write flag)
cz-cli sql --write "INSERT INTO table VALUES (1, 'test')"

# Async execution
cz-cli sql --async "SELECT COUNT(*) FROM large_table"

# With timeout
cz-cli sql --timeout 60 "SELECT * FROM table"

# With variables (pyformat style)
cz-cli sql -e "SELECT * FROM users WHERE id = %(id)s" --variable id=123

# Set ClickZetta SQL flags
cz-cli sql --set cz.sql.result.row.partial.limit=200 "SELECT * FROM large_table"
cz-cli sql --set sdk.job.timeout=60 --set cz.sql.adhoc.result.type=ARROW "SELECT * FROM table"

# Get job profile
cz-cli sql --job-profile <job_id>

# Check job status
cz-cli sql status <job_id>

# Short options
cz-cli sql -e "SELECT 1"  # --execute
cz-cli sql -f query.sql   # --file
cz-cli sql -N "SELECT 1"  # --no-header
cz-cli sql -B "SELECT 1"  # --batch (tab-separated)

Workspace Management

# Show current workspace
cz-cli workspace current

# Switch workspace
cz-cli workspace use <name>

# Switch and persist to profile
cz-cli workspace use <name> --persist

Schema Management

# List schemas
cz-cli schema list
cz-cli schema list --like 'test%'

# Describe schema
cz-cli schema describe <name>

# Create schema
cz-cli schema create <name>

# Drop schema
cz-cli schema drop <name>

Table Management

# List tables
cz-cli table list
cz-cli table list --schema public
cz-cli table list --like 'user%'

# Describe table
cz-cli table describe <name>

# Preview data
cz-cli table preview <name>
cz-cli table preview <name> --limit 20

# Table statistics
cz-cli table stats <name>

# Table history (including deleted)
cz-cli table history
cz-cli table history <name>

# Create table
cz-cli table create "CREATE TABLE test (id INT, name STRING)"
cz-cli table create --from-file schema.sql

# Drop table
cz-cli table drop <name>

Task Management (Studio)

Manage Studio scheduled tasks. Task type must be specified explicitly via --type (SQL, PYTHON, SHELL, SPARK, or FLOW).

# List task folders
cz-cli task list-folders

# Create a task folder
cz-cli task create-folder "my_folder"

# Create a task (type is required)
cz-cli task create my_task --type SQL --folder my_folder

# List tasks
cz-cli task list
cz-cli task list --page 2 --page-size 20

# Get task content (draft)
cz-cli task content <task_name_or_id>

# Save task script content (draft only, does NOT publish)
cz-cli task save-content <task_name_or_id> --file script.sql
cz-cli task save-content <task_name_or_id> --content "SELECT 1"

# Save schedule configuration (draft only, does NOT publish)
cz-cli task save-config <task_name_or_id> --cron "0 8 * * *"

# View task dependencies (draft)
cz-cli task deps <task_name_or_id>

# Execute task immediately (ad-hoc, requires user confirmation)
cz-cli task execute <task_name_or_id>

# Publish task to activate scheduling (requires confirmation)
cz-cli task online <task_name_or_id> -y

# Take task offline (IRREVERSIBLE — clears all run instances)
cz-cli task offline <task_name_or_id> -y

Flow Subcommands

# View flow DAG
cz-cli task flow dag <flow_task>

# Create / remove flow nodes
cz-cli task flow create-node <flow_task> --node-name <name> --task-id <id>
cz-cli task flow remove-node <flow_task> --node-name <name>

# Bind / unbind node dependencies
cz-cli task flow bind <flow_task> --from <node> --to <node>
cz-cli task flow unbind <flow_task> --dependency-id <id>

# Node detail / save / save-config
cz-cli task flow node-detail <flow_task> --node-name <name>
cz-cli task flow node-save <flow_task> --node-name <name> --file script.sql
cz-cli task flow node-save-config <flow_task> --node-name <name> --cron "0 8 * * *"

# Submit flow
cz-cli task flow submit <flow_task>

# List flow instances
cz-cli task flow instances <flow_task>

Runs Management (Studio)

Manage task run instances (scheduled, temporary, and backfill).

# List runs (defaults to SCHEDULE type, last 24h)
cz-cli runs list
cz-cli runs list --task my_task --status FAILED
cz-cli runs list --run-type REFILL --from 2026-04-01 --to 2026-04-07

# Get run detail
cz-cli runs detail <run_id_or_task_name>

# Wait for a run to complete
cz-cli runs wait <run_id_or_task_name> --timeout 300

# Get run logs
cz-cli runs logs <run_id_or_task_name>

# View run dependencies (published)
cz-cli runs deps <run_id_or_task_name>

# Stop a running instance
cz-cli runs stop <run_id_or_task_name> -y

# Run statistics summary
cz-cli runs stats --from 2026-04-01 --to 2026-04-07

# Submit a backfill (requires confirmation)
cz-cli runs refill <task_name_or_id> --from 2026-04-01 --to 2026-04-03

Attempts Management (Studio)

View attempt records and logs for task runs.

# List attempts for a run
cz-cli attempts list <run_id_or_task_name>

# Get attempt log
cz-cli attempts log <run_id_or_task_name>
cz-cli attempts log <run_id_or_task_name> --attempt-id 3

Agent (AI Agent)

Interact with ClickZetta Studio AI Agent via HTTP.

# Check agent health
cz-cli agent status

# Ask the agent a question
cz-cli agent ask "How many tables are in my schema?"

# Multi-turn conversation
cz-cli agent ask "List all tables" --conversation-id <id>

Job

Check SQL job status and performance.

# Check job status
cz-cli job status <job_id>

Global Options

--profile, -p       Profile name from ~/.clickzetta/profiles.toml
--jdbc              JDBC connection URL
--pat               Personal Access Token (PAT)
--username          Username (inline connection)
--password          Password (inline connection)
--service           Service endpoint (inline connection)
--protocol          Protocol: https or http (inline connection)
--instance          Instance name (inline connection)
--workspace         Workspace name (inline connection)
--schema, -s        Default schema
--vcluster, -v      Virtual cluster
--output, -o        Output format (json|pretty|table|csv|jsonl|toon)
--debug, -d         Enable debug mode
--silent            Suppress non-essential output
--verbose           Verbose output
--version           Show version

Breaking change: The --format/-f global option has been removed. Use --output/-o instead. The -f shorthand is now consistently --file on commands that use it (e.g., sql -f query.sql).

Safety Features

Write Protection

Write operations (INSERT, UPDATE, DELETE, etc.) require the --write flag:

cz-cli sql --write "DELETE FROM table WHERE id = 1"

Dangerous Operation Blocking

DELETE/UPDATE without WHERE clause are blocked:

# This will be rejected
cz-cli sql --write "DELETE FROM table"

# This is allowed
cz-cli sql --write "DELETE FROM table WHERE id = 1"

Row Limit Protection

Queries without LIMIT are automatically limited to 100 rows via SET cz.sql.result.row.partial.limit=100.

Sensitive Data Masking

Sensitive fields are automatically masked in output:

Phone numbers: 138****5678
Emails: u***@example.com
Passwords: ******
ID cards: 110****1234

Operation Logging

All operations are logged to ~/.clickzetta/sql-history.jsonl with sensitive data redacted.

Error Auto-Correction

When errors occur, the CLI provides helpful hints:

{
  "ok": false,
  "error": {
    "code": "SQL_ERROR",
    "message": "Column 'name' not found",
    "schema": {
      "table": "users",
      "columns": ["id", "username", "email", "created_at"]
    }
  }
}

Output Formats

JSON (default)

cz-cli sql "SELECT * FROM users LIMIT 2"

{
  "ok": true,
  "columns": ["id", "name", "email"],
  "rows": [
    {"id": 1, "name": "Alice", "email": "[email protected]"},
    {"id": 2, "name": "Bob", "email": "[email protected]"}
  ],
  "count": 2,
  "affected": 0,
  "time_ms": 123,
  "job_id": "2026033120245406019496708"
}

Pretty

cz-cli --output pretty sql "SELECT * FROM users LIMIT 2"

Pretty-printed JSON with indentation and syntax highlighting.

TOON (LLM-optimized)

cz-cli --output toon sql "SELECT * FROM users LIMIT 2"

ok: true
columns[2]: id,name,email
rows[2]{id,name,email}:
  1,Alice,[email protected]
  2,Bob,[email protected]
count: 2
affected: 0
time_ms: 123
job_id: "2026033120245406019496708"

TOON (Token-Oriented Object Notation) achieves 30-60% fewer tokens than JSON, making it ideal for LLM contexts.

Table

cz-cli --output table sql "SELECT * FROM users LIMIT 2"

+----+-------+-------------------+
| id | name  | email             |
+----+-------+-------------------+
|  1 | Alice | [email protected] |
|  2 | Bob   | [email protected]   |
+----+-------+-------------------+

CSV

cz-cli --output csv sql "SELECT * FROM users LIMIT 2"

id,name,email
1,Alice,[email protected]
2,Bob,[email protected]

JSONL

cz-cli --output jsonl sql "SELECT * FROM users LIMIT 2"

One JSON object per line — useful for streaming and log pipelines.

AI Agent Guide

Get structured usage guide for AI agents:

cz-cli ai-guide

This outputs a comprehensive guide (toon format by default) with all commands, safety rules, and examples. Use --format json for raw JSON.

Development

Run Tests

# Unit tests only
make test-unit

# Unit + integration tests (default)
make test

# Integration tests only (profile defaults to dev)
make test-integration

# Integration tests against standalone binary
CZ_CLI_BIN=/path/to/cz-cli make test-integration-bin

# Integration tests with debug logs (default behavior)
CZ_IT_DEBUG=1 make test-integration

Install Development Dependencies

pip install -e ".[dev]"

License

Apache-2.0

Support

For issues and questions, please visit [repository URL].

Name		Name	Last commit message	Last commit date
Latest commit History 48 Commits
.claude		.claude
.codex/skills		.codex/skills
.github/workflows		.github/workflows
.kiro		.kiro
cz_cli		cz_cli
openspec		openspec
pyinstaller		pyinstaller
scripts		scripts
tests		tests
tmp/volume_multi_test		tmp/volume_multi_test
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
LICENSE		LICENSE
MANIFEST.in		MANIFEST.in
Makefile		Makefile
README.md		README.md
cz-fs-design.md		cz-fs-design.md
profiles.toml.example		profiles.toml.example
pyproject.toml		pyproject.toml
requirement.txt		requirement.txt

Folders and files

Latest commit

History

Repository files navigation

cz-cli

Features

Manual Zip Install

Auto-Update

Build Standalone Binaries (PyInstaller)

One-shot Multi-OS Release (Recommended)

Quick Start

1. Create a Profile

2. Test Connection

3. Execute SQL

Configuration

Profile Configuration

JDBC URL Format

Inline Connection Arguments

Environment Variables

Commands

AI Skills Installation

Profile Management

SQL Execution

Workspace Management

Schema Management

Table Management

Task Management (Studio)

Flow Subcommands

Runs Management (Studio)

Attempts Management (Studio)

Agent (AI Agent)

Job

Global Options

Safety Features

Write Protection

Dangerous Operation Blocking

Row Limit Protection

Sensitive Data Masking

Operation Logging

Error Auto-Correction

Output Formats

JSON (default)

Pretty

TOON (LLM-optimized)

Table

CSV

JSONL

AI Agent Guide

Development

Run Tests

Install Development Dependencies

License

Support

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 11

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages