Metadata-Version: 2.4
Name: phema
Version: 0.1.0
Summary: The Phema CLI — query your AI's customer-context failure map from any terminal.
Project-URL: Homepage, https://phema.ai
Project-URL: Documentation, https://phema.ai/docs
Author-email: Phema <justinallensf@gmail.com>
Keywords: ai,cli,customer-context,evals,phema
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.12
Requires-Dist: httpx>=0.27
Requires-Dist: typer>=0.12
Description-Content-Type: text/markdown

# 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

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

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

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