> ## Documentation Index
> Fetch the complete documentation index at: https://docs.esperr.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Policies

> Compose actions, entities, and mitigations into evaluation rules.

## List policies

```bash theme={null}
esper policy list
esper policy list --status active  # Filter by status
```

## Create policy

```bash theme={null}
esper policy create \
  --name "Login Policy" \
  --description "Evaluate login traffic by actor." \
  --field request_path \
  --operator Eq \
  --value /login \
  --action login-action \
  --entity login-actor
```

This creates a single-clause policy, writes
`~/.esper/data/policies/login-policy.json`, and submits it to Esper.
`--action`, `--entity`, and `--mitigation` accept UUIDs or local data names.
Use `--file` for multi-clause or advanced policy payloads.

## Apply policy (idempotent)

```bash theme={null}
esper policy apply --file ./policy.json
```

The `apply` command creates or updates based on `policy_id` presence in the JSON:

* With `policy_id`: Updates existing policy
* Without `policy_id`: Creates new policy

<Tip>
  **Best Practice**

  Use `apply` in CI/CD pipelines for declarative policy management.
</Tip>

## Update policy

```bash theme={null}
esper policy update --file ./policy-update.json
```

## Delete policy

```bash theme={null}
esper policy delete <policy-id>
```

## Common Workflows

### Deploy new policy set

```bash theme={null}
# 1. Validate current state
esper policy list

# 2. Apply policies declaratively
esper policy apply --file policies/rate-limiting.json
esper policy apply --file policies/authentication.json

# 3. Verify deployment
esper results policies
```

### Rollback policy change

```bash theme={null}
# 1. Export current policy
esper policy show <policy-id> --output json > policy-backup.json

# 2. Make changes
esper policy update --file policy-new.json

# 3. If issues, restore
esper policy apply --file policy-backup.json
```