rokit

A tiny CLI companion for Roku device harness work.

Install

pnpm add -D @putdotio/rokit

rokit wraps Roku platform primitives for live-device proof loops. It does not own app-specific journeys, content IDs, credentials, or product assertions.

Usage

Create .rokit/.env or export environment variables in the app repo:

ROKIT_TARGET=<roku-ip>
ROKIT_PASSWORD=<developer-mode-password>

Then run:

pnpm exec rokit check
pnpm exec rokit launch dev
pnpm exec rokit press Down Select
pnpm exec rokit press --delay-ms 250 Right Select
pnpm exec rokit query /query/active-app
pnpm exec rokit wait-node videoPlayerScreen visible
pnpm exec rokit screenshot artifacts/live/player.png
pnpm exec rokit --json active-app

App-specific scenario scripts can also import the generic helpers:

import {
  assertNamedNodeState,
  assertNamedNodeTranslation,
  assertSceneGraphNode,
  pressKey,
  querySceneGraph,
  waitForSceneGraphAssertion,
  type RokuContext,
} from "@putdotio/rokit";

const target = process.env.ROKIT_TARGET;

if (!target) {
  throw new Error("ROKIT_TARGET is not set");
}

const context: RokuContext = {
  target,
  timeoutMs: 10_000,
  username: "rokudev",
};

await pressKey(context, "Info");
const xml = await querySceneGraph(context, { attempts: 3 });
await assertSceneGraphNode(context, "videoPlayerScreen", { state: "visible" });
assertNamedNodeTranslation(xml, "videoPlayerScreen", 0, 0);
await waitForSceneGraphAssertion(context, "expected player", (xml) => {
  assertNamedNodeState(xml, "videoPlayerScreen", "visible");
});

Commands

rokit check
rokit device-info
rokit active-app
rokit wait-active <app-id> [--timeout-ms <ms>]
rokit launch <app-id> [--param key=value]
rokit press [--delay-ms <ms>] <key> [key...]
rokit query <ecp-path>
rokit sgnodes
rokit assert-node <node-name> <visible|hidden|absent|text|attr> [value]
rokit wait-node <node-name> <visible|hidden|absent|text|attr> [value] [--timeout-ms <ms>]
rokit screenshot <output-path>
rokit install <zip-path>
rokit --version

Global options:

rokit --json <command>
rokit --output json <command>

JSON mode wraps command output as { "status": "ok", "command": "...", ... } and reports failures as { "status": "failed", "error": { "message": "..." } }.

• check confirms the Roku ECP endpoint responds and the developer installer is reachable.
• device-info prints enhanced Roku device metadata as JSON.
• active-app prints the foreground app.
• wait-active waits until the requested app is foregrounded and tolerates transient ECP read failures while polling.
• launch opens an app and waits until it is active. Use repeated --param values for deeplink parameters. Roku launch responses can race app startup, so launch accepts transient timeout/fetch failures and then verifies foreground state.
• press sends Roku remote keys through ECP. Use --delay-ms for navigation sequences that need a stable gap between keys.
• query prints a raw ECP response such as /query/sgnodes/all.
• sgnodes prints the raw SceneGraph tree from /query/sgnodes/all. Library callers can pass retry options to querySceneGraph.
• assert-node checks a named SceneGraph node once.
• wait-node polls SceneGraph until a named node condition matches.
• screenshot saves a developer screenshot. It requires ROKIT_PASSWORD.
• install publishes an existing ZIP through roku-deploy. It requires ROKIT_PASSWORD.

Environment

ROKIT_TARGET=<roku-ip>
ROKIT_PASSWORD=<developer-mode-password>
ROKIT_USERNAME=rokudev
ROKIT_TIMEOUT_MS=10000

ROKU_DEV_TARGET and ROKU_DEV_PASSWORD are accepted as fallbacks for app repos that already use Roku dev naming.

Keep .rokit/ local. Device IPs, Developer Mode passwords, signing keys, user tokens, and app-specific media identifiers do not belong in git.

Boundaries

rokit is the generic Roku harness layer:

• device info
• install/publish
• launch and deeplink parameters
• remote keypresses
• raw ECP queries
• SceneGraph state queries and named-node assertions
• SceneGraph attribute, numeric geometry, bounds, and translation readers
• SceneGraph geometry assertions, status/failure readers, and custom assertion wait loops
• screenshots

App repositories should keep their own scenario commands for product behavior, such as opening a specific route, asserting playback state, generating review HTML, or checking app-specific UI nodes.

Docs

• Contributing
• Distribution
• Agent readiness
• Security

Repo Internals

• Agent guide

License

MIT