---
title: Admin Commands
description: Complete reference for zone, app, resource, provider, policy, policy-set, grant, and session commands — flags, API calls, and output formats.
pageType: reference
---

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.

```bash
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.

```bash
caracal zone get zone_abc123
```

---

### `caracal zone create`

Create a new zone.

```bash
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.

```bash
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.

```bash
caracal zone delete zone_abc123
```

Output: `deleted zone_abc123`

---

## Application commands — `caracal app`

All `app` commands are zone-scoped.

### `caracal app list`

```bash
caracal app list --zone zone_abc123
```

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

---

### `caracal app get <id>`

```bash
caracal app get app_def456
```

---

### `caracal app create`

```bash
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>`

```bash
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>`

```bash
caracal app delete app_def456
```

---

### `caracal app dcr`

Create an application via Dynamic Client Registration.

```bash
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`

```bash
caracal resource list
```

**Table columns:** `id`, `identifier`, `name`, `upstream_url`, `gateway_application_id`, `scopes`, `credential_provider_id`

---

### `caracal resource get <id>`

```bash
caracal resource get resource_ghi789
```

---

### `caracal resource create`

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

| 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 |
| `--gateway-application-id <id>` | string | required with `--upstream-url` | Gateway application identity for STS exchange |
| `--prefix` | boolean | `false` | Match identifier as a prefix |
| `--provider <id>` | string | — | Credential provider ID |

---

### `caracal resource patch <id>`

```bash
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>`

```bash
caracal resource delete resource_ghi789
```

---

## Provider commands — `caracal provider`

All `provider` commands are zone-scoped.

### `caracal provider list`

```bash
caracal provider list
```

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

---

### `caracal provider get <id>`

```bash
caracal provider get prov_jkl012
```

---

### `caracal provider create`

```bash
# 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>`

```bash
caracal provider patch prov_jkl012 --name "GitHub OAuth"
```

---

### `caracal provider delete <id>`

```bash
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`

```bash
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.

```bash
caracal policy get pol_mno345
```

---

### `caracal policy create`

```bash
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 template`

Use built-in policy templates as the default starting point.

```bash
caracal policy template list
caracal policy template get baseline-scopes
caracal policy template use baseline-scopes --name "Gateway Scope Policy"
```

| Form | Description |
| --- | --- |
| `template list` | Lists built-in templates such as `baseline-scopes`, delegation constraints, and step-up triggers |
| `template get <id>` | Prints the Rego content for inspection or editing |
| `template use <id>` | Creates a policy in the selected zone from the template |

`template use` accepts `--name`, `--description`, `--owner-type`, `--zone`, and `--json`.

---

### `caracal policy version <id>`

Add a new Rego version to an existing policy.

```bash
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).

```bash
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`

```bash
caracal policy-set list
```

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

---

### `caracal policy-set get <id>`

```bash
caracal policy-set get pset_pqr678
```

---

### `caracal policy-set create`

```bash
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.

```bash
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.

```bash
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.

```bash
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`

```bash
caracal grant list
```

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

---

### `caracal grant get <id>`

```bash
caracal grant get grant_stu901
```

---

### `caracal grant create`

```bash
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.

```bash
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`

```bash
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`
