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

# CLI

> Install and use the esheria command-line interface for API smoke checks and regulatory pack workflows.

The `esheria` CLI is a thin client over the public Regulatory Pack API. It does not read Postgres, S3, pipeline artifacts, or internal evidence folders directly.

The CLI is catalog-first and multi-jurisdictional. It never selects Kenya or
any other jurisdiction implicitly: discover packs, inspect readiness, and pass
the chosen pack ID to pack-specific commands.

Version `1.2.2` is production/stable. The distributed CLI, Python client, and
MCP software are Apache-2.0 licensed. Hosted services, regulatory data,
outputs, and Esheria trademarks remain subject to the Esheria Terms of Service,
Privacy Policy, and customer agreements.

<Info>
  Preserve readiness labels, limitations, citations, and trace IDs in
  downstream workflows. Esheria output is regulatory intelligence, not legal
  advice or a substitute for qualified counsel.
</Info>

## Install

<CodeGroup>
  ```bash pip theme={null}
  pip install esheria
  ```

  ```bash pipx theme={null}
  pipx install esheria
  ```

  ```bash uvx theme={null}
  uvx --from esheria esheria health --format json
  ```
</CodeGroup>

## Configure

Create a self-serve data token in the dashboard first:

1. Open `https://dashboard.esheria.ai/`.
2. Sign up or sign in.
3. Create a token from **API Tokens**.
4. Store the one-time token secret as `ESHERIA_API_KEY`.

<CodeGroup>
  ```bash macOS/Linux theme={null}
  export ESHERIA_API_BASE_URL="https://api.esheria.ai"
  export ESHERIA_API_KEY="YOUR_DASHBOARD_CREATED_DATA_TOKEN"
  export ESHERIA_TIMEOUT_SECONDS="30"
  export ESHERIA_RETRY_COUNT="2"
  ```

  ```powershell Windows PowerShell theme={null}
  $env:ESHERIA_API_BASE_URL = "https://api.esheria.ai"
  $env:ESHERIA_API_KEY = "YOUR_DASHBOARD_CREATED_DATA_TOKEN"
  $env:ESHERIA_TIMEOUT_SECONDS = "30"
  $env:ESHERIA_RETRY_COUNT = "2"
  ```
</CodeGroup>

## Smoke Test

```bash theme={null}
esheria --version
esheria health --format json
esheria ready --format json
esheria packs list --format json
export ESHERIA_PACK_ID="UK-DATA-PROTECTION-PRIVACY"
esheria packs inspect "$ESHERIA_PACK_ID" --format json
esheria obligations list "$ESHERIA_PACK_ID" --limit 3 --format json
```

Use `esheria packs list --jurisdiction EU`, `--jurisdiction SG`, or another
catalog value to select a different jurisdiction. See the
[complete production catalog](/guides/pack-catalog).

## Core Commands

| Workflow                       | Command                                                                                                     |
| ------------------------------ | ----------------------------------------------------------------------------------------------------------- |
| Health                         | `esheria health`                                                                                            |
| Readiness                      | `esheria ready`                                                                                             |
| Diagnostics                    | `esheria doctor --pack "$ESHERIA_PACK_ID"`                                                                  |
| Pack discovery                 | `esheria packs list`                                                                                        |
| Pack inspection                | `esheria packs inspect "$ESHERIA_PACK_ID"`                                                                  |
| Pack export                    | `esheria packs export "$ESHERIA_PACK_ID" --out pack.json`                                                   |
| Obligations                    | `esheria obligations list "$ESHERIA_PACK_ID" --limit 25`                                                    |
| Applicability                  | `esheria applicability check "$ESHERIA_PACK_ID" --role data_controller --activity personal_data_processing` |
| Claim verification             | `esheria claims verify --pack "$ESHERIA_PACK_ID" "..."`                                                     |
| Filing calendar                | `esheria calendar list "$ESHERIA_PACK_ID"`                                                                  |
| Evidence register              | `esheria evidence list "$ESHERIA_PACK_ID"`                                                                  |
| Citation context               | `esheria citations get "$ESHERIA_PACK_ID" --citation-id CITATION_ID`                                        |
| Relationships                  | `esheria relationships list "$ESHERIA_PACK_ID"`                                                             |
| Graph query                    | `esheria graph query --pack "$ESHERIA_PACK_ID"`                                                             |
| Graph projection               | `esheria graph rebuild-projection --reason scheduled_rebuild --yes`                                         |
| Graph coverage                 | `esheria graph coverage --domain-pack-id "$ESHERIA_PACK_ID"`                                                |
| Source watches                 | `esheria monitoring watches --domain-pack-id "$ESHERIA_PACK_ID"`                                            |
| Source currentness             | `esheria monitoring currentness --domain-pack-id "$ESHERIA_PACK_ID"`                                        |
| Source check                   | `esheria monitoring check --domain-pack-id "$ESHERIA_PACK_ID" --yes`                                        |
| Recompile candidates           | `esheria monitoring recompile-candidates --domain-pack-id "$ESHERIA_PACK_ID"`                               |
| Customer lifecycle preview     | `esheria customers preview --pack "$ESHERIA_PACK_ID" --role data_controller`                                |
| Customer profiles              | `esheria customers profiles`                                                                                |
| Customer profile inspection    | `esheria customers inspect-profile CUSTOMER_PROFILE_ID`                                                     |
| Customer applicability         | `esheria customers run-applicability CUSTOMER_PROFILE_ID --pack "$ESHERIA_PACK_ID"`                         |
| Customer applicability history | `esheria customers applicability-runs CUSTOMER_PROFILE_ID`                                                  |
| Customer obligations           | `esheria customers obligations --customer-profile-id CUSTOMER_PROFILE_ID`                                   |
| Customer impacts               | `esheria customers impacts --customer-profile-id CUSTOMER_PROFILE_ID`                                       |
| Token list                     | `esheria tokens list`                                                                                       |
| Token creation                 | `esheria tokens create --name "Production data token" --pack "$ESHERIA_PACK_ID"`                            |
| Token revocation               | `esheria tokens revoke TOKEN_ID`                                                                            |
| Credit balance                 | `esheria billing balance`                                                                                   |
| Usage ledger                   | `esheria billing usage --limit 25`                                                                          |
| Billing catalog                | `esheria billing plans`                                                                                     |
| Checkout                       | `esheria billing checkout --sku-id developer-topup-1000`                                                    |
| Subscription state             | `esheria billing subscription`                                                                              |
| Workspace settings             | `esheria workspace show`                                                                                    |

The dashboard remains the recommended UI for signup, one-time token reveal,
usage review, billing checkout, subscription state, and workspace settings.

<Warning>
  Dashboard-created data tokens and OAuth connector tokens are read-only.
  Workspace, token, billing, and subscription CLI commands require a management
  token. Do not put management tokens in browser code, shared shell profiles,
  CI logs, or agent-host configuration.
</Warning>

Commands that create/check source watches, rebuild graph projections, or update
persisted customer lifecycle state change hosted data. They require
`monitoring:write`, `graph:write`, or `customer:write` respectively;
`regulatory:read` alone is rejected. Create a least-privilege operator token
with a management token:

```bash theme={null}
esheria tokens create --name "Monitoring operator" \
  --scope regulatory:read --scope monitoring:write \
  --pack UK-DATA-PROTECTION-PRIVACY
```

## Additional Fact Surfaces

The CLI also wraps canonical fact surfaces for versions, diffs, change events,
penalties, and legal review audit. The equivalent API calls are:

```bash theme={null}
curl --compressed -sS \
  "$ESHERIA_API_BASE_URL/api/v1/domain-packs/$ESHERIA_PACK_ID/versions?limit=10" \
  -H "x-api-key: $ESHERIA_API_KEY" | jq

curl --compressed -sS \
  "$ESHERIA_API_BASE_URL/api/v1/domain-packs/$ESHERIA_PACK_ID/diff?from_version=$FROM_VERSION&to_version=$TO_VERSION" \
  -H "x-api-key: $ESHERIA_API_KEY" | jq

curl --compressed -sS \
  "$ESHERIA_API_BASE_URL/api/v1/domain-packs/$ESHERIA_PACK_ID/change-events?from_version=$FROM_VERSION&to_version=$TO_VERSION&limit=25" \
  -H "x-api-key: $ESHERIA_API_KEY" | jq

curl --compressed -sS \
  "$ESHERIA_API_BASE_URL/api/v1/domain-packs/$ESHERIA_PACK_ID/penalty-facts?limit=25" \
  -H "x-api-key: $ESHERIA_API_KEY" | jq

curl --compressed -sS \
  "$ESHERIA_API_BASE_URL/api/v1/domain-packs/$ESHERIA_PACK_ID/legal-review-audit?limit=25" \
  -H "x-api-key: $ESHERIA_API_KEY" | jq
```

## Output Formats

Output flags can appear before the command or on the leaf command:

```bash theme={null}
esheria --format json packs list
esheria packs list --format json
```

Supported output controls are:

```text theme={null}
--format table
--format json
--format yaml
--format ndjson
--raw
--envelope
```

Use `--envelope` when you need the full API envelope. Use `--raw` when you want the returned payload without table formatting.

## Examples

### List Packs

```bash theme={null}
esheria packs list --jurisdiction EU --readiness verified_published --format json
```

### Check Applicability

```bash theme={null}
esheria applicability check \
  UK-DATA-PROTECTION-PRIVACY \
  --role data_controller \
  --activity personal_data_processing \
  --limit 5 \
  --format json
```

### Verify A Claim

```bash theme={null}
esheria claims verify \
  --pack UK-DATA-PROTECTION-PRIVACY \
  "A controller must respond to data subject rights requests." \
  --format json
```

The last command may return `unsupported_capability` when the selected pack has
no enabled claim evaluator. That does not affect obligations, applicability,
calendar, evidence, penalties, relationships, or export for the pack.

## Troubleshooting

| Symptom                                | Likely cause                              | Fix                                                                |
| -------------------------------------- | ----------------------------------------- | ------------------------------------------------------------------ |
| `esheria` opens SSH or another program | Shell alias shadows the installed command | Run `type -a esheria`, then remove or rename the alias             |
| `Invalid API key`                      | Missing or wrong `ESHERIA_API_KEY`        | Re-export the key and retry `esheria packs list`                   |
| `credits_exhausted`                    | Workspace credit balance is empty         | Run `esheria billing balance` and create a top-up checkout session |
| `billing_unavailable`                  | Billing ledger is not reachable           | Retry after the API operator restores ledger availability          |
| Request hangs                          | Wrong base URL or network issue           | Test `curl "$ESHERIA_API_BASE_URL/healthz"`                        |
| `unsupported_capability`               | The pack does not support that workflow   | Use generic pack endpoints or choose another pack                  |

<Info>
  Repository-local wrappers remain available as `bin/esheria` and `bin/esheria-mcp` for contributors working from a checkout.
</Info>