---
name: rivendell-cli
description: Use this skill when you need to call the Rivendell health-platform API on behalf of a developer organization — creating members, submitting claims, listing webhooks, or any partner integration work. Triggers on "rivendell", "rivendell-cli", or when a token starting with "riv_pat_" is in scope.
---

# Rivendell CLI

The `rivendell` command is the official CLI for AI coding agents and developer
integrations against the Rivendell health-insurance platform. It authenticates
as a Rivendell `Organization` (not a member) and exposes the partner REST
surface plus a raw escape hatch for any authenticated endpoint.

## Install

```bash
# macOS / Linuxbrew (recommended for human developers)
brew install rivendell-health/cli/rivendell

# Universal (recommended for AI agents in fresh sandboxes)
curl -fsSL https://rivendell.health/cli/install.sh | sh

# Containers
docker pull ghcr.io/rivendell-health/cli:latest
```

The curl-pipe installer drops `rivendell` into `~/.local/bin` (no sudo).
The script verifies the SHA-256 against the release's `checksums.txt`
before installing.

## Authenticate

Two paths. **Pick env-var unless the agent is genuinely interactive.**

### Env var (preferred for agents)

```bash
export RIVENDELL_TOKEN=riv_pat_…
rivendell whoami
```

The token is created by a human at <https://rivendell.health/developers/api-tokens>.
Tokens carry server-defined scopes (see `Scopes` below) and are tied to one
Organization.

### Browser / device-code (interactive only)

```bash
rivendell login                # opens browser, captures the redirect on a loopback port
rivendell login --device-code  # SSH/proxy fallback — shows a pairing code to enter at /cli-auth/device
```

Stores the credential in the OS keyring (with a `~/.config/rivendell/credentials.json`
mode 0600 fallback for headless Linux).

## Scopes

Closed set, validated server-side. Tokens can hold any subset:

| Scope | What |
|---|---|
| `org:read` | Read your own organization profile |
| `members:read` | List/get member records |
| `members:write` | Create/update/remove member records |
| `claims:read` | Read claim records |
| `claims:write` | Submit and update claims |
| `webhooks:read` | List webhook endpoints |
| `webhooks:write` | Create/update/delete webhook endpoints |
| `wearables:read` | Read your own linked Oura and WHOOP data |

`wearables:read` is member-scoped rather than org-scoped: it reaches the token
owner's own devices and nobody else's.

Default `rivendell login` requests `org:read members:read wearables:read`.
Pass `--scope` to request a different set, e.g. to narrow a token meant for
scripting.

## Who can sign in

Signing in mints an organization-scoped token, and only an organization's owners
and admins may mint one. A member who is not an admin cannot use this CLI at
all; they should add the MCP connector instead, which authenticates them as
themselves and reaches the same wearable data. See
https://rivendell.health/docs/mcp.md.

## Top commands

```bash
rivendell whoami                                   # confirm auth + active org + scopes
rivendell api GET  /api/cli/whoami                 # raw escape hatch
rivendell api POST /api/cli/foo --data '{"x":1}'   # JSON body
rivendell api POST /api/cli/foo --data @body.json  # body from file
rivendell api POST /api/cli/foo --data @-          # body from stdin
rivendell api GET  /api/foo --query limit=10 --header "X-Trace: abc" --include
rivendell logs tail                                # stream API call audit log
rivendell logs tail --surface http --status 4xx    # filtered tail
rivendell logs tail --output json | jq '.path'     # JSON for machine reading
rivendell logout                                    # remove the local credential
rivendell version --output json                     # build metadata
```

`logs tail` requires `org:read`. It reconnects automatically with
`Last-Event-Id` on transient failures. The stream emits `event: ping`
keepalives every ~30s and exits cleanly on Ctrl-C.

## Output and exit codes

- Default output is pretty JSON when stdout is a terminal, raw JSON when piped
  (matches `gh`, `resend`, `ramp`).
- Override with `--output json|text`.
- Set `RIVENDELL_FORCE_TTY=1` to force human mode in CI debugging.

Exit codes (the contract — agents may rely on these):

| Code | Meaning |
|---|---|
| `0` | Success (HTTP 2xx/3xx) |
| `3` | Reauth required: no token resolvable, or HTTP 401 |
| `4` | Other client error (HTTP 403, 404, 4xx) — token valid, request rejected |
| `5` | Server error (HTTP 5xx) |
| `1` | Network or pre-flight failure |

A `3` always means "ask the human to run `rivendell login` or refresh
`RIVENDELL_TOKEN`". A `4` means "fix the request"; reauth doesn't help.

## Things agents must NOT do

- **Never log the token.** Don't echo `$RIVENDELL_TOKEN`, don't include
  `Authorization` headers in commit messages, don't paste them into Slack,
  GitHub issues, or chat transcripts. Tokens in the wild get auto-revoked.
- **Never destructive-write without explicit user confirmation.** If a flow
  hits `DELETE`, `revoke`, or anything `*:write`-scoped, ask the user
  ("about to revoke webhook `wh_…`, ok?") before sending.
- **Never `--token` on the command line in a way that ends up in history**.
  Use the env var. The CLI prints a warning when `--token` is used so you
  can flag it back to the human.
- **Don't loop the API**. Use cursor pagination (`?cursor=...`) when the
  response carries `next_cursor`. Don't re-fetch the same page on a 4xx.

## Discovery URLs

These help the agent stay current without requiring this SKILL.md to be
exhaustive:

- API capabilities: <https://rivendell.health/api/capabilities>
- OpenAPI: <https://rivendell.health/openapi.json>
- LLM index: <https://rivendell.health/llms.txt>
- Full LLM reference: <https://rivendell.health/llms-full.txt>
- Developer dashboard: <https://rivendell.health/developers>
- Design doc (open-source): `cli/README.md` and `docs/cli/design.md` in
  the repo