home / skills / openclaw / skills / roku

roku skill

safe

This skill lets you control Roku devices via CLI, offering discovery, remote commands, app launches, and a bridge for real-time operations.

npx playbooks add skill openclaw/skills --skill roku

Review the files below or copy the command above to add this skill to your agents.

Files (9)

SKILL.md

3.3 KB

---
name: roku
description: Control Roku devices via CLI. Discovery, remote control, app launching, search, and HTTP bridge mode for real-time control.
homepage: https://github.com/gumadeiras/roku-cli
repository: https://github.com/gumadeiras/roku-cli
metadata: {"clawdbot":{"emoji":"📺","requires":{"bins":["roku"]},"install":[{"id":"node","kind":"node","package":"roku-ts-cli","bins":["roku"],"label":"Install Roku CLI (npm)"}]}}
---

# Roku CLI

Fast TypeScript CLI for controlling Roku devices via the ECP API.

## Installation

```bash
npm install -g roku-ts-cli@latest
```

## Quick Start

```bash
# Discover devices and save an alias
roku discover --save livingroom --index 1

# Use the alias
roku --host livingroom device-info
roku --host livingroom apps
```

## Commands

| Command | Description |
|---------|-------------|
| `roku discover` | Find Roku devices on network |
| `roku --host <ip> device-info` | Get device info |
| `roku --host <ip> apps` | List installed apps |
| `roku --host <ip> command <key>` | Send remote key |
| `roku --host <ip> literal <text>` | Type text |
| `roku --host <ip> search --title <query>` | Search content |
| `roku --host <ip> launch <app>` | Launch app |
| `roku --host <ip> interactive` | Interactive remote mode |

## Interactive Mode

```bash
roku livingroom                    # interactive control
roku --host livingroom interactive # same thing
```

Use arrow keys, enter, escape for remote-like control.

## Bridge Service

Run a persistent HTTP bridge as a native OS service:

```bash
# Install and start the service
roku bridge install-service --port 19839 --token secret --host livingroom --user
roku bridge start --user

# Service management
roku bridge status --user
roku bridge stop --user
roku bridge uninstall --user
```

Send commands via HTTP:

```bash
# Send key
curl -X POST http://127.0.0.1:19839/key \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer secret" \
  -d '{"key":"home"}'

# Type text
curl -X POST http://127.0.0.1:19839/text \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer secret" \
  -d '{"text":"hello"}'

# Launch app
curl -X POST http://127.0.0.1:19839/launch \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer secret" \
  -d '{"app":"plex"}'

# Health check
curl http://127.0.0.1:19839/health -H "Authorization: Bearer secret"
```

### Bridge Endpoints

| Endpoint | Body |
|----------|------|
| `POST /key` | `{"key": "home"}` |
| `POST /text` | `{"text": "hello"}` |
| `POST /search` | `{"title": "Stargate"}` |
| `POST /launch` | `{"app": "plex"}` |
| `GET /health` | — |
| `GET /health?deep=1` | Deep health check (probes Roku) |

## Aliases

```bash
# Save device alias
roku discover --save livingroom --index 1
roku alias set office 192.168.1.20

# Save app alias  
roku alias set plex 13535

# List aliases
roku alias list

# Use aliases
roku --host livingroom launch plex
```

## Remote Keys

home, back, select, up, down, left, right, play, pause, rev, fwd, replay, info, power, volume_up, volume_down, mute

## Notes

- Roku must be on the same network as the CLI
- Bridge service runs as a native launchd (macOS) or systemd (Linux) service
- Use `--user` flag for user-space service (no sudo required)
- Use `--token` for authentication in bridge mode

## Source

https://github.com/gumadeiras/roku-cli

Overview

This skill provides a CLI for discovering and controlling Roku devices on your network. It supports device discovery, remote key commands, app launching, typed search, interactive remote mode, and a persistent HTTP bridge for real-time integrations. It is designed for local network automation, scripts, and service-based control workflows.

How this skill works

The CLI talks to Roku devices via the ECP (External Control Protocol) API over your local network. It can discover devices, save aliases for hosts and apps, send individual remote key events, type literal text, list installed apps, and launch apps. The bridge mode runs a local HTTP service that accepts authenticated requests to proxy commands in real time to a designated Roku device.

When to use it

Automate Roku controls from shell scripts or cron jobs
Control Roku devices from other apps via the HTTP bridge
Quickly discover and inspect Roku devices on a LAN
Use interactive mode for keyboard-based remote control
Run a persistent local service to expose Roku controls to home automation systems

Best practices

Keep Roku and controlling machine on the same subnet for reliable discovery
Use aliases for device IPs and app IDs to simplify commands
Secure the bridge with a strong token and run it in user-space when possible
Use the bridge health endpoints for monitoring and service checks
Prefer named app aliases to avoid remembering numeric app IDs

Example use cases

Save a device alias and launch a streaming app from a script: discover, alias, then launch plex
Run the bridge as a systemd or launchd service and control Roku via HTTP from a home automation controller
Use interactive mode to navigate Roku with arrow keys and enter from a terminal
Search for a show by title then launch the found app programmatically
Send periodic health checks from a monitoring tool to ensure the Roku remains reachable

FAQ

Does the Roku need to be on the same network as the CLI?

Yes. Discovery and ECP commands require the CLI or bridge to be on the same local network as the Roku device.

How do I secure the HTTP bridge?

Start the bridge with --token and use that token in the Authorization header. Run the bridge with --user to avoid system-wide privileges and limit exposure.