Choose the Right Surface

Use this page before reaching for a command. Caracal separates local runtime lifecycle from product management so workload execution does not depend on admin tokens or selected zones.

Ownership Rule

local lifecycle and process execution -> caracal
human product management              -> caracal console / caracal-console
scripted product management           -> Control API or Admin SDK

The top-level runtime CLI intentionally contains only up, down, status, purge, run, and console.

Runtime CLI Tasks

Outcome	Command
Start the local stack	`caracal up`
Stop the local stack	`caracal down`
Stop and remove volumes	`caracal down -v`
Probe service health	`caracal status`
Probe dependency readiness	`caracal status --ready`
Emit structured status	`caracal status --json`
Remove local stack/runtime state	`caracal purge`
Run a process with resource tokens	`caracal run -- <command>`
Open the Console	`caracal console`

Runtime CLI commands must not require admin tokens, selected zones, product credentials, or Control credentials.

Console Tasks

Outcome	Console menu
Create or select zones	`zone`
Register confidential agent applications	`application`
Configure provider credential sources	`provider`
Register protected resources and scopes	`resource`
Author access policies	`policy`
Simulate and activate policy sets	`policy set`
Inspect authority sessions	`authority session`
Enable and manage Control API access	`control`
Search audit records and trace selected requests	`audit`
Trace one known request ID	`request trace`
Inspect or manage agent sessions	`agent session`
Inspect or revoke delegation edges	`delegation`
Run health, readiness, zone, and preflight checks	`diagnostics`

Product-management workflows are not mirrored as top-level runtime CLI commands. Keeping them in the Console prevents command drift and keeps interactive operations tied to the same engine/admin helpers.

Automation Tasks

Use the Admin SDK from trusted operator environments when scripts need to create zones. Use the Control API for zone-bound automation over applications, resources, policies, authority sessions, agents, delegation edges, audit queries, and Control credentials. Enable Control from the Console control menu, then call the authenticated HTTP surface from CI or automation.

Automation must run with operator credentials only in trusted control-plane environments. Agent workloads should use caracal run or application credentials and must not receive CARACAL_ADMIN_TOKEN, CARACAL_COORDINATOR_TOKEN, CARACAL_SECRETS_DIR, or mounted operator secret files.

Troubleshooting

Symptom	Check
`caracal console` is hidden or unavailable	Use `caracal-console` directly, or reinstall so the Console binary/workspace shim is available. Runtime lifecycle commands remain available.
A command for zones, policies, or audit is missing from `caracal`	Open the Console. Those workflows are intentionally Console-owned.
Console fails in CI	Use the Control API or Admin SDK. The Console requires an interactive TTY.
Runtime command asks for product-management context	Treat it as a bug; runtime lifecycle must not depend on admin or zone state.

Next Step

Use Start and Check the Stack when you need local services running.