CLI
Every embedded Clearplane command for setup, status, administrator recovery, bans, cache purges, databases, and secrets.
The clearplane command is included in the Core container. Run application commands through Docker Compose from the directory containing docker-compose.yml:
docker compose exec clearplane-core clearplane --help
Replace clearplane-core with your Core service key if you renamed it. Docker Compose handles installation, image pulls, start, stop, restart, logs, and removal; see Installation for those commands.
Using an LLM or coding agent? Open the plain-text CLI reference, the LLM documentation index, or the complete documentation file.
All commands
For online commands, use docker compose exec clearplane-core clearplane <command>. Database maintenance and secret rotation use the one-shot examples below.
| Command | Purpose | When to run |
|---|---|---|
serve |
Prepare persistent state and start Core. This is the default when no command is supplied. | Started by Compose; do not launch another serving process with exec. |
installation status |
Validate installation state and print Pending or Installed. |
Online. |
installation setup-code |
Issue a replacement code for initial browser setup and print the setup URL on the management hostname. | Online, before initial setup completes. |
administrator create |
Prompt for username, display name, and password to create the first administrator and complete setup. | Online, before initial setup completes; attached terminal required. |
administrator reset-password <username> |
Set a replacement administrator password, invalidate older sessions, and require a password change after sign-in. | Online; attached terminal required. |
administrator reset-multi-factor-authentication <username> |
Reset the administrator's MFA enrollment while preserving the account's MFA requirement. | Online. |
ban lift <address> |
Lift active bans matching the normalized IP address or CIDR range. Edge stops enforcing them immediately. | Online; Core must be serving. |
cache purge <scope> |
Purge cached responses on every connected Edge: everything, proxy-route <proxy-route-id-or-name>, exact-uri <absolute-uri>, uri-prefix <absolute-uri>, or tag <tag> [<tag> ...]. |
Online; Core must be serving. |
secret status |
Report redacted machine-secret generation metadata and missing, invalid, or expiring files. | Online or in a one-shot container, including when Core cannot start. |
secret rotate <scope> |
Rotate one secret scope or the complete matched generation. | Stop the entire stack first. |
database initialize |
Initialize wholly absent persistent state or validate already-current complete state. Refuses pending migrations and partial state. | Stop Core first. |
database migrate |
Apply known forward migrations to complete existing state, or validate already-current state. Refuses absent or incompatible state. | Stop Core first. |
version, --version |
Print the Clearplane version and exit. | Online or in a one-shot container. |
help, --help, -h |
Print command help and exit. | Online or in a one-shot container. |
Commands accept the exact arguments shown. Passwords are entered at prompts without echo and must be confirmed; there is no password argument. Use an attached terminal for administrator creation and password reset, without Compose's -T option or redirected input.
Status and first setup
docker compose exec clearplane-core clearplane installation status
docker compose exec clearplane-core clearplane installation setup-code
A setup code expires after 15 minutes. A new code invalidates the previous one; five syntactically valid incorrect attempts invalidate the current code. Successful setup consumes the code and permanently closes initial setup. The command prints the setup URL, such as https://waf.example.com/setup, taken from the UI route's clearplane.proxy.host; until that route is enabled it explains how to enable it. Submit the code there over trusted HTTPS.
To create the first administrator through the terminal:
docker compose exec clearplane-core clearplane administrator create
This command completes initial setup; it does not add administrators to an already-installed system.
Administrator recovery
docker compose exec clearplane-core clearplane administrator reset-password <username>
docker compose exec clearplane-core clearplane administrator reset-multi-factor-authentication <username>
Password reset invalidates the target administrator's older sessions and requires a password change after sign-in. MFA reset clears enrollment without changing whether MFA is required. These commands are available through host/container access; there is no anonymous browser recovery flow.
Remove a ban
docker compose exec clearplane-core clearplane ban lift 203.0.113.10
<address> accepts an IPv4 address, IPv6 address, or CIDR range. Matching uses the normalized address or exact normalized CIDR; a CIDR argument does not remove every individual-address ban contained within that network. The command asks the serving Core to lift the bans, so every connected Edge stops enforcing them at once, just as when you lift a ban from the Blocked IPs report.
Purge the cache
docker compose exec clearplane-core clearplane cache purge everything
docker compose exec clearplane-core clearplane cache purge proxy-route 42
docker compose exec clearplane-core clearplane cache purge proxy-route "Shop frontend"
docker compose exec clearplane-core clearplane cache purge exact-uri https://app.example.com/index.html
docker compose exec clearplane-core clearplane cache purge uri-prefix https://app.example.com/assets/
docker compose exec clearplane-core clearplane cache purge tag product-42 catalog
These are the same purges as the cache page and POST /api/cache/purge. A proxy route is identified by its ID, shown on the cache page, or by its name, such as the clearplane.proxy.name label; an argument made only of digits is an ID. URIs are absolute HTTP or HTTPS URIs without a fragment; a prefix matches every cached URI that starts with it. Tags match the upstream's Cache-Tag and Surrogate-Key response headers, ignoring case; up to 30 tags per command, without whitespace or commas.
The command calls the serving Core over the container's loopback interface with Core's own internal certificate, so it works only through docker compose exec while Core runs; ban lift works the same way. It prints the purge revision and each Edge's result, and exits 1 when any Edge fails. When no Edge is connected, every Edge purges its whole cache when it reconnects.
Database maintenance
Normal startup prepares the application, analytics, logs and IP-data databases automatically. Core creates a missing analytics, logs or IP-data database (database/ip-data.db in clearplane-core-data); the IP-data database belongs to Core's backup scope. Use these commands for manual preparation with Core stopped. Choose the operation that matches the persistent state.
Fresh provisioning requires every database, the machine secrets, and other durable state to be absent. Existing state requires the application database and a valid matched secret generation; Core creates a missing analytics, logs or IP-data database. Core validates every existing history before migrating any database; unknown, empty, reordered, or incompatible state is refused without resets.
Initialize empty volumes, or validate already-current complete state:
docker compose stop clearplane-core &&
docker compose run --rm --no-deps clearplane-core database initialize &&
docker compose up -d --wait
Migrate a complete existing installation:
docker compose stop clearplane-core &&
docker compose run --rm --no-deps clearplane-core database migrate &&
docker compose up -d --wait
One-shot containers already use clearplane as their entry point, so the command follows the service key directly. The && chains leave Core stopped if maintenance fails; diagnose the failure before starting it again.
Secret status and rotation
Inspect redacted status online:
docker compose exec clearplane-core clearplane secret status
When Core cannot start, use a one-shot container:
docker compose run --rm --no-deps clearplane-core secret status
Rotation supports these scopes:
| Scope | Secret material |
|---|---|
session-jwt |
Signing key for every user's session tokens. |
stored-certificates |
Stored-certificate protection password and re-encrypted certificates. |
internal-tls |
Private CA and internal service identities. They are issued for 1,000 years and never need routine renewal; rotate them after a suspected compromise. |
challenge-clearance |
Bot-challenge signing key; invalidates cookies and pending proofs when Edge restarts. |
all |
All of the above in one matched generation. |
Stop the entire stack because services retain credentials in memory:
docker compose down &&
docker compose run --rm --no-deps clearplane-core secret rotate all &&
docker compose up -d --wait
Replace all with the desired scope. Rotation journals progress. If interrupted, keep the stack stopped, inspect secret status, and rerun the exact same scope to resume. Never delete the journal or replace only one service's generation to force startup.
Exit codes
| Code | Meaning |
|---|---|
0 |
Success. Help also exits successfully without starting Core. |
1 |
Operational failure, including an invalid secret status, Core not serving a cache purge, or an Edge failing one. |
2 |
Unsupported command or invalid argument syntax. |
Results go to stdout and failures to stderr. Secret status is redacted; installation setup-code intentionally prints the requested setup code.