CLI - Esheria

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.

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.

Install

pip install esheria

pipx install esheria

uvx --from esheria esheria health --format json

Configure

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

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

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"

$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"

Smoke Test

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.

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.

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.

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:

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:

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:

esheria --format json packs list
esheria packs list --format json

Supported output controls are:

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

esheria packs list --jurisdiction EU --readiness verified_published --format json

Check Applicability

esheria applicability check \
  UK-DATA-PROTECTION-PRIVACY \
  --role data_controller \
  --activity personal_data_processing \
  --limit 5 \
  --format json

Verify A Claim

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

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

​Install

​Configure

​Smoke Test

​Core Commands

​Additional Fact Surfaces

​Output Formats

​Examples

​List Packs

​Check Applicability

​Verify A Claim

​Troubleshooting

Install

Configure

Smoke Test

Core Commands

Additional Fact Surfaces

Output Formats

Examples

List Packs

Check Applicability

Verify A Claim

Troubleshooting