ring-cli

Execute ring operations using the `ring` CLI. All ring interactions should use this CLI — never hit the Ring API directly, never scrape the Ring web UI. The `ring` CLI follows this pattern: ```bash ring [arguments] [options] ```

Common task	Command
First-time login (prompts for email, password, 2FA)	ring auth login
List every device on the account	ring devices list --table
Show battery + wifi for one device	ring devices health "Front Door" --table
Recent motion events on one device	ring events list --device "Front Door" --kind motion --limit 20
Download the last 5 recordings	ring events download --device "Front Door" --recent 5
Grab a fresh snapshot	ring snapshot get --device "Front Door"
Turn motion detection on/off	ring motion enable --device "Front Door"
Floodlight on (stickup_cams only)	ring lights on --device "Driveway"
Sound the siren	ring siren on --device "Driveway" --duration 30
Test a chime	ring chime test --device "Downstairs" --kind ding
Set volume	ring volume set --device "Front Door" --value 7
</quick_start>

**MANDATORY: Consult the adjacent `usage.json` at `/_repo/skills/-cli/usage.json` before executing ANY `ring` command.** That file contains the full command tree (every argument, every option, every leaf usage_instruction). Do not guess flag names — read usage.json. Ring requires a 6-digit 2FA code on the first login from this CLI client (delivered via SMS/email at the moment `ring auth login` runs). The CLI prompts for it through the standard cli_tools_common prompting pipeline. After a successful exchange the OAuth token (with refresh) is cached in the profile data directory and reused on subsequent runs — no further prompts. Use `ring auth login --force` to clear the cached token and re-run the 2FA challenge. Every per-device command (events, snapshot, motion, lights, siren, chime, volume) accepts either the case-insensitive device name (e.g. `"Front Door"`) OR the numeric device ID returned by `ring devices list`. Names are matched exactly (case-insensitive) — partial matches are not supported. Ring Alarm arm/disarm (security panel mode home/away/disarmed) and motion-zone editing are NOT exposed by the underlying ring-doorbell library and are intentionally not part of this CLI. If a user asks for those, point them at the Ring mobile app and do not try to scrape the web UI. Default output is JSON on stdout for every read command. Pass `--table`/`-t` for a human-readable markdown table. Messages and prompts go to stderr. Pipe to `jq` for ad-hoc shaping. </essential_principles> | Group | Purpose | |-------|---------| | `auth` | Login (with 2FA prompt), logout, status, refresh, test. Supports profiles. | | `devices` | List / get / health for doorbells, cameras, chimes, intercoms. | | `events` | History (dings + motion + on-demand) — list, get, download. | | `snapshot` | List snapshot-capable devices; capture fresh JPEGs. | | `motion` | Toggle motion detection (enable/disable/status) per device. | | `lights` | Control floodlights on stickup_cams. | | `siren` | Sound / silence the siren on stickup_cams. | | `chime` | Play test sounds on Ring chimes. | | `volume` | Set device volume (0-10). | | `cache` | Manage the local response cache. | </command_groups> **`usage.json`** — Complete command tree with arguments, options, defaults, and usage_instructions for every command. Read before issuing any `ring` command. </reference_index> - Command executes without error (exit code 0) - Output is in the requested format (JSON by default, table with --table) - Correct command path and flags used, verified against usage.json - No direct Ring API calls, no Ring web scraping </success_criteria>