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.

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 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. Submit it at your management hostname's /setup page 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 bans unban 203.0.113.10 &&
docker compose restart clearplane-core

<range> 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. Restart Core after a successful command so the serving process reloads active bans.

Purge the cache

docker compose exec clearplane-core clearplane cache purge everything
docker compose exec clearplane-core clearplane cache purge route 42
docker compose exec clearplane-core clearplane cache purge uri https://app.example.com/index.html
docker compose exec clearplane-core clearplane cache purge 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 route ID is shown on the cache page. 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. 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 all three databases automatically. Use these commands for manual preparation with Core stopped. Choose the operation that matches the persistent state.

Fresh provisioning requires all three databases, machine secrets, and other durable state to be absent. Existing state requires all three databases and a valid matched secret generation. Core validates every history before migrating any database; unknown, empty, reordered, or partially missing 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 secrets status

When Core cannot start, use a one-shot container:

docker compose run --rm --no-deps clearplane-core secrets status

Rotation supports these scopes:

Stop the entire stack because services retain credentials in memory:

docker compose down &&
docker compose run --rm --no-deps clearplane-core secrets rotate all &&
docker compose up -d --wait

Replace all with the desired scope. Rotation journals progress. If interrupted, keep the stack stopped, inspect secrets 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

Results go to stdout and failures to stderr. Secret status is redacted; setup-code intentionally prints the requested setup code.