This document belongs to RedNet Cloud — 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 RedNet Cloud, 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):

1. Authentication (auth)

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)

After creating a profile, run zcloud --profile <name> config set api_url <URL> to write the api_url and other settings.
The profiles create command 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)

3.1.1 Zombie WeChat bindings (sys wx-zombies)

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)

3.3 OEMs (sys oems)

3.4 Sessions (sys sessions)

3.5 Operation Audit (sys audit-logs)

4. guard Module (Web Protection)

4.1 Domains (guard domains)

4.1.1 Domain Node Assignment (guard domains nodes)

Which protection nodes a domain is bound to determines which nodes carry its traffic. Successful assign/remove calls trigger config re-distribution; lock only changes state without re-distribution. sync is an ops reconciliation tool: it fully aligns node bindings of ALL domains with the upstream (aeg) per-user node allocation (adding missing bindings, removing surplus ones) — run it once after nodes are reclaimed to batch-clean ghost bindings. It overwrites manual per-domain fine-grained assignment; for day-to-day incremental assignment use assign (the console no longer exposes the sync entry, CLI only).

4.1.2 Domain Anti-Brute-Force (guard domains brute-force)

Per-domain request-rate rules: when the same source IP / bot session exceeds the request threshold against a given URI within the counting window, the configured action is executed (block / redirect / captcha, etc.). Rules live in a shared table and are distributed to nodes; successful create/update/delete calls trigger config re-distribution. Unit flags (--req-time-unit/--block-time-unit/--window-unit) only accept the enum names ReqUnit_1_PSec (seconds) / ReqUnit_2_PMin (minutes). update overwrites the whitelisted fields as a whole row: optional flags not given are written as zero values; --status defaults to true — use --status=false to disable a rule. Weak-password interception is not part of this group — use zcloud guard domains set-settings (the guard_weak_password_setting key).

4.1.3 Domain Cache Actions (guard domains cache)

Warm up / purge the domain's CDN cache. Both commands are asynchronous: the server builds a cache instruction and dispatches it to the nodes through the legacy-platform gen (zRPC cmd=554 → MQ) — send-and-return: nothing is persisted, there is no execution-result query, and command success only means the instruction was submitted to the dispatch channel. --resources maps to the request-body field cache_res (multiple resource paths separated by comma/space/newline; may be empty). Cache rules / advanced config / warm-up resource list are not part of this group — use zcloud guard domains get-settings / set-settings (the cache_config_v2_setting key).

4.1.4 DNS Advanced Settings (guard domains dns-advance)

Advanced DNS scheduling settings: auto return-to-origin, minimum active node records, IPv6 checks (1:1 with the zmod "DNS Advanced Settings" dialog). update overwrites all four fields as a group (all required); every other key stored in disp_config_setting (total_count/ava_ratio/max_count/auto_switch, etc.) is preserved server-side. The three toggle flags take booleans and are converted to the CFGOPTION_1_DISABLE/CFGOPTION_2_ENABLE string enum names on the wire. The IPv6 toggles are the master switch for dual-stack access: saving does not touch existing DNS records; AAAA records are generated/removed on the next zcloud guard schedules init rebuild.

4.2 Certificates (guard certs)

Three certificate types (--type, maps to the API's certificate_type):

# Standard TLS (default, --type can be omitted)
zcloud guard certs upload --name star --cert ./fullchain.pem --key ./private.key

# GM NTLS: signing pair + encryption pair, all four are mandatory (material must really be SM2, otherwise 400)
zcloud guard certs upload --name gm-2026 --type ntls \
  --sign-cert ./sign.pem --sign-key ./sign.key --cert ./enc.pem --key ./enc.key

# Keyless: the private key stays on the customer's own server; only the address is reported
zcloud guard certs upload --name keyless-2026 --type nokey \
  --cert ./fullchain.pem --no-key-tls-addr 10.0.0.9:8443

4.3 Policies (guard policies)

4.4 Black/White Lists (guard bwlist)

4.5 WAF Rules (guard waf)

4.5.1 WEB Base Protection (guard waf-base, read-only)

Policy-level WEB base protection has four parts: base config (block page/engine/XML/body size), high-frequency penalty, precision whitelist, and BODY inspection whitelist. Create/update/delete for whitelist/BODY/base config carry nested payloads (zones array, enum KEY strings, block-page linkage validation) and are UI-primary; the CLI provides four read-only inspection commands. Write CLI is a rule-5 exemption (nested payloads, UI-first).

zcloud guard waf-base config 60806153-1332-41aa-9286-16ba4592d2cb --format json
zcloud guard waf-base white-list 60806153-1332-41aa-9286-16ba4592d2cb --format json
zcloud guard waf-base rule-versions 60806153-1332-41aa-9286-16ba4592d2cb --format json
zcloud guard waf-base policy-schemas 60806153-1332-41aa-9286-16ba4592d2cb --rule-version v2022.05.05 --format json

4.6 Forwards (guard forwards)

4.7 DNS Scheduling (guard schedules)

This module only covers DNS parsing scheduling (SRC/NODE mode switch and batch record enable/disable). Every write persists compatibility-table state, then the cloud DNS worker applies it through the configured DNS provider API. Always poll with affairs to obtain the final outcome (AffairsStatus_Start → Succeed / Faild).

4.8 Applies (guard applies)

4.9 Origin Groups (guard origin-groups)

One origin group = a set of protection nodes bound to the subset of origin servers they pull from, making "which node pulls from which origins" controllable (e.g. telecom nodes pull from telecom origins). Each domain has exactly one default origin group (holds all origins, cannot be deleted, fallback for ungrouped nodes); a node belongs to exactly one group within a domain; if any origin in a group is IPv6, the group must contain at least one IPv6-capable node. list supports the global --format table|json|yaml.

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):

chart-key catalog per page:

5.1 2026-04-30 chart-rebuild 6-phase extension (4 new pages + 2 standalone subcommand groups)

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-action accepts only 0=allow / 1=block / 2=captcha; --bot-reason filters Bot protection evidence; --z-white is 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).

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

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 — zcloud currently 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:

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)

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.

9. netdiag Module (Network Diagnostics)

Run a full-chain checkup on a domain (DNS → ICP → certificate → cloud-WAF access → node connectivity → origin health), or use the Ping tool. All checks are read-only probes fired from the management server; nothing is written. Responses are nested — add --format json.

Examples

# Single check: DNS resolution and whether CNAME points to the platform
zcloud netdiag dns www.example.com --format json

# Single check: origin health (TCP + HTTP two-stage probe)
zcloud netdiag origin www.example.com --format json

# Single check: ping a target
zcloud netdiag ping www.example.com --format json

Bound API: GET /api/netdiag/{dns,icp,ssl,access,nodes,origin}?domain=<domain> / GET /api/netdiag/ping?target=<target>

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 / audit / get-settings / set-settings / src-check-peers / nodes[list,available,assign,remove,lock,sync] / brute-force[list,create,update,delete] / cache[warm,purge] / dns-advance[describe,update])
│   ├── certs    (list / describe / upload / update / delete / bind / unbind)
│   ├── policies (list / describe / create / update / delete)
│   ├── bwlist   (sets[*] / ips[*])
│   ├── waf      (rules[*])
│   ├── waf-base (config / rate-limit / white-list / body-list / rule-versions / policy-schemas)  [只读 / read-only]
│   ├── forwards (list / create / update / set-status / delete)
│   ├── schedules(domains / switch-mode / batch-switch-mode / init / reset / records / create-record / update-record / delete-record / batch-status / open / close / affairs / affair)
│   ├── origin-groups (list / create / delete)
│   └── 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]
├── netdiag      (dns / icp / ssl / access / nodes / origin / ping)
├── update
├── completion
└── version

Related Documents

• API Documentation — REST endpoints behind these commands
• Authentication — profile / 401 retry mechanics
• Permission Matrix — required permission keys

RedNet Cloud · zcloud CLI · 98 commands, source of truth src/frontend/src/views/docs/cli-commands.ts