# Rivendell CLI

A single binary for scripting Rivendell and for agents that would rather run a
command than hold an HTTP client. Same auth contract and same tenancy as the
REST API.

## Install

```
brew install rivendell-health/cli/rivendell
```

```
curl -fsSL https://rivendell.health/cli/install.sh | sh
```

The script installs into `~/.local/bin` and verifies a SHA-256 checksum. Pin a
version by appending `-s -- v0.1.8`. A container image is published at
`ghcr.io/rivendell-health/cli`.

## Sign in

```
rivendell login
rivendell login --device-code   # no browser: SSH, or behind a proxy
rivendell whoami
```

A long-lived token works too, for CI and headless scripts:

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

**Who can use the CLI.** Signing in mints a token scoped to an organization, and
only an organization's owners and admins may mint one. If you are a member of a
team rather than an owner of it, use the MCP connector instead: it authenticates
you as yourself, and it reaches the same wearable data. See
https://rivendell.health/docs/mcp.md.

## Commands

- `rivendell login` — sign in through the browser
- `rivendell login --device-code` — sign in without a browser, over SSH or through a proxy
- `rivendell logout` — discard the stored token
- `rivendell whoami` — show who the current token belongs to
- `rivendell api` — call any REST endpoint directly
- `rivendell logs tail` — stream the API audit log live
- `rivendell wearables status` — show which wearables are connected and what they granted
- `rivendell wearables connect` — print the dashboard link for connecting a wearable
- `rivendell wearables sleep` — nightly sleep across every linked wearable
- `rivendell wearables recovery` — daily recovery and readiness scores
- `rivendell wearables activity` — daily training load, steps, and calories
- `rivendell wearables workouts` — individual training sessions
- `rivendell version` — print the version

Every command takes `--output json` for machine-readable output, and
`--token`, `--api-url` and `--verbose` are available everywhere. The
wearables commands take `--days`, or `--start-date` with `--end-date`, and
`--provider oura|whoop`.

## Token scopes

A token carries a server-validated subset of these. `rivendell login` requests
`org:read members:read wearables:read` unless you pass `--scope`.

- `org:read`
- `members:read`
- `members:write`
- `claims:read`
- `claims:write`
- `webhooks:read`
- `webhooks:write`
- `wearables:read`

## Exit codes

| Code | Meaning |
|---|---|
| 0 | success, HTTP 2xx or 3xx |
| 1 | network or pre-flight failure |
| 3 | reauthentication required: no token resolvable, or HTTP 401 |
| 4 | other client error: HTTP 403, 404, or another 4xx |
| 5 | server error, HTTP 5xx |

The exit codes are part of the public contract. Agents may branch on them.

## Notes

- `rivendell api` is the escape hatch: anything the REST API can do, it can do.
  The full API reference is at https://rivendell.health/api-docs, and the OpenAPI document at
  https://rivendell.health/openapi.json.
- This document lives at https://rivendell.health/docs/cli.md.