Commands
This page groups the command surface by execution context and operational purpose.
Audience: User
Context: Use this as a structured reference after you already understand the host-versus-runtime split.
Host Commands
These commands run on the host and manage the runtime itself.
| Command | Purpose | Notes |
|---|---|---|
caracal up | Start PostgreSQL, Redis, and mcp | May pull or build images depending on compose file |
caracal down | Stop the stack | Removes services and orphans |
caracal reset | Stop the stack and remove volumes | Resets persistent container data |
caracal purge --force | Remove all Caracal runtime resources and local state | Destructive |
caracal logs -f | Tail runtime logs | Defaults to mcp, postgres, and redis |
caracal cli | Open restricted in-container CLI | Ensures stack is up first |
caracal flow | Launch Flow | Starts the TUI session in the runtime |
In-Container Command Groups
These groups are exposed by the operational CLI inside caracal cli.
| Group | Purpose |
|---|---|
workspace | Create, list, switch, inspect, and delete workspaces |
principal | Register and inspect principals |
policy | Create and list authority policies |
authority | Issue, validate, revoke, delegate, and graph mandates |
delegation | Generate, list, validate, and revoke delegation tokens or relationships |
provider | Add, list, test, and remove workspace providers |
config | Read and modify high-level runtime configuration surfaces |
audit | Export audit information and inspect workflow/command coverage |
merkle | Manage Merkle keys, verification, export, and backfill |
snapshot | Create, list, verify, and restore snapshots |
allowlist | Manage resource allowlists |
config-encrypt | Encrypt and decrypt config values |
mcp-service | Start or inspect the standalone MCP service |
backup, db, migrate | Operational maintenance tasks |
Command Relationships
The most important operational dependency chain is:
- configure a workspace
- configure providers
- register principals
- create policies
- issue mandates
- validate or delegate authority
That order exists because later commands depend on data created by earlier ones.
Practical Usage
Common sequences:
caracal workspace create demo
caracal workspace use demo
caracal provider list
caracal principal list
caracal policy list
caracal authority list
caracal audit export
caracal merkle list-batches
caracal snapshot list
Advanced command families
Use these groups when you are operating beyond the initial authority lifecycle:
merklefor integrity verification, key rotation, and historical backfillsnapshotfor recovery-oriented point-in-time state operationsdbandmigratefor schema and deployment migration workmcp-servicefor the HTTP service that fronts MCP enforcement flows
Edge Cases And Constraints
- Some command names in help text are aliased for UX. For example, the
authoritygroup exposes the issue command asmandateand validate asenforce. - Many commands are workspace-sensitive even when they do not require an explicit
--workspaceflag, because the active workspace is resolved implicitly. - Provider-scoped scope validation is enforced in policy and mandate commands. Invalid or unknown scopes fail before the operation is written.