phema 0.1.0

The Phema CLI — query your AI's customer-context failure map from any terminal.

phema — the Phema CLI

Query your AI's customer-context failure map from any terminal. phema is a thin, published HTTPS client of the Phema read API (/api/v1). It authenticates with a workspace API key and renders human-readable output by default, with --json on every command for scripting, jq, and CI.

This is the customer CLI. It is a separate artifact from the internal operator CLI (phema-cli): it depends on nothing but httpx + typer, talks only over HTTPS, and ships to PyPI.

Install

uvx phema --help            # zero-install one-off
uv tool install phema       # or: pipx install phema / pip install phema

Authenticate

Mint a workspace API key in the Phema dashboard, then:

phema auth login            # prompts for the key (hidden), stores it in ~/.phema/config
phema auth whoami           # confirms the key authenticates
phema auth logout           # removes the stored key

The key resolves from PHEMA_API_KEY (environment, highest precedence) then the stored config file (written with 0600 permissions). Point the CLI at a non-default host with PHEMA_API_URL or phema auth login --api-url ....

Read commands

phema themes                          # list failure-mode themes
phema themes --theme-id <uuid>        # one theme's detail
phema failure-map --top-n 10          # severity-ranked coverage
phema cited-cases --theme-id <uuid>   # eval cases + citation chains
phema case-history --case-id <uuid>   # provenance / lineage
phema dispositions --view coverage    # triage / coverage surface

phema themes --json | jq '.themes[].label'   # --json on every command

Errors are honest, never silent

Situation	What you get
No key configured	Run \phema auth login`` (exit 2)
Key rejected (401)	invalid / revoked / expired → auth login (exit 2)
Plan not entitled (403)	"requires a paid plan (Signal or above)" (exit 3)
Rate limited (429)	retry hint with Retry-After (exit 4)
API unreachable	network / timeout message (exit 5)

Scope

Read-only. Export/download and generate/push are separate milestones.