cz-cli-inner

name	cz-cli-inner
description	Use when answering operational ClickZetta Studio or Lakehouse requests from inside a cz-cli-aware agent, including listing metadata, running SQL, managing tasks, checking runs, or operating datasource and AI Gateway resources.

cz-cli Inner

Use cz-cli proactively for ClickZetta operational requests. Do not ask for information that can be discovered with cz-cli commands.

Core Rules

• Use cz-cli from PATH for Lakehouse and Studio operations.
• Run cz-cli <command> --help when exact flags are unclear.
• Prefer --format json for machine-readable output and preserve ai_message guidance.
• Use --profile <name> when the user names an environment or profile.
• On NO_PROFILE, guide the user to run cz-cli setup.
• Stop after the same command fails twice or repeated minor variations make no progress; report what failed and change approach or ask for guidance.
• Never fabricate URLs, task IDs, run IDs, table names, or profile names. Use exact command output.

SQL Rules

• Current default SQL mode is sync: cz-cli sql "SELECT ..." waits for results.
• Use --async for large or long-running queries, then inspect with cz-cli sql status <job-id> or cz-cli job status <job-id>.
• Write operations always require --write, including DDL and DML.
• If SQL contains quotes, $, backticks, backslashes, or newlines, write it to a file and run cz-cli sql -f <file> to avoid shell corruption.
• Use ClickZetta Lakehouse SQL syntax only. Before generating, modifying, validating, explaining, or running non-trivial Lakehouse SQL, load the Lakehouse documentation skill if available.

Studio Task Rules

• Always pass --type when creating tasks.
• cz-cli task content <task> is draft-only. Use cz-cli task status <task> before validating cron, retry, readiness, or formal scheduled behavior so you can see whether the latest draft has actually been published.
• Flow tasks use cz-cli task flow * commands for nodes; do not use normal task content/deploy commands on flow nodes.
• Flow draft changes do not affect formal schedule runs until you publish them with cz-cli task flow submit <task>.
• cz-cli task flow temp-run <task> is TEMP/ad-hoc debugging only. Do not use it to conclude formal SCHEDULE retry semantics or published schedule behavior.
• Merge tasks use cz-cli task create <name> --type MERGE and cz-cli task save-merge <task> --dependency <upstream> --status SUCCESS --status FAILED; use --status SKIPPED only for upstream if/condition tasks.
• For standalone task runtime params, use cz-cli task save-content <task> --params '{"key":"value"}' while saving script content, or cz-cli task save-config <task> --param key=value to merge/update params without changing script content.
• cz-cli task content <task> returns saved params, and may also return input_params / output_params when the backend has those lists.
• For flow node params, use cz-cli task flow node-save: --param key=value for manual defaults, --flow-param key for values inherited from parent flow execution params, --output-param key to declare $[output], and --input-param key=upstreamNodeName to consume an upstream node output. Bind the upstream dependency first so the upstream node can resolve from the DAG.
• For flow schedule validation, prefer this path: cz-cli task status <task> → cz-cli task flow submit <task> if needed → cz-cli runs list --task <task> --run-type SCHEDULE → cz-cli attempts list --run-id <schedule_run_id>.
• Confirm intent before destructive or state-changing operations: deploy, undeploy, execute, delete, refill/backfill, stop, rerun, and similar actions.
• For historical reruns or backfills, use cz-cli runs refill <task> --from YYYY-MM-DD --to YYYY-MM-DD; this is under runs, not task.
• For output table JSON flags such as --output-tables, pass the JSON array as one shell argument, usually with single quotes.
• cz-cli task cdc * commands operate on multi-table CDC pipelines only (MULTI_REALTIME, fileType 281). Single-table Kafka streaming tasks (fileType 14) use task start / task stop, not task cdc.

Data Quality Rules

• cz-cli dqc * manages data quality check rules: list / create / update / stat / run / delete. A rule is a custom SQL returning a single number compared to a threshold (--operator + --value); the canonical form is --sql "select count(*) from db.t where <violation>" --operator EQUAL --value 0.
• dqc create requires a compute VC via --vc (GENERAL/ANALYTICS) — sync-only INTEGRATION VCs cannot run rule SQL. Omit --vc to have the CLI list available compute VCs. Confirm the VC with the user rather than defaulting.
• dqc run is async: it returns a task_id, not the pass/fail result. dqc delete is destructive — confirm intent (or pass -y).

Output Handling

• --format json: best for parsing.
• --format toon: line-per-field output, useful with grep or head.
• --format table, --format csv, --format pretty: human-readable.
• --field <name>: extracts one field as raw text.
• Paginated list commands usually return page 1; check ai_message for next-page hints.

Command Reference

Read references/command-reference.md when you need examples or command coverage beyond these core rules.