Rivendell CLI

The official command-line tool for AI coding agents and developer integrations. Same auth contract as the REST API; same tenancy as this dashboard.

Signing in mints an organization-scoped token, and only owners and admins may mint one. If you are a member rather than an owner, use the MCP connector instead: it authenticates you as yourself and reaches the same wearable data.

or read the markdown at /docs/cli.md

Install

The installer detects your OS/arch, downloads the matching binary from GitHub Releases, verifies the SHA-256, and drops it in ~/.local/bin. No sudo.

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

For a specific version:

curl -fsSL https://rivendell.health/cli/install.sh | sh -s -- v0.1.8

Also available via brew install rivendell-health/cli/rivendell and as a Docker image at ghcr.io/rivendell-health/cli on each release.

Authenticate

For agents and CI, the preferred path is the env var:

export RIVENDELL_TOKEN=riv_pat_…
rivendell whoami

Create the token at /developers/api-tokens. Tokens are scoped to your organization.

For interactive use, run the browser flow:

rivendell login
rivendell login --device-code # SSH/proxy fallback

The CLI stores credentials in your OS keyring (macOS Keychain, Windows Credential Manager, libsecret), with a mode-0600 file fallback at ~/.config/rivendell/credentials.json for headless Linux.

Scopes

Tokens carry a server-validated subset of these scopes. The closed list lives in code at lib/api-token-scopes.ts.

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

Tailing logs

rivendell logs tail streams the API audit log for your organization in real time over Server-Sent Events. Useful for debugging integration calls, watching webhook deliveries, or just confirming a tool is hitting the API at all.

rivendell logs tail
rivendell logs tail --surface http
rivendell logs tail --status 4xx --since 30m
rivendell logs tail --output json | jq '.path'

The stream auto-reconnects with Last-Event-Id on transient failures. Requires org:read. Request and response bodies are never streamed — only metadata.

Common commands

rivendell whoami
rivendell api GET  /api/cli/whoami
rivendell api POST /api/cli/foo --data '{"x":1}'
rivendell api POST /api/cli/foo --data @body.json
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 --surface http --status 4xx
rivendell wearables status
rivendell wearables sleep --days 7
rivendell wearables recovery --days 14 --provider oura
rivendell wearables activity --start-date 2026-09-01 --end-date 2026-09-08
rivendell wearables workouts --output json
rivendell logout
rivendell version --output json

Exit codes

The CLI's exit codes are part of the public contract; agents may branch on them.

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

For agents: the LLM-friendly summary lives at /llms.txt, and this CLI ships an agent skill at /docs/rivendell-cli-skill.md. Source for the CLI lives in the monorepo at cli/; design doc at docs/cli/design.md.