Package Exports

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (roku-ts-cli) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

Roku CLI

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

Highlights

Full ECP control (keys, text, search, apps, device info, media state).
Interactive mode for remote-like control from the terminal.
Local bridge mode for other apps to send commands over HTTP.
SSDP discovery, emulator server, and proxy tools.
Strong typing, retries, timeouts, and better error handling.

Requirements

Node 18+ (Node 20+ recommended)

Install (recommended)

npm install -g roku-ts-cli@latest

# or install locally for development
npm install
npm run build
npm link

Quick Start

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

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

CLI Usage

# Direct host (fast, no SSDP)
roku 192.168.1.118

# Commands
roku --host livingroom command home
roku --host livingroom literal "hello"
roku --host livingroom search --title "Stargate"

# App lookup / aliases
roku --host livingroom search --app plex
roku alias set plex 13535
roku --host livingroom launch plex

Interactive Mode

# Interactive control
roku livingroom

# With local command port
roku --host livingroom interactive --listen 19839 --token secret

Bridge Mode (Local HTTP)

roku --host livingroom bridge --listen 19839 --token secret

Send commands from other apps:

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

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

Endpoints:

POST /key { "key": "home" }
POST /text { "text": "hello" }
POST /search { "title": "Stargate" }
POST /launch { "app": "plex" }
GET /health
GET /stats

Run Bridge as a Service

You can run the bridge in the background using your OS service manager.

macOS + Linux (user service)

Install and manage the service entirely through the CLI (no manual plist/unit edits needed):

# Install service file
roku bridge install-service --port 19839 --token YOUR_TOKEN --host YOUR_HOST_OR_ALIAS --user

# Start/stop/restart
roku bridge start --port 19839 --token YOUR_TOKEN --host YOUR_HOST_OR_ALIAS --user
roku bridge stop --user
roku bridge restart --port 19839 --token YOUR_TOKEN --host YOUR_HOST_OR_ALIAS --user

# Status + logs (+ optional health probe if port/token provided)
roku bridge status --user
roku bridge status --port 19839 --token YOUR_TOKEN

# Diagnose service issues (shows paths + logs, token redacted)
roku bridge diagnose --user

# Uninstall
roku bridge uninstall --user

Emulator & Proxy

# Local emulator (HTTP + SSDP)
roku server --port 8060

# Forward requests to a real Roku
roku proxy --remote-host 192.168.1.10 --local-port 8061

Library Usage

import { Roku } from "roku-ts-cli";

const roku = new Roku("192.168.1.10");
const apps = await roku.getApps();
await roku.home();

Tests

npm run build
npm test

License

MIT