Admin Commands

Admin commands manage all control-plane entities. Every command in this section requires CARACAL_ADMIN_TOKEN. Zone-scoped commands (everything except zone list, zone get, zone create) also require a zone ID, resolved in order: --zone flag → CARACAL_ZONE_ID environment variable → zone_id in caracal.toml.

All commands accept --json to emit structured JSON and --help for command-specific help.

---

Zone commands — caracal zone

caracal zone list

List all zones in the organization.

caracal zone list
caracal zone list --json

Table columns: id, name, slug, org_id, dcr_enabled, pkce_required

---

caracal zone get <id>

Fetch a single zone by ID.

caracal zone get zone_abc123

---

caracal zone create

Create a new zone.

caracal zone create --name "Production"
caracal zone create --name "Staging" --slug staging --dcr --no-pkce

Flag	Type	Default	Description
--name <n>	string	required	Display name
--slug <s>	string	Auto-derived	URL-safe slug
--org <id>	string	—	Organization ID
--dcr	boolean	false	Enable dynamic client registration
--no-pkce	boolean	—	Disable PKCE (PKCE is required by default)
--login-flow <flow>	string	standard	Login flow type

---

caracal zone patch <id>

Update an existing zone. Only supplied flags are sent.

caracal zone patch zone_abc123 --name "Production v2"
caracal zone patch zone_abc123 --dcr=true --pkce=false

Accepts the same flags as create, plus --dcr=true|false and --pkce=true|false as explicit boolean forms.

---

caracal zone delete <id>

Delete a zone.

caracal zone delete zone_abc123

Output: deleted zone_abc123

---

Application commands — caracal app

All app commands are zone-scoped.

caracal app list

caracal app list --zone zone_abc123

Table columns: id, name, registration_method, credential_type, consent, created_at

---

caracal app get <id>

caracal app get app_def456

---

caracal app create

caracal app create --name "Payment Agent" --credential-type token
caracal app create --name "Public Client" --method dcr --credential-type public

Flag	Type	Default	Description
--name <n>	string	required	Application name
--method <m>	managed|dcr	managed	Registration method
--credential-type <t>	token|password|public-key|url|public	—	Credential type
--client-secret <s>	string	—	Pre-set client secret
--traits <a,b>	string	—	Comma-separated trait list
--consent	boolean	false	Require user consent

---

caracal app patch <id>

caracal app patch app_def456 --name "Payment Agent v2"
caracal app patch app_def456 --consent=true

Accepts the same flags as create. Only supplied flags are sent.

---

caracal app delete <id>

caracal app delete app_def456

---

caracal app dcr

Create an application via Dynamic Client Registration.

caracal app dcr --name "Temp Client" --expires-in 3600

Flag	Type	Default	Description
--name <n>	string	required	Application name
--credential-type <t>	string	—	Credential type
--client-secret <s>	string	—	Pre-set client secret
--traits <a,b>	string	—	Trait list
--expires-in <s>	integer	—	Token TTL in seconds

---

Resource commands — caracal resource

All resource commands are zone-scoped.

caracal resource list

caracal resource list

Table columns: id, identifier, name, upstream_url, scopes, credential_provider_id

---

caracal resource get <id>

caracal resource get resource_ghi789

---

caracal resource create

caracal resource create \
  --identifier "resource://payments-api" \
  --scopes "transfer:read,transfer:write" \
  --name "Payments API" \
  --upstream-url "http://payments.internal"

Flag	Type	Default	Description
--identifier <id>	string	required	Resource URI
--scopes <a,b>	string	required	Comma-separated scope list
--name <n>	string	—	Display name
--upstream-url <url>	string	—	Backend URL for gateway proxying
--prefix	boolean	false	Match identifier as a prefix
--provider <id>	string	—	Credential provider ID

---

caracal resource patch <id>

caracal resource patch resource_ghi789 --scopes "transfer:read,transfer:write,transfer:admin"

Accepts the same flags as create. Only supplied flags are sent.

---

caracal resource delete <id>

caracal resource delete resource_ghi789

---

Provider commands — caracal provider

All provider commands are zone-scoped.

caracal provider list

caracal provider list

Table columns: id, identifier, name, kind, owner_type, client_id

---

caracal provider get <id>

caracal provider get prov_jkl012

---

caracal provider create

# OAuth 2.0 provider
caracal provider create \
  --identifier "provider://github" \
  --kind oauth2 \
  --name "GitHub" \
  --client-id "gh_client_id" \
  --config '{"authorization_endpoint":"https://github.com/login/oauth/authorize"}'

# Config from file
caracal provider create \
  --identifier "provider://internal-oidc" \
  --kind oidc \
  --config @/path/to/oidc-config.json

Flag	Type	Default	Description
--identifier <id>	string	required	Provider identifier URI
--name <n>	string	—	Display name
--kind <k>	oauth2|oidc|apikey|workload	—	Provider kind
--owner-type <t>	string	—	Owner type (e.g., user, agent)
--client-id <id>	string	—	OAuth 2.0 client ID
--config <json>	string	—	Public config fields as JSON; use @/path/to/file to load from a file

---

caracal provider patch <id>

caracal provider patch prov_jkl012 --name "GitHub OAuth"

---

caracal provider delete <id>

caracal provider delete prov_jkl012

---

Policy commands — caracal policy

All policy commands are zone-scoped. Policies are immutable after creation — add new Rego content as a new version.

caracal policy list

caracal policy list

Table columns: id, name, description, owner_type, created_by, created_at

---

caracal policy get <id>

Returns the policy record and all its versions.

caracal policy get pol_mno345

---

caracal policy create

caracal policy create --name "Scope Guard" --file policy.rego
caracal policy create --name "Allow All" --content 'package caracal.authz
import rego.v1
result := {"decision": "allow", "evaluation_status": "complete", "determining_policies": [], "diagnostics": []}'

Flag	Type	Default	Description
--name <n>	string	required	Policy name
--file <path>	string	required†	Path to Rego file
--content <rego>	string	required†	Inline Rego source
--description <d>	string	—	Description
--owner-type <t>	string	—	Owner type

†Either --file or --content is required.

---

caracal policy version <id>

Add a new Rego version to an existing policy.

caracal policy version pol_mno345 --file policy-v2.rego
caracal policy version pol_mno345 --file policy-v2.rego --schema-version 2026-03-16

Flag	Type	Default	Description
--file <path>	string	required†	Path to Rego file
--content <rego>	string	required†	Inline Rego source
--schema-version <v>	string	2026-03-16	Policy schema version

†Either --file or --content is required.

---

caracal policy delete <id>

Archive a policy (soft delete).

caracal policy delete pol_mno345

Output: archived pol_mno345

---

Policy-set commands — caracal policy-set

A policy set bundles policy versions into a versioned, activatable set. The STS evaluates the active policy-set version on every token exchange.

caracal policy-set list

caracal policy-set list

Table columns: id, name, active_version_id, description, created_at

---

caracal policy-set get <id>

caracal policy-set get pset_pqr678

---

caracal policy-set create

caracal policy-set create --name "Production Guards" --description "All production enforcement policies"

Flag	Type	Default	Description
--name <n>	string	required	Policy-set name
--description <d>	string	—	Description

---

caracal policy-set version <id>

Bundle policy versions into a new policy-set version.

caracal policy-set version pset_pqr678 \
  --policy-versions polv_abc,polv_def,polv_ghi

Flag	Type	Default	Description
--policy-versions <v1,v2>	string	required	Comma-separated policy version IDs

---

caracal policy-set activate <id>

Promote a version to active. Token exchanges immediately begin evaluating it.

caracal policy-set activate pset_pqr678 --version psetv_jkl012

# Shadow mode: evaluate new version in parallel but use the active version's decision
caracal policy-set activate pset_pqr678 --version psetv_mno345 --shadow psetv_jkl012

Flag	Type	Default	Description
--version <vid>	string	required	Policy-set version ID to activate
--shadow <vid>	string	—	Version to run in shadow (evaluation-only) mode

---

caracal policy-set delete <id>

Archive a policy set.

caracal policy-set delete pset_pqr678

Output: archived pset_pqr678

---

Grant commands — caracal grant

All grant commands are zone-scoped. Grants authorize a specific application to access a resource on behalf of a user.

caracal grant list

caracal grant list

Table columns: id, application_id, user_id, resource_id, scopes, status, created_at

---

caracal grant get <id>

caracal grant get grant_stu901

---

caracal grant create

caracal grant create \
  --app app_def456 \
  --user user_vwx234 \
  --resource resource_ghi789 \
  --scopes "transfer:read,transfer:write"

Flag	Type	Default	Description
--app <id>	string	required	Application ID
--user <id>	string	required	User (subject) ID
--resource <id>	string	required	Resource ID
--scopes <a,b>	string	required	Comma-separated scopes

---

caracal grant revoke <id>

Revoke a grant. All active sessions derived from the grant become ineligible for new token exchanges.

caracal grant revoke grant_stu901

Output: revoked grant_stu901

---

Session commands — caracal session

Sessions are read-only from the CLI. Revoke access by revoking the underlying grant.

caracal session list

caracal session list
caracal session list --status active --limit 50
caracal session list --subject user_vwx234

Flag	Type	Default	Description
--status <s>	active|revoked|expired	—	Filter by status
--subject <id>	string	—	Filter by subject (user) ID
--limit <n>	integer	—	Maximum rows to return

Table columns: id, session_type, subject_id, status, expires_at, authenticated_at