reyna-cli/README.md

# Reyna CLI

On-demand CLI façade for Reyna family MCP services and LAN devices. The goal is to avoid keeping every MCP server/tool schema loaded in Hermes memory while still letting Hermes call capabilities through `terminal` when needed.

## Phase 2 scope

- **Devices parent command**: All local devices are now under `reyna-cli devices`.
  - `reyna-cli devices screen ...` (ESP32 screen)
  - `reyna-cli devices laptop ...` (personal laptop MCP screen)
  - `reyna-cli devices computer ...` (this computer's desktop companion client)
  - `reyna-cli devices iphone ...` (iPhone app)
  - `reyna-cli devices arm ...` (Robot arm)
- **Robot Arm**: Dynamic tool resolution for `state`, `home`, `wave`, `battery`.
- **Immich**: On-demand MCP bridge at `http://127.0.0.1:8626/mcp`.
- **MongoDB**: On-demand MCP bridge at `http://127.0.0.1:8630/mcp`.
- **Top-level aliases**: `reyna-cli screen`, `reyna-cli laptop`, `reyna-cli iphone`, `reyna-cli arm` still work for compatibility.

## Install / run

```bash
uv sync
uv run reyna-cli doctor
```

## Device discovery

```bash
uv run reyna-cli devices list --json
uv run reyna-cli devices ping esp32_screen --json
uv run reyna-cli devices tools esp32_screen --json
uv run reyna-cli devices describe esp32_screen --for-hermes
```

## Generic MCP calls

```bash
uv run reyna-cli devices call esp32_screen draw_text --args '{"text":"Hello","x":10,"y":20,"size":2}' --json
```

## Robot Arm

```bash
uv run reyna-cli devices arm state
uv run reyna-cli devices arm home
uv run reyna-cli devices arm wave
uv run reyna-cli devices arm battery --json
```

## ESP32 screen, laptop screen, this computer & iPhone

```bash
uv run reyna-cli devices screen text "Dinner is ready"
uv run reyna-cli devices laptop text "Hermes is online" --json
uv run reyna-cli devices laptop battery --json
uv run reyna-cli devices laptop sensors --json
uv run reyna-cli devices computer service-status --json
uv run reyna-cli devices computer text "Hermes is online here" --json
uv run reyna-cli devices iphone battery --json
```

## This computer desktop client service

The local desktop companion client runs `/home/adolforeyna/Projects/Screen/desktop_client/client.py` in the GUI session with `WAYLAND_DISPLAY=wayland-0` and `XDG_RUNTIME_DIR=/run/user/1000`.

```bash
uv run reyna-cli computer service-install --json
uv run reyna-cli computer service-start --json
uv run reyna-cli computer service-status --json
uv run reyna-cli computer service-restart --json
uv run reyna-cli computer service-logs --lines 80
```

## Immich

```bash
uv run reyna-cli immich stats
uv run reyna-cli immich albums
uv run reyna-cli immich search "sunset" --limit 5
uv run reyna-cli immich tools
```

## MongoDB

```bash
uv run reyna-cli mongo dbs
uv run reyna-cli mongo collections my_db
uv run reyna-cli mongo count my_db my_coll --filter '{"status":"active"}'
uv run reyna-cli mongo find my_db my_coll --limit 5
uv run reyna-cli mongo aggregate my_db my_coll --pipeline '[{"$match":{}}]'
```

## Local Thunderbird email (read-only)

The `email` command searches the locally synced Thunderbird MBOX files directly. It is read-only: it does not send, delete, move, label, or modify mail.

```bash
uv run reyna-cli email doctor --json
uv run reyna-cli email search "whirlpool fridge warranty" --limit 5 --json
uv run reyna-cli email find-receipts "Whirlpool" --json
uv run reyna-cli email latest --limit 10 --json
uv run reyna-cli email show <message-id> --body --json
```

By default it uses the local Thunderbird profile at `~/snap/thunderbird/common/.thunderbird/tjug9cp5.default` and the Gmail `INBOX` MBOX. Override with `REYNA_THUNDERBIRD_PROFILE` or `REYNA_THUNDERBIRD_INBOX` when testing or using a different profile.

## Mac mini

The `macmini` command reads the existing Hermes `mcp_servers.macmini` HTTP URL and Authorization header from `~/.hermes/config.yaml`, so credentials stay in the Hermes profile config instead of being duplicated here.

```bash
uv run reyna-cli macmini ping --json
uv run reyna-cli macmini tools --json
uv run reyna-cli macmini call notes_list --args '{"limit":5}' --json

uv run reyna-cli macmini calendar calendars --json
uv run reyna-cli macmini calendar events 2026-06-11T00:00:00 2026-06-12T00:00:00 --json
uv run reyna-cli macmini calendar create "Dentist" 2026-06-15T09:00:00 2026-06-15T10:00:00 --notes "Bring insurance card"

uv run reyna-cli macmini contacts search Adolfo --json
uv run reyna-cli macmini notes list --query family --json
uv run reyna-cli macmini reminders lists --json
```

## TP-Link Deco

The `deco` command talks directly to the router with `tplinkrouterc6u`; it does not use the Mac mini MCP server. Configure `DECO_HOST`, `DECO_USERNAME`, `DECO_PASSWORD`, `DECO_VERIFY_SSL`, and `DECO_TIMEOUT` in `~/.hermes/.env` or the process environment. `DECO_HOST` defaults to the Linux default gateway when omitted.

```bash
uv run reyna-cli deco config --json
uv run reyna-cli deco overview --json
uv run reyna-cli deco clients --json
uv run reyna-cli deco firmware --json
uv run reyna-cli deco ipv4 --json

# Backward-compatible alias; also direct, not MCP:
uv run reyna-cli macmini deco clients --json
```

## Browser web interface

`reyna-cli web` runs a FastAPI/uvicorn browser UI that can execute Reyna CLI commands from a browser. The web app uses Authentik OIDC by default against `auth.reynafamily.com`.

Create an Authentik OAuth2/OpenID provider/application for the web app and add a redirect URI that matches where you will browse to the server, for example:

```text
https://reyna-cli.reynafamily.com/auth/callback
```

Configure the server with environment variables (for example in `~/.hermes/.env` or your service manager):

```bash
REYNA_WEB_SESSION_SECRET='generate-a-long-random-string'
REYNA_WEB_AUTH_CLIENT_ID='authentik-client-id'
REYNA_WEB_AUTH_CLIENT_SECRET='authentik-client-secret'
REYNA_WEB_AUTH_ISSUER='https://auth.reynafamily.com/application/o/reyna-cli-web/'
REYNA_WEB_PUBLIC_URL='https://reyna-cli.reynafamily.com'
```

Run locally:

```bash
uv run reyna-cli web --host 127.0.0.1 --port 8765
```

For a trusted LAN-only development session, bypass OIDC with:

```bash
REYNA_WEB_DEV_AUTH=1 uv run reyna-cli web --host 127.0.0.1 --port 8765
```

## Tests

```bash
uv run pytest -q
```