CLI reference

The tiyi CLI is a thin client over the same ConnectRPC API that drives the UI. Every mutation has one path; the CLI stays in lockstep with the API by construction. This page groups commands by resource — for the full flag surface on any subcommand, run tiyi <cmd> --help.

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://primary:8080 --username admin
# prompts for password, prints the JWT, optionally writes ~/.config/tiyi/credentials

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 --hostname H --upstream P --policy P [--tls auto|none|CERT]
tiyi site update <id> [...flags]
tiyi site enable <id>
tiyi site disable <id>
tiyi site delete <id>
tiyi site preview <id>           # dump the Caddy JSON the applier would emit
tiyi site policy-override <id> [--blocking-pl N --inbound-threshold N ...]

Upstreams

tiyi upstream list
tiyi upstream get <name|id>
tiyi upstream create --name N --target URL [--target 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 FILE --key FILE
tiyi cert issue --domain D --email E [--challenge http-01|dns-01] [--directory 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 create --name N --template strict|standard|permissive
tiyi policy update <id> [...layer flags]
tiyi policy delete <id>
tiyi policy preview <id> [--site-id S]   # effective compiled SecLang
tiyi policy versions <id>                       # list snapshot revisions
tiyi policy diff <id> --from A --to B           # side-by-side diff
tiyi policy rollback <id> --to REV

Rule overrides, custom rules, IP lists

tiyi rule override upsert --policy P --rule-id N --action default|disable|log_only|score_override [--score-override N] [--scope global|site --site-id S]
tiyi rule override delete --policy P --rule-id N
tiyi rule custom create --policy P --seclang FILE
tiyi rule custom delete --policy P --rule-id N
tiyi rule ip-list create --policy P --kind allow|deny|monitor --name N
tiyi rule ip-list add-entries <id> 203.0.113.0/24 geo:CN
tiyi rule ip-list import-csv <id> --file F
tiyi rule ip-list bind <id> --policy P [--path-prefix /api]
tiyi rule rate-limit upsert --policy P --endpoint /login --rps 5 --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 --tag v4.25.0 --paranoia 1 --tag attack-sqli
tiyi crs exclusion-package list
tiyi crs exclusion-package install --slug wordpress
tiyi crs exclusion-package attach --policy P --slug wordpress [--scope /wp-admin/]

Agents

tiyi agents list
tiyi agents get <id>
tiyi agents issue-token [--tag edge] [--ttl 24h]
tiyi agents install-script --server-url URL --enrollment-token T
tiyi agents send-command <id> --kind reload|restart|collect_diagnostics
tiyi agents commands [--agent-id id>]
tiyi agent-group list
tiyi agent-group create --name N --tag-selector role=edge
tiyi agent-group resolve <id>

Trust profile

tiyi trust show
tiyi trust set --trusted-proxies 10.0.0.0/8,172.16.0.0/12 --client-ip-headers X-Forwarded-For
tiyi trust reset
tiyi trust test --peer 10.0.0.5 --header "X-Forwarded-For: 1.2.3.4"
tiyi trust status
tiyi trust cdn list
tiyi trust cdn refresh cloudflare

Alerts

tiyi alert active list
tiyi alert active ack <id>
tiyi alert active resolve <id>
tiyi alert rule list
tiyi alert rule upsert --name N --kind security_threshold --condition FILE
tiyi alert channel list
tiyi alert channel upsert --name N --kind webhook|slack|pagerduty|feishu|wecom --config FILE
tiyi alert channel test <id>

Logs

tiyi log security list [--site S] [--client-ip IP] [--rule-id N] [--from T] [--to T]
tiyi log security get <event-id>
tiyi log security export --format ndjson --output F
tiyi log access  list [...filters]
tiyi log error   list [...filters]
tiyi log audit   list [...filters]
tiyi log tail-security                       # live stream

Audit chain

tiyi audit list [--actor UUID] [--action prefix] [--from T] [--to T]
tiyi audit get <id>
tiyi audit verify-chain                      # 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 --key siem.filter.include_audit --value true
tiyi system settings update --key telemetry.enabled --value true

Releases (rolling agent upgrades)

tiyi release import --tarball ./tiyi-1.2.3.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 --role R
tiyi user reset-password <id>
tiyi user lock <id>
tiyi user unlock <id>
tiyi role list
tiyi role get <id>

Cluster failover

tiyi promote                     # on the secondary, after verifying the primary is unreachable
tiyi promote --force             # skip the demote step; accept bounded data loss

Exit codes