This document belongs to Cloud WAF — Enterprise Web Protection Management Platform
CLI tool:zcloud· 6 modules: auth / config / sys / guard / analytics / tools
Full API index: /api/openapi.json · Sitemap: /sitemap.xml · AI Quick Read: /llms.txt
Full CLI Command Reference
What is zcloud
zcloud is the official CLI for Cloud WAF, built on Cobra. It mirrors 100% of the management console's core operations across 98 commands organized in 6 modules (auth / config / sys / guard / analytics / tools).
The binary is distributed dynamically by the backend at /api/cli/version, and supports linux/darwin × amd64/arm64.
Installation
See Quickstart, or:
curl -fsSL <api_url>/api/cli/install.sh | sh
zcloud version
Common Flags
The following flags are valid for every command (inherited from the root):
| Flag | Type | Description |
|---|---|---|
--api-url |
string | Override api_url for a single invocation |
--insecure |
bool | Skip TLS verification (self-signed certs) |
--profile |
string | Use a specific profile (defaults to active) |
--format |
enum | Output format: table / json / yaml (default table) |
--verbose |
bool | Print request details for debugging |
--quiet |
bool | Quiet mode: suppress success notices and pagination info; data on stdout and errors on stderr are unaffected |
--yes / -y |
bool | Auto-answer "yes" to any confirmation prompt (equivalent to -f on every delete command) |
--help / -h |
bool | Help for the current command |
1. Authentication (auth)
| Command | Description | Example |
|---|---|---|
zcloud auth login |
Interactive login (prompts for username and password, password is hidden); credentials are written to ~/.zcloud/credentials.toml |
zcloud auth login |
zcloud --api-url <URL> auth login |
Override the API URL for this session, then log in | zcloud --api-url https://waf.example.com auth login |
zcloud --insecure auth login |
Skip TLS verification when logging in (self-signed certs, internal testing only) | zcloud --insecure auth login |
zcloud auth logout |
Log out of the current session, clear local token | zcloud auth logout |
zcloud auth info |
Show current identity and permissions | zcloud auth info --format json |
zcloud auth apikey create --name N [--scopes K1,K2] [--expires-days N] |
Issue a new API key (plaintext returned only once, save it immediately) | zcloud auth apikey create --name "prod-integration" --expires-days 30 |
zcloud auth apikey list [--page N] [--size N] |
List your own / your OEM API keys | zcloud auth apikey list --format json |
zcloud auth apikey revoke <key-id> [-f] |
Revoke an API key (idempotent soft-delete, audit trail preserved) | zcloud auth apikey revoke 8f21c0c5-... -f |
zcloud auth apikey renew <key-id> --add-days N |
Extend an API key's expiry (--add-days required, 1-365 days) | zcloud auth apikey renew 8f21c0c5-... --add-days 90 |
zcloud auth apikey revoke-all [--user-id U] [--reason R] [-f] |
Revoke ALL active API keys of a user in one shot (emergency lockdown; --user-id is platform-level only, empty = yourself) | zcloud auth apikey revoke-all -f --reason "possible credential leak" |
zcloud auth apikey logs <key-id> [--event call|manage] [--page N] [--size N|--limit N] |
List audit logs for the given key (default event=call, call traces) | zcloud auth apikey logs 8f21c0c5-... --limit 50 |
zcloud auth apikey stats <key-id> [--since 24h|7d|30m] |
Aggregate stats for the given key (success rate / error breakdown / top endpoints / last-1h QPS) | zcloud auth apikey stats 8f21c0c5-... --since 24h |
Bound APIs: POST /api/auth/login / POST /api/auth/logout / GET /api/auth/userinfo / GET\|POST\|DELETE /api/sys/api-keys[/<id>] / PUT /api/sys/api-keys/<id>/renew / POST /api/sys/api-keys/revoke-all / GET /api/sys/api-keys/<id>/logs / GET /api/sys/api-keys/<id>/stats
API Key invocation: send
Authorization: ApiKey zck_<prefix>.<secret>(parallel channel to Bearer session). effective_perms = user.RBAC ∩ key.scope; empty scope = inherit user RBAC fully.
2. Configuration (config)
| Command | Description | Example |
|---|---|---|
zcloud config set <key> <value> |
Set a config key in the active profile | zcloud config set api_url https://waf.example.com |
zcloud config get <key> |
Read a config key from the active profile | zcloud config get api_url |
zcloud config list |
List all config keys in the active profile | zcloud config list |
zcloud config profiles list |
List all profiles | zcloud config profiles list |
zcloud config profiles create <name> |
Create an empty profile (no flags; the first profile is auto-activated) | zcloud config profiles create prod |
zcloud config profiles activate <name> |
Switch the active profile | zcloud config profiles activate prod |
zcloud config profiles delete <name> |
Delete a profile | zcloud config profiles delete dev |
After creating a profile, run
zcloud --profile <name> config set api_url <URL>to write the api_url and other settings.
Theprofiles createcommand takes only one positional argument<name>and does not accept any flags.
config commands are local only and do not call the backend.
3. sys Module (System Management)
3.1 Users (sys users)
| Command | Description | Example |
|---|---|---|
zcloud sys users list [--page N] [--size N] [--keyword K] |
Paginated user list | zcloud sys users list --page 1 --size 20 |
zcloud sys users describe <uuid> |
User detail | zcloud sys users describe abc-123-... |
zcloud sys users create --username U --password P [--nick-name N] [--email E] [--mobile M] [--comment C] |
Create user (--username and --password are required; no --oem-id / --display-name flag exists) |
zcloud sys users create --username u1 --password '***' --nick-name 'Ops A' |
zcloud sys users update <uuid> [--nick-name N] [--email E] [--mobile M] [--comment C] |
Update user basics (incremental, only changed flags are sent) | zcloud sys users update abc-123 --nick-name 'Ops A' |
zcloud sys users delete <uuid> [-f] |
Delete user (-f skips confirm; or use the global -y) |
zcloud sys users delete abc-123 -f |
zcloud sys users reset-password <uuid> --password NEW |
Reset password (--password required) |
zcloud sys users reset-password abc-123 --password 'New***' |
zcloud sys users lock <uuid> [--locked true|false] |
Lock / unlock account (--locked defaults to true) |
zcloud sys users lock abc-123 --locked false |
zcloud sys users assign-roles <uuid> --role-ids 1,2,3 |
Assign roles (required --role-ids, comma-separated) |
zcloud sys users assign-roles abc-123 --role-ids 5,6 |
3.1.1 Zombie WeChat bindings (sys wx-zombies)
| Command | Description | Example |
|---|---|---|
zcloud sys wx-zombies cleanup [--service-ids ID1,ID2] [--max-pages N] |
Dry-run scan for local WeChat bindings whose openid no longer appears in the official account follower list | zcloud sys wx-zombies cleanup --max-pages 50 |
zcloud sys wx-zombies cleanup --apply [--max-pages N] |
Apply cleanup: clear users.wx_union_id/wx_nick_name, matching alert_receivers.weixin, and weixin_userinfo |
zcloud sys wx-zombies cleanup --apply --max-pages 50 |
Safety: the command uses WeChat user/get follower lists for set difference instead of per-user user/info calls. Hitting --max-pages aborts to avoid false positives. If the follower list is empty while local bindings exist, --apply is refused unless --allow-empty-followers is explicitly set.
3.2 Roles (sys roles)
| Command | Description | Example |
|---|---|---|
zcloud sys roles list [--page N] [--size N] [--keyword K] |
List roles | zcloud sys roles list |
zcloud sys roles create --name N [--level L] [--comment C] |
Create role (--level defaults to 1) |
zcloud sys roles create --name Operator --level 10 |
zcloud sys roles update <id> [--name N] [--level L] [--comment C] |
Update role (incremental, only changed flags are sent) | zcloud sys roles update 5 --name 'Senior Operator' |
zcloud sys roles delete <id> [-f] |
Delete role (-f skips confirm; or use global -y) |
zcloud sys roles delete 5 -f |
zcloud sys roles get-permissions <id> |
Show current permissions | zcloud sys roles get-permissions 5 |
zcloud sys roles set-permissions <id> --permissions K1,K2,K3 |
Replace permissions (overwrite; required) | zcloud sys roles set-permissions 5 --permissions guard.domain.list,guard.domain.view |
3.3 OEMs (sys oems)
| Command | Description | Example |
|---|---|---|
zcloud sys oems list [--page N] [--size N] [--keyword K] |
List OEMs | zcloud sys oems list |
zcloud sys oems describe <uuid> |
OEM detail | zcloud sys oems describe oem-abc |
zcloud sys oems create --name N --hostname H [--tag T] [--comment C] |
Create OEM (--name and --hostname required) |
zcloud sys oems create --name 'Customer A' --hostname a.example.com |
zcloud sys oems update <uuid> [--name N] [--hostname H] [--tag T] [--comment C] |
Update OEM (incremental) | zcloud sys oems update oem-abc --name 'New' |
zcloud sys oems delete <uuid> [-f] |
Delete OEM | zcloud sys oems delete oem-abc -f |
zcloud sys oems get-setting <uuid> <key> |
Read OEM setting | zcloud sys oems get-setting oem-abc theme |
zcloud sys oems set-setting <uuid> <key> <value> |
Write OEM setting | zcloud sys oems set-setting oem-abc theme dark |
3.4 Sessions (sys sessions)
| Command | Description | Example |
|---|---|---|
zcloud sys sessions list [--page N] [--size N] [--keyword K] |
List active sessions | zcloud sys sessions list |
zcloud sys sessions kill <session-id> [-f] |
Force-kick a session | zcloud sys sessions kill sess-xxx -f |
3.5 Audit Logs (sys audit-logs)
| Command | Description | Example |
|---|---|---|
zcloud sys audit-logs list [--page N] [--size N] [--keyword K] |
Operation audit log | zcloud sys audit-logs list --page 1 --size 50 |
zcloud sys audit-logs login-records list [--page N] [--size N] [--keyword K] |
Login history | zcloud sys audit-logs login-records list |
zcloud sys audit-logs permissions |
Permission tree (with i18n names) | zcloud sys audit-logs permissions --format json |
4. guard Module (Web Protection)
4.1 Domains (guard domains)
| Command | Description | Example |
|---|---|---|
zcloud guard domains list [--page N] [--size N] [--keyword K] |
List domains | zcloud guard domains list |
zcloud guard domains describe <domain-id> |
Domain detail | zcloud guard domains describe 12 |
zcloud guard domains create --domain D [--asset-name A] [--policy-id P] |
Create domain (--domain is required) |
zcloud guard domains create --domain api.example.com --asset-name "Main Site" --policy-id 1 |
zcloud guard domains update <domain-id> [--asset-name A] [--policy-id P] |
Update domain (incremental; at least one flag) | zcloud guard domains update 12 --policy-id 2 |
zcloud guard domains delete <domain-id> [-f] |
Delete domain | zcloud guard domains delete 12 -f |
zcloud guard domains get-settings <domain-id> |
Read full domain config | zcloud guard domains get-settings 12 |
zcloud guard domains set-settings <domain-id> --key K --value V |
Write a single domain setting (KV mode, not a JSON file) | zcloud guard domains set-settings 12 --key cc_protect --value enable |
4.2 Certificates (guard certs)
| Command | Description | Example |
|---|---|---|
zcloud guard certs list [--page N] [--size N] [--keyword K] |
List certs | zcloud guard certs list |
zcloud guard certs describe <cert-id> |
Cert detail | zcloud guard certs describe 3 |
zcloud guard certs upload --name N --cert F --key F [--sign-cert F] [--sign-key F] |
Upload cert (PEM; optional sign cert/key for SM2 dual-cert setups) | zcloud guard certs upload --name star --cert ./fullchain.pem --key ./private.key |
zcloud guard certs update <cert-id> [--name N] [--cert F] [--key F] [--sign-cert F] [--sign-key F] |
Replace cert (incremental) | zcloud guard certs update 3 --cert ./new.pem --key ./new.key |
zcloud guard certs delete <cert-id> [-f] |
Delete cert | zcloud guard certs delete 3 -f |
zcloud guard certs bind <cert-id> --domain-id D |
Bind cert to domain (--domain-id required) |
zcloud guard certs bind 3 --domain-id 12 |
zcloud guard certs unbind <cert-id> --domain-id D |
Unbind cert from domain (--domain-id required) |
zcloud guard certs unbind 3 --domain-id 12 |
4.3 Policies (guard policies)
| Command | Description | Example |
|---|---|---|
zcloud guard policies list [--page N] [--size N] [--keyword K] |
List policies | zcloud guard policies list |
zcloud guard policies describe <policy-id> |
Policy detail | zcloud guard policies describe 8 |
zcloud guard policies create --name N [--comment C] |
Create policy | zcloud guard policies create --name p1 |
zcloud guard policies update <policy-id> [--name N] [--comment C] |
Update policy | zcloud guard policies update 8 --name p1-v2 |
zcloud guard policies delete <policy-id> [-f] |
Delete policy | zcloud guard policies delete 8 -f |
4.4 Black/White Lists (guard bwlist)
| Command | Description | Example |
|---|---|---|
zcloud guard bwlist sets list [--page N] [--size N] [--keyword K] |
List sets | zcloud guard bwlist sets list |
zcloud guard bwlist sets create --name N --type black|white [--policy-id P] [--describe D] |
Create set (--name and --type required) |
zcloud guard bwlist sets create --name block-cn --type black |
zcloud guard bwlist sets update <set-id> [--name N] [--status enable|disable] [--describe D] |
Update set | zcloud guard bwlist sets update 5 --name allow-asia |
zcloud guard bwlist sets delete <set-id> [-f] |
Delete set | zcloud guard bwlist sets delete 5 -f |
zcloud guard bwlist ips list <set-id> [--page N] [--size N] |
List IPs in set | zcloud guard bwlist ips list 5 |
zcloud guard bwlist ips add <set-id> --ip IP |
Add single IP (--ip required) |
zcloud guard bwlist ips add 5 --ip 1.2.3.4 |
zcloud guard bwlist ips batch-add <set-id> --ips IP1,IP2,... |
Bulk-add IPs (comma-separated string; does NOT accept --file) |
zcloud guard bwlist ips batch-add 5 --ips 1.2.3.4,5.6.7.8 |
zcloud guard bwlist ips delete <ip-id> [-f] |
Delete a single IP | zcloud guard bwlist ips delete 1234 -f |
zcloud guard bwlist ips batch-delete <set-id> --ip-ids ID1,ID2,... |
Bulk-delete IPs (comma-separated IP entry IDs, scoped to the set) | zcloud guard bwlist ips batch-delete 5 --ip-ids 100,101,102 -f |
4.5 WAF Rules (guard waf)
| Command | Description | Example |
|---|---|---|
zcloud guard waf rules list [--page N] [--size N] [--policy-id P] |
List rule groups | zcloud guard waf rules list |
zcloud guard waf rules create --name N --policy-id P [--describe D] [--scope S] [--action 1|2|3] [--status 1|2] [--waf-type N] |
Create rule group (--name and --policy-id required; action 1=block / 2=log / 3=captcha) |
zcloud guard waf rules create --name sqli-1 --policy-id 8 --action 1 |
zcloud guard waf rules update <rule-id> [--name N] [--describe D] [--scope S] [--action N] [--status N] [--waf-type N] |
Update rule group | zcloud guard waf rules update 7 --name sqli-1-v2 |
zcloud guard waf rules delete <rule-id> [-f] |
Delete rule group | zcloud guard waf rules delete 7 -f |
zcloud guard waf rules set-status <rule-id> --status enable|disable |
Enable / disable rule group (string enum, not a boolean) | zcloud guard waf rules set-status 7 --status enable |
4.6 Forwards (guard forwards)
| Command | Description | Example |
|---|---|---|
zcloud guard forwards list [--page N] [--size N] [--domain-id D] [--keyword K] |
List forwards | zcloud guard forwards list --domain-id 12 |
zcloud guard forwards create --domain-id D --port P [--schema 3|4] [--domain D] [--describe D] |
Create forward (--domain-id and --port required; --schema 3=TCP 4=UDP) |
zcloud guard forwards create --domain-id 12 --port 8443 --schema 3 |
zcloud guard forwards update <forward-id> [--port P] [--schema N] [--status 1|2] [--describe D] |
Update forward (--status 1=disable 2=enable) |
zcloud guard forwards update 4 --status 2 |
zcloud guard forwards delete <forward-id> [-f] |
Delete forward | zcloud guard forwards delete 4 -f |
4.7 DNS Scheduling (guard schedules)
This module only covers DNS parsing scheduling (SRC/NODE mode switch and batch record enable/disable). It does not call any third-party DNS API directly; every write publishes an NSQ message on topic
dnsand the legacy zdns service applies the change asynchronously. Always poll withaffairsto obtain the final outcome (AffairsStatus_Start→Succeed/Faild).
| Command | Description | Example |
|---|---|---|
zcloud guard schedules domains [--page N] [--size N] [--keyword K] [--user-id U] [--mode 0|1|2] [--status S] |
List DNS scheduling domains (--mode 0=all 1=SRC 2=NODE) |
zcloud guard schedules domains --keyword example.com |
zcloud guard schedules switch-mode <domain-id> --target-mode src|node [--comment C] |
Switch SRC/NODE mode (--target-mode required) |
zcloud guard schedules switch-mode d_8a3b1c --target-mode node |
zcloud guard schedules init <domain-id> [--comment C] |
Initialize DNS parsing by rebuilding records from current config and submitting one sync affair | zcloud guard schedules init d_8a3b1c |
zcloud guard schedules reset <domain-id> [--comment C] |
Reset DNS parsing for the domain (switch_state to 1, status rolled back to last_status) | zcloud guard schedules reset d_8a3b1c |
zcloud guard schedules records <domain-id> [--group-type 1|2] [--status 1|2] [--page N] [--size N] |
List DNS records of the domain (read-only on zdns_db) | zcloud guard schedules records d_8a3b1c --status 2 |
zcloud guard schedules batch-status --record-ids id1,id2 --status enable|disable [--comment C] |
Batch enable/disable DNS records (both --record-ids and --status required) |
zcloud guard schedules batch-status --record-ids r1,r2 --status disable |
zcloud guard schedules open <domain-id> [--comment C] |
One-click open (set status=2 on every record under the current mode) | zcloud guard schedules open d_8a3b1c |
zcloud guard schedules close <domain-id> [-f] [--comment C] |
One-click close (NSQ Cmd=1, stop-affair semantics) | zcloud guard schedules close d_8a3b1c -f |
zcloud guard schedules affairs [--page N] [--size N] [--user-id U] [--status S] [--ctime-from MS] [--ctime-to MS] [--domain-id D] |
Affair record list (--status accepts AffairsStatus_Start|AffairsStatus_Succeed|AffairsStatus_Faild) |
zcloud guard schedules affairs --domain-id d_8a3b1c |
zcloud guard schedules affair <affair-id> |
Affair record detail (full HTML message + json_content) | zcloud guard schedules affair 1715600000_aB3xY9LmNq |
4.8 Applies (guard applies)
| Command | Description | Example |
|---|---|---|
zcloud guard applies list [--page N] [--size N] [--domain-id D] [--status S] |
List apply tasks (--status is pending|success|failed|running|quit) |
zcloud guard applies list --status running |
zcloud guard applies describe <apply-id> |
Task summary | zcloud guard applies describe 100 |
zcloud guard applies create --domain-id D |
Trigger an apply (--domain-id required) |
zcloud guard applies create --domain-id 12 |
zcloud guard applies detail <apply-id> |
Task detail with subtasks | zcloud guard applies detail 100 |
zcloud guard applies retry <apply-id> [--node-ids id1,id2] |
Retry failed (--node-ids targets specific nodes; empty retries all failed nodes) |
zcloud guard applies retry 100 |
zcloud guard applies quit <apply-id> [-f] |
Cancel running task | zcloud guard applies quit 100 -f |
5. analytics Module (Dashboard)
Common flags (apply to every analytics <page> command; if not explicitly set, they are NOT added to the query string and the backend default applies):
| Flag | Type | Description |
|---|---|---|
--window |
string | Time window such as last_1h / last_24h / last_7d (values defined by backend) |
--stime / --etime |
int64 | Custom start / end (Unix milliseconds) |
--site-id / --domain-id |
string | Filter by site / domain |
--compare |
bool | Period-over-period compare |
--top |
int | Top-N (1-100) |
--order |
string | Sort direction (asc / desc; chart-specific) |
--page / --size |
int | Pagination (logs/records-style charts) |
--charts |
string | Comma-separated chart keys for batch fetch (used when chart-key arg is omitted) |
chart-key catalog per page:
| Page | chart-key |
|---|---|
overview |
kpi, bandwidth, request-attack, event-type, waf-type, geo, top-domains, recent-events |
access |
request-hm, flow-hm, cache-hm, bandwidth, status, flow-duration, isp, top-ip, top-url, geo |
protect |
overview, waf/statistics, waf/types, waf/top-ip, waf/geo, cc/statistics, cc/top-ip, cc/geo, cc/top-url, ddos/statistics, ddos/types, ddos/top-ip |
ai |
attack-trend, top-ip, top-url, detection, test-results, logs |
bot |
statistics, advance-warn, browser, operating, geo, top-agent, top-ip, scatter, sessions |
alert |
total, hm, types, domains, list |
| Command | Description | Example |
|---|---|---|
zcloud analytics overview [chart-key] [flags] |
Overview metrics (omit chart-key to fetch the whole page via batch) | zcloud analytics overview kpi --window last_24h --format json |
zcloud analytics access [chart-key] [flags] |
Access stats | zcloud analytics access top-url --window last_7d --format json |
zcloud analytics protect [chart-key] [flags] |
Protection stats | zcloud analytics protect waf/statistics --format json |
zcloud analytics ai [chart-key] [flags] |
AI detection stats | zcloud analytics ai logs --page 1 --format json |
zcloud analytics bot [chart-key] [flags] |
Active protection (Bot) | zcloud analytics bot statistics --format json |
zcloud analytics alert [chart-key] [flags] |
Alert stats | zcloud analytics alert list --page 1 --size 20 --format json |
zcloud analytics glossary |
Field glossary | zcloud analytics glossary --format json |
zcloud analytics batch --page P --charts C [...] |
Cross-page batch (--page and --charts required) |
zcloud analytics batch --page overview --charts kpi,bandwidth --format json |
zcloud analytics overview export --charts C [--type csv|json] [...] |
Export overview report (only the overview sub-page exposes export) | zcloud analytics overview export --type csv --charts kpi,bandwidth > overview.csv |
zcloud analytics alert ack <alert-id> |
Acknowledge alert | zcloud analytics alert ack a-20260422-0001 |
zcloud analytics bot session <session-id> |
Bot session detail (only accepts --window / --stime / --etime) |
zcloud analytics bot session s-abc123 --format json |
5.1 2026-04-30 chart-rebuild 6-phase extension (4 new pages + 2 standalone subcommand groups)
| Command | Description | Example |
|---|---|---|
zcloud analytics health [chart-key] [flags] |
Phase 3 Business Health (status-breakdown / slow-uri / availability, 7 chart-keys) | zcloud analytics health summary --window last_24h --format json |
zcloud analytics ops [chart-key] [flags] |
Phase 5 Platform Ops (traffic-users / error-domains / nodes, 8 chart-keys, platform ops / superadmin only) | zcloud analytics ops traffic-users --top 20 --format json |
zcloud analytics closure [chart-key] [flags] |
Phase 6 Closure (summary / alerts / risks / trend, 4 chart-keys) | zcloud analytics closure summary --format json |
zcloud analytics cache [chart-key] [flags] |
Phase 6 Cache Value (summary / trend / top-uri / content-types) | zcloud analytics cache summary --window last_7d --format json |
zcloud analytics logs list [flags] |
Phase 1 Raw logs list (filters: uuid/session/ip/uri/status/z_final_*, 12 ES fields) | zcloud analytics logs list --window last_24h --status 403 --format json |
zcloud analytics logs detail <uuid> |
Phase 1 Raw log detail | zcloud analytics logs detail req-abc123 --format json |
zcloud analytics logs export --format csv [--fields ...] [flags] |
Phase 1 Raw log export (size ≤ 10000; larger goes async) | zcloud analytics logs export --format csv --fields ctime,uuid,host,uri,status > logs.csv |
zcloud analytics closure {alerts|risks} confirm --ids ID1,ID2,... |
Phase 6 Batch confirm alerts / risks (proxies /api/alert/records/confirm and /api/chart/risk/events/:event_id/confirm) |
zcloud analytics closure alerts confirm --ids a1,a2,a3 |
zcloud analytics reports templates |
Phase 4 List report templates | zcloud analytics reports templates --format json |
zcloud analytics reports list |
Phase 4 Report history list | zcloud analytics reports list --format json |
zcloud analytics reports describe <id> |
Phase 4 Report detail | zcloud analytics reports describe r-001 --format json |
zcloud analytics reports generate --template T --window W [...] |
Phase 4 Trigger generation (sync threshold ≤ 100k rows; larger goes async) | zcloud analytics reports generate --template protection-value --window last_30d |
zcloud analytics reports download <id> [--output file] |
Phase 4 Download artifact (pdf/csv/json/html) | zcloud analytics reports download r-001 --output report.pdf |
Phase 4 templates (--template): protection-value / asset-risk / attack-source / business-health / platform-summary (platform ops / superadmin only) / raw-log-export.
Truth-table field constraints (cross-cutting D3/D8/D10):
--z-final-actionaccepts only0=allow/1=block/2=captcha;--z-whiteis an independent bool field (whitelist hit) and is NOT part of the action enum.- Cache metrics use exactly
total_cache_count/total_cache_bytes/total_cache_response_bytes(forbidden:cache_count/cache_bytes). - Closure fields use exactly
process_uid/process_time/status/level(forbidden:handle_user/handle_time/risk_score).
Placeholder fallback: some chart-keys currently return {available: false, reason: "data source pending..."} from the server; the API/CLI contract is stable; real SQL/ES wiring rolls out per chart-key.
6. Plan catalog (plan)
External exposure scope: Only the two read-only commands below are part of the public API/CLI surface. Plan create/edit/delete, user assignment, and subscription queries are platform-console admin operations that write the live shared billing tables — they are NOT in the external API/CLI surface (platform ops only, via console + RBAC).
| Command | Description | Required permission |
|---|---|---|
zcloud plan list [--prod-type N] [--keyword KW] [--page N] [--page-size N] |
Paginated plan catalog query; filterable by product type (1=WAF/2=Monitor/3=GFIP) and name keyword | plan.plan.list |
zcloud plan describe <plan_id> |
Retrieve plan detail (including content quota JSON) | plan.plan.view |
Examples
# List WAF plans
zcloud plan list --prod-type 1 --format json
# Search by name keyword
zcloud plan list --keyword basic
# Get plan detail
zcloud plan describe 550e8400-e29b-41d4-a716-446655440000
Bound APIs: GET /api/plan/plans / GET /api/plan/plans/:id
7. cli_release / tools
| Command | Description | Example |
|---|---|---|
zcloud update |
Self-update (queries /api/cli/version and downloads new release) |
zcloud update |
zcloud completion <bash|zsh|fish> |
Generate shell completion script | zcloud completion zsh > ~/.zsh/_zcloud |
zcloud version |
Show current CLI version | zcloud version |
Backend release APIs: GET /api/cli/version (public) / GET /api/cli/install.sh (public).
8. Node Install / Upgrade (command line)
CLI exemption note (Rule 5): node install / upgrade has no
zcloud node ...subcommand —zcloudcurrently has only six command groups: auth / config / sys / guard / analytics / plan. The node "command line" is the platform-minted one-time install one-liner (run as root on the target node host) plus management-plane HTTP endpoints. Full endpoint semantics: API docs §8 Node Install / Upgrade.
8.1 One-line install / upgrade command (run on the node host)
POST /api/node/install/commands (upgrade: /upgrades) returns a command of the form:
curl -fsSL --connect-timeout 10 --max-time 60 \
-H 'Authorization: Bearer nit_xxx' 'https://<cloud>/api/node/install/script' \
| sudo bash -s -- --token 'nit_xxx' --server 'https://<cloud>'
Script arguments / environment variables:
| Argument | Env var | Default | Description |
|---|---|---|---|
--token <token> |
SETUP_TOKEN |
required | one-time install token (nit_ prefix), shown once |
--server <url> |
SERVER_ADDR |
required | cloud public address; must match the configured public base URL |
--install-dir <dir> |
INSTALL_DIR |
/opt/skynet-node |
install directory |
Script behavior: check deps (curl/tar/gzip/sha256sum) → download package and verify X-Artifact-SHA256 → fetch env and overwrite the package's env.conf → run install.sh → report running/success/failed via /report. All downloads use --retry; the report call uses a short timeout.
8.2 Management operations (curl / API)
| Operation | Method + path | Required permission (node.node.*) |
|---|---|---|
| Register package + precheck | POST /api/node/install/artifacts |
artifact |
| List packages | GET /api/node/install/artifacts |
artifact |
| Mint install command | POST /api/node/install/commands |
install |
| Mint upgrade command | POST /api/node/install/upgrades |
upgrade |
| List / get jobs | GET /api/node/install/jobs[/:id] |
job |
| Revoke token | POST /api/node/install/tokens/:id/revoke |
revoke |
Key points: max_uses minimum 5 / default 20 / cap 100 (keep retry headroom); ttl_seconds default 3600 / cap 86400; the plaintext token is shown once and the DB stores only hash + prefix; installer-side auth failure returns 401 + challenge; script does not consume uses, package/env consume use_count, report uses an independent report_count and only success marks the token used. See API §8.
Full Command Tree
zcloud
├── auth (login / logout / info)
├── config (set / get / list / profiles[list,create,activate,delete])
├── sys
│ ├── users (list / describe / create / update / delete / reset-password / lock / assign-roles)
│ ├── roles (list / create / update / delete / get-permissions / set-permissions)
│ ├── oems (list / describe / create / update / delete / get-setting / set-setting)
│ ├── sessions (list / kill)
│ └── audit-logs (list / login-records list / permissions)
├── guard
│ ├── domains (list / describe / create / update / delete / get-settings / set-settings)
│ ├── certs (list / describe / upload / update / delete / bind / unbind)
│ ├── policies (list / describe / create / update / delete)
│ ├── bwlist (sets[*] / ips[*])
│ ├── waf (rules[*])
│ ├── forwards (list / create / update / delete)
│ ├── schedules(domains / switch-mode / init / reset / records / batch-status / open / close / affairs / affair)
│ └── applies (list / describe / create / detail / retry / quit)
├── analytics (overview / access / protect / ai / bot / alert / glossary / batch / export / ack / session)
├── plan (list / describe) [read-only external]
├── update
├── completion
└── version
Related Documents
- API Documentation — REST endpoints behind these commands
- Authentication — profile / 401 retry mechanics
- Permission Matrix — required permission keys
Cloud WAF · zcloud CLI · 98 commands, source of truth src/frontend/src/views/docs/cli-commands.ts