@clickzetta/cz-cli-darwin-arm64 0.3.78 → 0.3.81

package/bin/skills/cz-cli/SKILL.md

@@ -1,311 +0,0 @@
----
-name: cz-cli
-description: "Route ALL ClickZetta Lakehouse operations to cz-cli: SQL, Studio tasks, tables, pipelines, profiles. Use when user mentions ClickZetta, Lakehouse, cz-cli, or needs profile/connection lakehouse configuration."
----
-
-# cz-cli — ClickZetta Lakehouse Subagent
-
-You have no direct Lakehouse access. Always delegate via cz-cli.
-
-## Capabilities
-
-### SQL & Data Operations
-- Execute any SQL against Lakehouse: SELECT, DDL (CREATE/ALTER/DROP TABLE, SCHEMA, VIEW), DML (INSERT, UPDATE, DELETE, MERGE INTO)
-- Run async jobs and fetch results
-- Preview table data and row counts
-
-### Table & Schema Management
-- List, describe, create, and drop tables and schemas
-- View table history, indexes, partitions, and statistics
-- Add or update column/table comments
-- Create Dynamic Tables for auto-incremental ETL (ODS→DWD→DWS pipelines)
-- Create Materialized Views for pre-computed aggregations
-- Create Table Streams to capture INSERT/UPDATE/DELETE changes for CDC UPSERT
-
-### Studio Task Management
-- Create, configure, deploy, and delete Studio tasks (SQL, Shell, Python, integration, flow)
-- Save task content and cron schedule
-- Deploy, undeploy, and execute tasks ad-hoc
-- Monitor run instances: list, detail, wait, logs, stop, rerun, backfill
-- View run statistics and dependencies
-
-### Data Sync Pipelines
-- Create single-table realtime CDC sync tasks (MySQL/PostgreSQL/SQL Server → Lakehouse, task_type=28)
-- Create multi-table or whole-database CDC sync tasks — mirror, merge, or sharded-table consolidation (task_type=281)
-- Create offline batch sync tasks with Cron scheduling — single-table (task_type=10) or multi-table (task_type=291)
-- Manage sync task lifecycle: start, stop, offline, backfill, add tables, re-sync individual tables
-
-### Data Ingestion Pipelines
-- Create continuous OSS/S3/COS ingest PIPE (LIST_PURGE scan mode or EVENT_NOTIFICATION mode)
-- Create continuous Kafka ingest PIPE using READ_KAFKA function
-- One-shot file import from URL, local path, or Volume (COPY INTO)
-- Manage PIPE lifecycle: pause, resume, adjust batch interval, view load history
-
-### Data Recovery
-- Query data at a historical point in time (Time Travel: TIMESTAMP AS OF)
-- Roll back a table to a previous version (RESTORE TABLE)
-- Recover accidentally dropped tables, dynamic tables, or materialized views (UNDROP TABLE)
-- Inspect change history (DESC HISTORY) and deleted objects (SHOW TABLES HISTORY)
-- Configure retention: data_retention_days, data_lifecycle
-
-### Connection & Environment Management
-- Create, update, delete, and switch connection profiles (multi-cloud, multi-region)
-- Check connection status and switch workspace
-- List and test external data sources, browse catalogs and objects
-- Generate Python SDK / ZettaPark / SQLAlchemy / JDBC connection code from profile parameters
-
-## Route to cz-cli
-
-- SQL against Lakehouse (SELECT, DDL, DML)
-- Studio task development, scheduling, monitoring
-- Data pipelines (sync, import, CDC, streaming)
-- Profile and connection configuration
-- Performance analysis and optimization
-
-## Keep in host agent
-
-- General programming unrelated to ClickZetta
-- Local file operations, git
-- Non-ClickZetta databases (PostgreSQL, MySQL standalone)
-
-## Execution strategy
-
-**MANDATORY: Follow this order every time. No exceptions.**
-
-**Step 1 — MUST check LLM first:**
-
-```bash
-cz-cli agent llm show
-```
-
-**Step 2 — If active LLM is configured (kind != "none"), you MUST use agent run:**
-
-```bash
-cz-cli agent run "<request>" --format a2a --dangerously-skip-permissions
-```
-
-Do NOT use direct cz-cli subcommands when an active LLM is available. Always delegate the full request to `cz-cli agent run`.
-
-The output includes a `session_id`. Use it to inspect the run:
-- `cz-cli agent session status <session_id>` — current state (`busy`/`retry` with `progress`, `idle` with `result`, or `error`)
-- `cz-cli agent export <session_id>` — full conversation (messages, tool calls, reasoning, text). Wait until `status` is `idle` before exporting; otherwise the conversation may still be in progress.
-
-**Step 3 — ONLY if no active LLM (kind: "none" or empty list), fall back to direct commands:**
-
-Decompose the request into concrete `cz-cli` subcommands (`sql`, `schema`, `table`, `task`, `runs`, `job`, `datasource`, `profile`, etc.), execute them, and synthesize the result.
-
-Use direct commands for local setup and diagnostics even when agent path is available: `cz-cli profile ...`, `cz-cli -p <profile> status`, `cz-cli agent llm ...`, `cz-cli --help`.
-
-With session continuity:
-
-```bash
-cz-cli agent run "<request>" --format a2a --dangerously-skip-permissions --session <session_id>
-```
-
-Reuse `session_id` for follow-ups on the same topic. Omit `--session` to start fresh.
-
-## Async mode (non-TTY / long-running tasks)
-
-When running in non-TTY environments (e.g. as a subagent from Claude Code) or for long-running tasks, use async mode to avoid blocking:
-
-### Submit asynchronously
-
-```bash
-cz-cli agent run "<request>" --async --format a2a --dangerously-skip-permissions
-```
-
-Returns immediately with a session ID:
-```json
-{"session_id": "01JXF3K...", "status": "running", "message": "Session submitted asynchronously"}
-```
-
-Note: In non-TTY with `--format a2a` or `--format json`, async mode activates automatically (no `--async` flag needed).
-
-### Poll status
-
-```bash
-cz-cli agent session status <session_id>
-```
-
-While running:
-```json
-{"session_id": "01JXF3K...", "status": "busy", "progress": "$ cz-cli table list -o table"}
-```
-
-Other progress examples you may see during polling:
-- `"💭 Thinking..."` — LLM is reasoning
-- `"✏ Generating response..."` — LLM is writing the reply
-- `"✱ Grep \"error\" · 3 matches"` — running a search tool
-- `"↻ Retry (attempt 2)"` — retrying a failed LLM call (paired with a `retry` field describing the reason)
-
-When complete:
-```json
-{"session_id": "01JXF3K...", "status": "idle", "result": "Here are the results:\n..."}
-```
-
-The `result` field is the final text reply. For full conversation details (thinking, tool calls, intermediate text), use `cz-cli agent export <session_id>`.
-
-If the session does not exist:
-```json
-{"session_id": "ses_invalid", "error": "Session not found"}
-```
-(exits with code 1)
-
-### Retrieve full conversation (thinking + tool calls + text)
-
-```bash
-cz-cli agent export <session_id>
-```
-
-Returns complete session with all message parts:
-```json
-{
-  "info": { "id": "...", "title": "...", "time": {...} },
-  "messages": [
-    {
-      "info": { "role": "user" },
-      "parts": [{ "type": "text", "text": "original prompt" }]
-    },
-    {
-      "info": { "role": "assistant" },
-      "parts": [
-        { "type": "reasoning", "text": "thinking content..." },
-        { "type": "tool", "tool": "bash", "state": { "status": "completed", "input": {...}, "output": "..." } },
-        { "type": "text", "text": "final answer..." }
-      ]
-    }
-  ]
-}
-```
-
-Part types in export:
-- `reasoning` — LLM thinking/reasoning blocks
-- `tool` — tool calls with full input/output (bash, read, write, edit, glob, grep, etc.)
-- `text` — final text response
-- `step-start` / `step-finish` — step boundaries
-- `patch` — code diffs
-- `subtask` — delegated sub-tasks
-
-### Async workflow pattern
-
-```bash
-# 1. Submit
-SESSION=$(cz-cli agent run "complex analysis" --async --format a2a --dangerously-skip-permissions | jq -r '.session_id')
-
-# 2. Poll until done, printing progress along the way
-while true; do
-  STATUS=$(cz-cli agent session status $SESSION)
-  STATE=$(echo "$STATUS" | jq -r '.status')
-  if [ "$STATE" = "idle" ]; then
-    echo "$STATUS" | jq -r '.result'
-    break
-  fi
-  echo "$STATUS" | jq -r '.progress // empty'
-  sleep 5
-done
-
-# Need full conversation (thinking + tool calls)?
-cz-cli agent export $SESSION
-```
-
-### With session continuity (async)
-
-```bash
-# First turn
-SESSION=$(cz-cli agent run "describe sales table" --async --format a2a --dangerously-skip-permissions | jq -r '.session_id')
-# ... wait for completion ...
-
-# Follow-up turn on same session
-cz-cli agent run "now show row counts" --async --format a2a --dangerously-skip-permissions --session $SESSION
-```
-
-### Important notes for async mode
-
-- **Permissions:** Always use `--dangerously-skip-permissions` — async mode cannot handle interactive permission prompts
-- **Server requirement:** An agent runtime server must be running (or will be started automatically)
-- **Error handling:** If session is already busy, returns `{"error": "session busy"}`
-
-## Multi-environment (profiles)
-
-When the user specifies an environment or profile (e.g. "use uat_test", "on the test instance"):
-
-```bash
-cz-cli agent run "<request>" --profile uat_test --format a2a --dangerously-skip-permissions
-```
-
-Available profiles: read `~/.clickzetta/profiles.toml` or run `cz-cli profile list`.
-
-## Adding a new profile
-
-**Trigger conditions:** User says "configure new environment", "add profile", "can't connect", mentions an unknown profile name, or provides connection credentials.
-
-### Step 1 — Collect information (guided Q&A)
-
-If all required fields are already provided, skip directly to Step 2.
-
-Otherwise, ask for missing ones. Accept all at once or prompt one by one.
-
-**Required fields:**
-
-| Field | Question to ask | Example |
-|-------|----------------|---------|
-| `service` | Which cloud region? (see table below, or provide the service endpoint directly) | `cn-shanghai-alicloud.api.clickzetta.com` |
-| `instance` | What is the instance name? | `billingsh` |
-| `workspace` | What is the workspace name? | `meter_n_bill` |
-| `username` | What is the username? | `billing_admin` |
-| `password` | What is the password? | — |
-| `name` | What should this profile be named? (suggested format below) | `billingsh` |
-
-**Common service endpoints (offer as options):**
-
-| Region | service | Suggested profile prefix |
-|--------|---------|--------------------------|
-| Alibaba Cloud East China 2 (Shanghai) | `cn-shanghai-alicloud.api.clickzetta.com` | `cn-shanghai` |
-| Tencent Cloud East China (Shanghai) | `ap-shanghai-tencentcloud.api.clickzetta.com` | `ap-shanghai` |
-| Tencent Cloud North China (Beijing) | `ap-beijing-tencentcloud.api.clickzetta.com` | `ap-beijing` |
-| Tencent Cloud South China (Guangzhou) | `ap-guangzhou-tencentcloud.api.clickzetta.com` | `ap-guangzhou` |
-| AWS China (Beijing) | `cn-north-1-aws.api.clickzetta.com` | `cn-north-1` |
-
-**Inference rules (reduce unnecessary questions):**
-- If the user describes a cloud region in natural language (e.g. "Alibaba Cloud Shanghai", "Tencent Cloud Beijing", "阿里云上海", "腾讯云北京"), look up the service endpoint from the table above — do NOT ask the user to provide it again.
-- If the user hasn't provided a profile name, suggest `<prefix>-<instance>` using the prefix from the table (e.g. `cn-shanghai-billingsh`). Confirm with the user or proceed if they don't object.
-
-### Step 2 — Create profile
-
-Run `cz-cli profile create` with all collected fields:
-
-```bash
-cz-cli profile create <name> \
-  --username <username> \
-  --password <password> \
-  --instance <instance> \
-  --workspace <workspace> \
-  --service <service> \
-  --schema public \
-  --vcluster default
-```
-
-### Step 3 — Verify connection
-
-After creating, run:
-
-```bash
-cz-cli status --profile <name>
-```
-
-A successful response looks like:
-```json
-{"data": {"connected": true, "workspace": "...", "time_ms": ...}}
-```
-
-If it fails, report the error and ask the user to double-check credentials or service endpoint.
-
-## Error handling
-
-All errors in non-TTY mode output JSON to stdout:
-
-```json
-{"ok": false, "error": "NO_PROFILE", "next_steps": ["cz-cli setup --credential <base64>"]}
-```
-
-On `NO_PROFILE` error: check if a profile can be configured via username/password (see "Adding a new profile" above). If the user has a base64 credential instead, guide them to run `cz-cli setup --credential <base64>`. See `references/profile-setup.md`.

package/bin/skills/cz-cli/references/profile-setup.md

@@ -1,120 +0,0 @@
-# Profile Setup — Connection Onboarding Guide
-
-Use this reference when any command returns error code `NO_PROFILE`.
-
-## Preferred: `cz-cli setup`
-
-The recommended first-time onboarding entry point:
-
-```
-cz-cli setup --credential "<base64_string>"
-```
-
-Or interactive (TTY only):
-
-```
-cz-cli setup
-```
-
-For AI agents (non-TTY), always pass `--credential`. Without it, the command outputs JSON with registration URLs and exits 1.
-
-## What setup does
-
-Writes two files:
-- `~/.clickzetta/profiles.toml` — connection profile (`[profiles.default]`)
-- `~/.local/share/clickzetta/auth.json` — API key
-
-## Profile management
-
-List profiles (forwarded to cz-tool):
-```
-cz-cli profile list
-```
-
-All `cz-cli profile *` subcommands are forwarded to the `cz-tool` binary at `~/.clickzetta/cz-tool/cz-tool`.
-
-## LLM configuration
-
-After setup, the ClickZetta built-in LLM is used by default. To use a different LLM:
-
-```bash
-# Add and select Claude
-cz-cli agent llm add my-claude --provider anthropic --api-key sk-ant-... --use
-
-# Add OpenAI
-cz-cli agent llm add my-openai --provider openai --api-key sk-...
-
-# Check what's active
-cz-cli agent llm show
-
-# Switch between configured LLMs
-cz-cli agent llm use my-claude
-
-# Fall back to ClickZetta built-in
-cz-cli agent llm reset
-
-# Full help
-cz-cli agent llm --help
-```
-
-Supported providers: `anthropic`, `openai`, `openai-compatible`, `bedrock`, `google`, `azure`
-
-For `openai-compatible` (third-party relays), add `--base-url <url>`.
-
-## Error JSON reference
-
-```json
-// No profile at all
-{"ok": false, "error": "NO_PROFILE", "profile_exists": false,
- "next_steps": ["cz-cli setup --credential <base64>"],
- "register_urls": ["https://accounts.clickzetta.com/register?ref=cz-cli"]}
-
-// Profile exists but no api_key, has llm entries
-{"ok": false, "error": "NO_PROFILE", "profile_exists": true, "has_llm_entry": true,
- "next_steps": ["cz-cli agent llm show", "cz-cli agent llm add <name> --provider <p> --api-key <k> --use"]}
-
-// Profile exists but no api_key, no llm entries
-{"ok": false, "error": "NO_PROFILE", "profile_exists": true, "has_llm_entry": false,
- "next_steps": ["cz-cli setup --credential <base64>", "cz-cli agent llm add my-claude --provider anthropic --api-key <key> --use"],
- "supported_providers": ["anthropic", "openai", "openai-compatible", "bedrock", "google", "azure"]}
-```
-
-## Alternative: username/password profile (no credential required)
-
-If the user has an existing instance account (username + password) but no base64 credential, use `cz-cli profile create` directly:
-
-```bash
-cz-cli profile create <name> \
-  --username <username> \
-  --password <password> \
-  --instance <instance_name> \
-  --workspace <workspace_name> \
-  --service <service_host> \
-  --schema public \
-  --vcluster default
-```
-
-**Common service endpoints:**
-
-| 云区域 | service |
-|--------|---------|
-| 阿里云 华东2（上海） | `cn-shanghai-alicloud.api.clickzetta.com` |
-| 腾讯云 华东（上海） | `ap-shanghai-tencentcloud.api.clickzetta.com` |
-| 腾讯云 华北（北京） | `ap-beijing-tencentcloud.api.clickzetta.com` |
-| 腾讯云 华南（广州） | `ap-guangzhou-tencentcloud.api.clickzetta.com` |
-| AWS 中国（北京） | `cn-north-1-aws.api.clickzetta.com` |
-
-After creating, verify with:
-```bash
-cz-cli status --profile <name>
-```
-
-Note: `profile discover` / `list-workspaces` / `render-command` require a Studio page URL (`https://<instance>.accounts.clickzetta.com`) and are not usable when only a service endpoint + credentials are available.
-
-## Step-by-step: no credential available
-
-If the user doesn't have a base64 credential, guide them to:
-
-1. Register at `https://accounts.clickzetta.com/register?ref=cz-cli` (China) or `https://accounts.singdata.com/register?ref=cz-cli` (International)
-2. Copy the credential string from the registration page
-3. Run `cz-cli setup --credential "<base64_string>"`