CLI reference

The tiyi CLI is a thin client over the same ConnectRPC API that drives the UI. This page groups the current v3.5.3 operator commands by resource. Examples intentionally show only common flags; before a mutation, run tiyi <command> --help and treat the installed binary as authoritative.

Authentication modes

The CLI talks to Tiyi in one of two ways. Local commands need no token; remote commands need both an API URL and a JWT.

Get a JWT from a username/password:

$ tiyi auth login --api http://controller:8080 --username admin
# prompts for password, prints the JWT, optionally writes ~/.config/tiyi/credentials

Diagnostics

Use tiyi doctor on the host before or after install to check the local environment without changing anything. It highlights config load errors, systemd availability, sudo PATH issues, installed-service state ownership problems, and listeners on the API/dashboard and proxy ports. If no systemd unit is installed, state ownership is skipped unless you pass --service-user/--service-group or request repair. State repair is explicit and root-only: sudo tiyi doctor --fix-state-ownership.

$ tiyi doctor
$ tiyi doctor --mode agent
$ tiyi doctor --proxy-http-addr :8180 --proxy-https-addr :18443
$ sudo tiyi doctor --fix-state-ownership

Declarative apply

The kubectl-style entry point. One YAML file, one command, one audit row:

$ tiyi apply -f site.yaml
# preview-applies, shows a per-resource diff, prompts to confirm, then applies

The same validator and mutator the UI uses. Skip the prompt with --yes. Multiple resources in one file are applied in dependency order.

Sites

tiyi site list
tiyi site get <name|id>
tiyi site create --name N --host H --upstream-url URL [--tls none|managed-acme|uploaded] [--tls-http-behavior redirect|acme-only|serve-both]
tiyi site update <id> [...flags]
tiyi site enable <id>
tiyi site disable <id>
tiyi site delete <id>
tiyi site routing get <id>
tiyi site routing set <id> --route /api=UPSTREAM_ID --unmatched default|404
tiyi site policy-override get <id>
tiyi site policy-override set <id> [--blocking-pl N --inbound-threshold N ...]
tiyi site policy-override delete <id>

Upstreams

tiyi upstream list
tiyi upstream get <name|id>
tiyi upstream create --name N --endpoint-url URL [--endpoint-url URL2 ...]
tiyi upstream update <id> [...flags]
tiyi upstream delete <id>      # refused if any site uses it (UPSTREAM_IN_USE)

Certificates

tiyi cert list
tiyi cert get <id>
tiyi cert upload --name N --cert-pem FILE --key-pem FILE
tiyi cert issue DOMAIN --email E [--challenge-type http-01|dns-01] [--acme-issuer letsencrypt|letsencrypt-staging|custom] [--directory-url URL]
tiyi cert renew <id>
tiyi cert delete <id>
tiyi cert dns-provider drivers
tiyi cert dns-provider list
tiyi cert dns-provider create --name N --provider cloudflare --credentials-file F
tiyi cert dns-provider get <id>
tiyi cert dns-provider update <id>
tiyi cert dns-provider delete <id>

WAF policies

tiyi policy list
tiyi policy get <id>
tiyi policy templates
tiyi policy create-from-template --name N --template-id TEMPLATE_ID
tiyi policy create --name N [--engine-state on|detection-only|off]
tiyi policy update <id> [...layer flags]
tiyi policy delete <id>
tiyi policy preview-seclang <id>              # compiled SecLang
tiyi policy preview-impact <id> [--crs-ruleset-id R]
tiyi policy test <id> --url /login --method POST
tiyi policy versions <id>                      # list saved versions
tiyi policy diff <left-version-id> <right-version-id>
tiyi policy rollback <id> --version-id REV

Rule overrides, custom rules, IP lists

tiyi rule override upsert <policy-id> --crs-rule-id N --action default|disable|log_only|score_override [--site-id S] [--scope /api]
tiyi rule override delete <override-id>
tiyi rule custom create <policy-id> --name N --rule-id 8000001 --seclang-file FILE
tiyi rule custom delete <custom-rule-id>
tiyi rule ip-list create --kind allow|deny|monitor --name N --entry 203.0.113.0/24
tiyi rule ip-list add-entry <id> --entry 198.51.100.0/24
tiyi policy bind-ip-list <policy-id> --ip-list-id <id> --decision allow|deny|monitor
tiyi rule rate-limit upsert --policy-id P --path-pattern /login --per-minute 60 --action block

CRS catalog

tiyi crs ingest --tag v4.25.0            # fetch a release from upstream
tiyi crs ingest --archive FILE             # offline archive upload
tiyi crs releases                            # list available upstream tags
tiyi crs list                                # installed CRS rulesets
tiyi crs rules <ruleset-id> --paranoia-level 1 --tag attack-sqli
tiyi crs rule <ruleset-id> <rule-id>
tiyi crs plugins
tiyi crs plugin-schema <plugin-id>

Agents

tiyi agents list
tiyi agents get <id>
tiyi agents issue-token [--tag edge] [--ttl-seconds 86400]
tiyi agents install-script --controller-url URL --enrollment-token TOKEN
tiyi agents bundles [agent-id]
tiyi agents bundle <bundle-id>
tiyi agent-group list
tiyi agent-group get <id>
tiyi agent-group create --name N --tag role=edge
tiyi agent-group delete <id>

Trust profile

tiyi trust show
tiyi trust set --proxy 10.0.0.0/8 --proxy 172.16.0.0/12 --header X-Forwarded-For
tiyi trust set --cdn cloudflare --header CF-Connecting-IP --header X-Forwarded-For
tiyi trust reset
tiyi trust test --peer 10.0.0.5 --header "X-Forwarded-For: 1.2.3.4"
tiyi trust refresh cloudflare

Alerts

tiyi alert list
tiyi alert get <id>
tiyi alert ack <id> [--note TEXT]
tiyi alert notes <id>
tiyi alert resolve <id> [--note TEXT]
tiyi alert rule list
tiyi alert rule upsert --name N --expression-json JSON
tiyi alert channel list
tiyi alert channel upsert --name N --kind webhook|slack|pagerduty|feishu|wecom|email --config-json JSON
tiyi alert channel test <id>

Logs

tiyi log security list [--site-id S] [--client-ip-cidr CIDR] [--rule-id N] [--start T] [--end T]
tiyi log security get <event-id>
tiyi log security export --site-id S --out F
tiyi log access  list [...filters]
tiyi log error   list [...filters]
tiyi log tail-security                       # live stream

SecurityFact investigation

v3.5.3 has no incident or campaign CLI resource. Start from tiyi alert list or tiyi log security list, then pivot by --unique-id, site, rule, client CIDR, and time window. Correlate the matching Attack, Access, and Runtime Error rows in the UI.

Audit chain

tiyi audit list [--actor-id UUID] [--action ACTION] [--start T] [--end T]
tiyi audit get <id>
tiyi audit verify                            # walks the chain and reports each link

System

tiyi system stats
tiyi system traffic --window 1h
tiyi system attack-distribution --window 1h
tiyi system top-attackers --window 1h
tiyi system settings get
tiyi system settings update --set siem.enabled=true
tiyi system settings update --set siem.endpoint=tcp://siem.internal:514 --set siem.filter.include_audit=true

Logging and evidence policy is a revision-CAS LogService resource, managed under Administration → Settings → Logs & evidence; legacy telemetry.*, logsink.*, log_mode.*, and log_retention settings are rejected.

Releases (rolling agent upgrades)

tiyi release import --tarball ./tiyi_3.5.2_linux_amd64.tar.gz
tiyi release list
tiyi release apply <release-id>           # fan APPLY_BINARY to all matching agents
tiyi release apply <release-id> --agent-id A --agent-id B
tiyi release runs
tiyi release run-get <run-id>
tiyi release run-cancel <run-id>
tiyi release rollback
tiyi release check-updates

Users and roles

tiyi user list
tiyi user create --username U --password P --role-id R
tiyi user reset-password <id> --password P
tiyi user lock <id>
tiyi user unlock <id>
tiyi role list
tiyi role get <id>

Controller and Agent processes

tiyi run                         # complete writable Controller + local data plane
tiyi install --mode agent --unit-name tiyi-agent --now # Agent systemd service; reads /etc/tiyi/tiyi-agent.env
tiyi agent --controller-url http://controller:8080 --enrollment-token <one-use-token> # foreground Agent
tiyi dashboard                   # UI-only process

Exit codes