rk device

Summary

Manage and query Roku devices, including Roku Cloud Emulator (RCE) devices.

Description

Manage the device list, select the active device, and query or control a device. Roku Cloud Emulator (RCE) devices are named with an rce: prefix and have their own commands for starting, stopping, snapshots and remote input. The lease and pool subverb trees share devices across parallel jobs through a device pool.

Usage

rk device <subcommand> [options]
rk device <subcommand-tree> [options]

Environment variables

All documented variables are listed on rk environment variables.

add

Summary

Add or update a LAN device, or register an existing Roku Cloud Emulator device.

Description

Adds or updates a device in the canonical device list store (home preferred; legacy local fallback). It validates the IP, generates a stable id from the IP and optional name unless --id is given, and de-duplicates by id and IP. The first device added becomes active when no device is active. A name starting with rce: is refused with DEVICE_NAME_RESERVED. With --rce it registers a device that already exists in the RCE organisation, together with the snapshot rk dev starts it from; registrations are saved in ~/roku-rce-devices.json and registering does not make the device active.

Usage

rk device add <ip> [--name <n>] [--id <id>] [--tag <t> ...] [--json]
rk device add --rce <name|id> --snapshot <name|id> [--firmware <id|name>] [--max-runtime <s>] [--password-stdin] [--json]

Options

--name

Display name for the device.

--id

Device id to use instead of the one generated from the IP and name.

--tag

Tag to add to the device. Repeat the flag for several tags; duplicates are removed.

--snapshot

With --rce, the snapshot rk dev starts the device from. Required for --rce; it has to be ready and not the device's base snapshot.

--firmware

With --rce, the firmware rk device start and rk dev --start use by default.

--max-runtime

With --rce, the maximum runtime in seconds rk device start and rk dev --start use by default.

--password-stdin

With --rce, save the device's developer (rokudev) password, read from stdin: a hidden prompt at a terminal, else the first line of the pipe. The password is never an argument.

--rce

Register the existing Roku Cloud Emulator device with this name or id.

--json

Print the added device, and whether it became the active device, as JSON.

Examples

rk device add 192.168.1.10 --name Office
rk device add --rce my-tv --snapshot dev-ready --password-stdin

See also

• addDevice (POST /api/devices)
• add_device

check-update

Summary

Trigger a firmware update check on the target Roku device.

Description

Sends POST /plugin_swup with mysubmit=CheckUpdate, using the device password from the device store. Prints a clear error when no password is configured for the selected device. Requires firmware 15.0.4 or later.

Usage

rk device check-update [<id|ip|name>] [--json]

Options

--json

Print a machine-readable success or error payload.

See also

• checkDeviceUpdate (POST /api/devices/check-update)
• device_check_update

clear-active

Summary

Clear the active device pointer.

Description

Clears the active device pointer, so no device is active afterward.

Usage

rk device clear-active

See also

• listDevices (GET /api/devices)
• clearActiveDevice (POST /api/devices/clear-active)
• clear_active_device

clear-rce-token

Summary

Remove the saved Roku Cloud Emulator token.

Description

Removes the RCE token saved by rk device set-rce-token.

Usage

rk device clear-rce-token

create

Summary

Create a device in the Roku Cloud Emulator organisation.

Description

Creates a device in the RCE organisation. RCE cannot delete devices, so a device you create counts against the organisation's device quota for good; create therefore asks first. --yes skips the question, and without a terminal and without --yes it refuses. It prints the steps that turn the new device into one rk dev can use.

Usage

rk device create --rce <name> --type tv|stb [--note <text>] [--account-name <email>] [--property key=value ...] [--yes] [--json]

Options

--rce

Name of the device to create.

--type

Device type.

--note

Note to set on the new device.

--account-name

Account name to set on the new device.

--property

Property to set on the new device. Repeat the flag for several properties.

Example:

rk device create --rce my-tv --type tv --property team=sdk --property lab=austin

--yes

Create the device without asking first.

--json

Print the result as JSON.

Examples

rk device create --rce my-tv --type tv

dev-id

Summary

Print the keyed developer ID registered on the target Roku device.

Description

Queries GET /query/device-info through the existing ECP path and reads the keyed-developer-id field. Returns null when the field is missing or empty, and exits non-zero when the device cannot be reached or the query fails.

Usage

rk device dev-id [<id|ip|name>] [--json]

Options

--json

Print { devId } as JSON.

See also

• getDeviceDevId (POST /api/devices/dev-id)
• get_device_dev_id

dev-settings

Summary

Open the Developer Settings screen on a Roku Cloud Emulator device.

Description

Opens the firmware's Developer Settings screen with the remote combo, where the installer is enabled and its password set.

Usage

rk device dev-settings [rce:<name>] [--json]

Options

--json

Print the result as JSON.

Examples

rk device dev-settings rce:my-tv

firmware

Summary

List the firmware versions Roku Cloud Emulator offers.

Description

Lists the firmware versions RCE offers, for one device type or all of them.

Usage

rk device firmware ls [--type tv|stb|streambar] [--json]

Options

--type

Only list firmware for this device type.

--json

Print { firmware } as JSON.

Examples

rk device firmware ls --type tv

forward

Summary

Make device ports reachable from this machine.

Description

For a Roku Cloud Emulator device, opens a 127.0.0.1 listener for each device port and holds them until Ctrl-C or until the run ends, so other tools can reach the device as if it were local. RCE bridges ports 8080, 8081, 8082, 8085, 8087, 9999 and 49152-65535; any other port is refused with RCE_PORT_NOT_ALLOWED before anything is opened. The listener takes no credentials. For a LAN device the host:port is printed and the command exits.

Usage

rk device forward <device> <port...> [--json]

Options

--json

Print the result as JSON.

Examples

rk device forward rce:my-tv 8085 9999

get-screenshot-dir

Summary

Get the default screenshot output directory.

Description

Prints the default screenshot output directory.

Usage

rk device get-screenshot-dir [--json]

Options

--json

Print the directory as JSON.

info

Summary

Get device information (not yet implemented).

Description

Not yet implemented: prints a TBD message.

Usage

rk device info

input

Summary

Send remote keys to a Roku Cloud Emulator device through RCE.

Description

Sends remote keys through RCE itself, without ECP or developer mode, so it drives guided setup and the Developer Settings screen as well as an app. press sends keys, down holds a key and up releases it; ready reports whether the device accepts input, and --wait waits until it does. --text types each character as a literal key and cannot send a slash.

Usage

rk device input [rce:<name>] press|down|up <key...> [--delay <ms>] [--json]
rk device input [rce:<name>] --text "<text>" [--delay <ms>] [--json]
rk device input [rce:<name>] ready [--wait] [--json]

Options

--text

Type this text, one literal key per character.

--delay

Pause between keys, in whole milliseconds.

Example:

rk device input rce:my-tv press Down Down Select --delay 250

--wait

With ready, wait until the device accepts input.

--json

Print the result as JSON.

Examples

rk device input rce:my-tv press Home Down Select
rk device input rce:my-tv down Right
rk device input rce:my-tv ready --wait

ip

Summary

Print the IP address of the active device.

Description

Prints the active device's IP address. With no active device, or an active Roku Cloud Emulator device (which has no IP), it prints an error and exits non-zero.

Usage

rk device ip [--json]

Options

--json

Print { ip } as JSON, without banner text.

See also

• getActiveDeviceIp (GET /api/devices/active/ip)
• get_device_ip

lease acquire

Summary

Acquire a device lease from the configured device pool.

Description

Resolves a free device from the configured pool, writes a lease file to <lease-dir>/<leaseId>.json and prints its id. Exits 1 on a resolver or provider error.

Usage

rk device lease acquire [--pool <kind>] [--profile <name>] [--target <id|ipv4|name>] [--tag <t> ...] [--require-fw <semver>] [--ttl <seconds>] [--purpose <text>] [--lease-dir <path>] [--password-ref <ref>] [--force] [--json]

Options

--pool

Provider kind to route through: local or a custom kind registered with registerDeviceProvider.

--profile

Profile name from .roku/profiles.json.

--ttl

Lease TTL in seconds.

Example:

rk device lease acquire --ttl 900 --tag ci

--target

Pin to a specific device: a configured device id or name, or a raw IPv4 literal. For the local pool, an IPv4 that is not configured is acquired as an ephemeral device.

Example:

rk device lease acquire --target 192.168.1.42

--tag

Required tag. Repeat the flag to require several tags; comma-separated lists are not parsed.

--purpose

Free-form caller annotation written into the lease for triage.

--require-fw

Strict-equality firmware pin. Range syntax is not supported.

--lease-dir

Directory the lease files live in.

--force

Opt into one-shot sticky-state recovery on a busy candidate before declaring it un-acquirable. CI fallback only: from an interactive shell it can kill a developer's sideloaded session. The local provider ignores it.

--password-ref

Pin the lease's passwordRef to a caller-supplied reference such as env:NAME. literal:VALUE is allowed only on the local pool with RK_ALLOW_LITERAL_PASSWORD=1.

Example:

rk device lease acquire --password-ref env:LAB_TV_PASSWORD

--json

Print the lease as JSON, with passwordRef redacted.

Examples

rk device lease acquire --pool local --ttl 600

Environment variables

All documented variables are listed on rk environment variables.

lease reap

Summary

Release expired or corrupt leases in the lease directory.

Description

Scans the lease directory: a corrupt or malformed lease file is deleted, an expired lease is released through its owning provider, and a live lease is skipped. Each lease is routed through the providerKind in its own file.

Usage

rk device lease reap [--pool <kind>] [--lease-dir <path>] [--dry-run] [--json]

Options

--pool

Accepted to keep the flag set symmetric with acquire and release; each lease is routed through its own providerKind.

--lease-dir

Directory to scan.

--dry-run

Report what would be reaped without modifying any files.

--json

Print the lease directory and the actions taken as JSON.

Examples

rk device lease reap --json

Environment variables

All documented variables are listed on rk environment variables.

lease release

Summary

Release a device lease by id.

Description

Releases a lease by id. It is idempotent: releasing a missing or already-released lease exits 0 with a no-op log line. The provider is always read from the lease file. Exits 1 when the lease file is malformed or unreadable, or the provider's release fails.

Usage

rk device lease release [--lease-id <id>] [--pool <kind>] [--lease-dir <path>] [--json]

Options

--pool

Optional safety check: if given, it must match the lease's providerKind, else the command fails with RESOLVER_FORBIDDEN_COMBO. It never changes routing.

--lease-id

Lease id to release. Falls back to $RK_DEVICE_LEASE_ID; with neither, it exits 1 with MISSING_LEASE_ID.

--lease-dir

Directory the lease file is read from.

--json

Print the result as JSON.

Examples

rk device lease release --lease-id 01HE7P5RZQ

Environment variables

All documented variables are listed on rk environment variables.

ls

Summary

List devices and the active device.

Description

Lists the configured devices and marks the active one. Once a Roku Cloud Emulator device is registered, Kind and Status columns are added. --rce lists only the registered RCE devices, and --org lists every device in the RCE organisation, registered here or not.

Usage

rk device ls [--rce] [--json]
rk device ls --org [--json]

Options

--json

Print { devices, activeId, source } as JSON. Passwords are omitted.

--rce

List only the registered RCE devices.

--org

List every device in the RCE organisation.

See also

• listDevices (GET /api/devices)
• list_devices

open

Summary

Open the device web UI in a browser.

Description

Opens http://<device-ip> in the default browser. With no active device configured, it prints an error and exits non-zero.

Usage

rk device open [<id|ip|name>]

package

Summary

Device-side channel package operations.

Description

Manages channel package operations on a Roku device: sign, rekey, delete, squashfs and ls. Run without a subcommand it prints its help. The signing password is taken from --signing-password, then the ROKU_SIGNING_PASSWORD environment variable, then an interactive masked prompt (TTY only).

Usage

rk device package <subcommand> [options]

See also

• package

package delete

Summary

Delete the currently installed dev channel.

Description

Deletes the currently installed dev channel with POST /plugin_install and mysubmit=Delete.

Usage

rk device package delete [--device <id|ip|name>] [--host <ip|hostname>] [--password <pwd>] [--json]

Options

--device

Target device id, IP or name.

--host

Target device IP or hostname.

--password

Device developer password.

--json

Print { success } as JSON.

See also

• managePackage (POST /api/package)
• package

package ls

Summary

List installed channel and DCL package entries.

Description

Lists the installed channel and DCL package entries from the device web plugin endpoint (GET /plugin_install?dcl_enabled=1), as a table with type, archiveFileName, fileType and size columns.

Usage

rk device package ls [--device <id|ip|name>] [--host <ip|hostname>] [--password <pwd>] [--json]

Options

--device

Target device id, IP or name.

--host

Target device IP or hostname.

--password

Device developer password.

--json

Print only an array of package objects.

See also

• managePackage (POST /api/package)
• package

package rekey

Summary

Rekey a device with a signed key package.

Description

Rekeys the device with a signed .pkg key package (POST /plugin_inspect with mysubmit=Rekey), then reads the resulting keyed-developer-id from GET /query/device-info. When --dev-id, or package.devId in roku-config.ts, is set, the result must match it.

Usage

rk device package rekey <pkg-path> [--device <id|ip|name>] [--host <ip|hostname>] [--password <pwd>] [--signing-password <pwd>] [--dev-id <expected-id>] [--config <path>] [--json]

Options

--device

Target device id, IP or name.

--host

Target device IP or hostname.

--password

Device developer password.

--signing-password

Signing password for the key package.

--dev-id

Expected developer ID. Falls back to package.devId from roku-config.ts.

--config

Config variant file that provides the package.devId fallback.

--json

Print { success, devId } as JSON.

Examples

rk device package rekey /tmp/key.pkg --signing-password xxx --config roku-config-perf.ts

See also

• managePackage (POST /api/package)
• package

package sign

Summary

Sign the installed dev channel and download the generated package.

Description

Signs the currently installed dev channel package on the target device (POST /plugin_package) and downloads the generated .pkg. It is saved as ./app.pkg unless --out, package.outDir from roku-config.ts, or --out-file says otherwise.

Usage

rk device package sign [--device <id|ip|name>] [--host <ip|hostname>] [--password <pwd>] [--signing-password <pwd>] [--out <dir>] [--out-file <basename>] [--config <path>] [--json]

Options

--device

Target device id, IP or name.

--host

Target device IP or hostname.

--password

Device developer password.

--signing-password

Signing password.

--out

Output directory. Falls back to package.outDir from roku-config.ts.

--out-file

Base file name; the .pkg extension is appended automatically.

--config

Config variant file that provides the package.outDir fallback.

--json

Print { success, pkgPath } as JSON.

See also

• managePackage (POST /api/package)
• package

package squashfs

Summary

Convert the installed dev channel package to squashfs.

Description

Converts the currently installed dev channel package to squashfs with POST /plugin_install and mysubmit=Convert to squashfs.

Usage

rk device package squashfs [--device <id|ip|name>] [--host <ip|hostname>] [--password <pwd>] [--json]

Options

--device

Target device id, IP or name.

--host

Target device IP or hostname.

--password

Device developer password.

--json

Print { success } as JSON.

See also

• managePackage (POST /api/package)
• package

ping

Summary

Test device connectivity (not yet implemented).

Description

Not yet implemented: prints a TBD message.

Usage

rk device ping

pool status

Summary

Print current pool inventory + per-device state.

Description

Snapshots every inventory entry the pool's provider can see, with its live state: free, busy, leased or unreachable. The local pool reports its configured devices, every one as free. Asking for a kind that is not registered fails with PROVIDER_NOT_REGISTERED.

Usage

rk device pool status [--pool <kind>] [--json]

Options

--pool

Provider kind to inspect.

--json

Print the pool status as JSON.

Examples

rk device pool status --json

Environment variables

All documented variables are listed on rk environment variables.

rce-whoami

Summary

Show who the RCE token belongs to, and the organisation's limits.

Description

Prints the user and organisation the RCE token belongs to, the organisation's device, snapshot and runtime limits, and where the token comes from and when it expires.

Usage

rk device rce-whoami [--json]

Options

--json

Print { user, token } as JSON.

Environment variables

All documented variables are listed on rk environment variables.

reboot

Summary

Reboot the target Roku device.

Description

Sends POST /plugin_swup with mysubmit=Reboot, using the device password from the device store. Prints a clear error when no password is configured for the selected device. Requires firmware 15.0.4 or later.

Usage

rk device reboot [<id|ip|name>] [--json]

Options

--json

Print a machine-readable success or error payload.

See also

• rebootDevice (POST /api/devices/reboot)
• device_reboot

rm

Summary

Remove a device from the configuration.

Description

Removes a device (home preferred; legacy local fallback). If it was active, no device is active afterward. For a Roku Cloud Emulator device only the registration is forgotten; the device is never stopped or changed in RCE.

Usage

rk device rm <id|ip|name|rce:name>

See also

• removeDevice (DELETE /api/devices/:id)
• remove_device

runs

Summary

List a Roku Cloud Emulator device's past and current runs.

Description

Lists the device's runs, most recent first, with their runtime and cost.

Usage

rk device runs [rce:<name>] [--limit <n>] [--json]

Options

--limit

Show at most this many runs (a positive whole number).

--json

Print { device, total, runs } as JSON.

set-active

Summary

Set the active device.

Description

Sets the active device by writing the local activeDeviceId pointer. Only one device, LAN or RCE, is active at a time.

Usage

rk device set-active <id|ip|name|rce:name>

Examples

rk device set-active rce:my-tv

See also

• listDevices (GET /api/devices)
• activateDevice (POST /api/devices/:id/activate)
• activate_device

set-default-password

Summary

Set the default password for all devices.

Description

Updates defaultPassword in the configuration file. The password cannot be an empty string.

Usage

rk device set-default-password <password>

See also

• setDefaultDeviceAuth (PUT /api/devices/default/auth)
• update_default_auth

set-rce-token

Summary

Verify and save a Roku Cloud Emulator token.

Description

Reads the RCE token from stdin or a hidden prompt, never from an argument, so it stays out of shell history and the process list; any argument is refused. From a pipe only the first line is read. The token is checked with RCE before it is saved, and the command prints the user and organisation it belongs to. It warns when the token is within seven days of expiring.

Usage

rk device set-rce-token

Environment variables

All documented variables are listed on rk environment variables.

set-screenshot-dir

Summary

Set the default screenshot output directory.

Description

Sets the default screenshot output directory.

Usage

rk device set-screenshot-dir <path>

snapshot

Summary

List, inspect, capture, edit or delete Roku Cloud Emulator snapshots.

Description

Manages the saved states a device starts from. create captures a snapshot of a running device; rm asks first and never deletes the base snapshot, the live one, or the snapshot a registration starts from. Each verb accepts only its own flags.

Usage

rk device snapshot ls [rce:<name>] [--json]
rk device snapshot show [rce:<name>] <snapshot> [--json]
rk device snapshot create [rce:<name>] --name <name> [--note <text>] [--parent <snapshot>] [--property key=value ...] [--wait] [--json]
rk device snapshot update [rce:<name>] <snapshot> [--name <name>] [--note <text>] [--property key=value ...] [--json]
rk device snapshot rm [rce:<name>] <snapshot> [--yes] [--json]

Options

--name

create and update: the snapshot's name. Required for create.

--note

create and update: a note on the snapshot.

--parent

create only: the parent snapshot.

--property

create and update: a property to set. Repeat the flag for several properties.

--wait

create only: wait for the snapshot to be captured.

--yes

rm only: delete without asking first.

--json

Print the result as JSON.

Examples

rk device snapshot ls rce:my-tv
rk device snapshot create rce:my-tv --name after-login --wait
rk device snapshot rm rce:my-tv after-login

start

Summary

Start a Roku Cloud Emulator device and leave it running.

Description

Starts an RCE device (default: the active one) and leaves it running until rk device stop or its maximum runtime, whichever comes first. It prints when the device will stop and the most it can cost. RCE bills per device-hour while a device runs.

Usage

rk device start [rce:<name>] [--snapshot <name|id>] [--firmware <id|name>] [--max-runtime <s>] [--json]

Options

--snapshot

Start once from this snapshot without changing the registration.

--firmware

Firmware to start with.

--max-runtime

Maximum runtime in seconds. The organisation's limit lowers a larger value.

Example:

rk device start rce:my-tv --max-runtime 1800

--json

Print { device, runId, started, deadline } as JSON.

Examples

rk device start rce:my-tv

See also

• device_start

status

Summary

Show a Roku Cloud Emulator device's status.

Description

Shows the device, its current run, its last snapshot and how many snapshots it has. With a LAN device active and no device named, it says that it reports on RCE devices only and exits 0; naming a LAN device fails with DEVICE_KIND_UNSUPPORTED.

Usage

rk device status [rce:<name>] [--watch] [--json]

Options

--watch

Print every state change until Ctrl-C; one JSON object per line with --json.

--json

Print the status as JSON.

stop

Summary

Stop a Roku Cloud Emulator device.

Description

Stops a device and waits until RCE reports its run ended. A run not started from this machine needs confirmation: a y/N prompt at a terminal, or --yes when there is none; a script without --yes fails with RCE_STOP_NOT_CONFIRMED.

Usage

rk device stop [rce:<name>] [--yes] [--json]

Options

--yes

Stop a run not started from this machine without asking.

--json

Print the result as JSON.

Examples

rk device stop rce:my-tv

See also

• device_stop

store-path

Summary

Print the path to the effective device config source.

Description

Prints the effective device config source path.

Usage

rk device store-path [--json]

Options

--json

Print { path } as JSON; path is null when no config exists at any level.

update

Summary

Update a device's fields, or a Roku Cloud Emulator registration and device.

Description

Updates an existing device's fields (home preferred; legacy local fallback) and shows the updated device list. For a Roku Cloud Emulator device (rce:<name>) it changes the registration (--snapshot, --firmware, --max-runtime, --password-stdin) or the device in RCE (--name, --note, --account-name, --property), and prints only what changed.

Usage

rk device update <id|ip|name> [--name <n>] [--id <id>] [--ip <ip>] [--password <p>] [--tag <t> ...]
rk device update rce:<name> [--snapshot <name|id>] [--firmware <id|name>] [--max-runtime <s>] [--password-stdin] [--name <n>] [--note <text>] [--account-name <email>] [--property key=value ...] [--yes]

Options

--name

New name. For an RCE device this renames it in RCE and asks first; without a terminal and without --yes it fails with RCE_RENAME_NOT_CONFIRMED.

--id

New device id.

--ip

New IP address.

--password

New device password.

--tag

Tag to add. Repeat the flag for several tags.

--snapshot

RCE: the snapshot rk dev starts the device from.

--firmware

RCE: the firmware rk device start and rk dev --start use by default.

--max-runtime

RCE: the maximum runtime in seconds rk device start and rk dev --start use by default.

--password-stdin

RCE: save a new developer password, read from stdin.

--note

RCE: the device's note in RCE.

--account-name

RCE: the device's account name in RCE.

--property

RCE: a property to set; key= removes it. Repeat the flag for several properties.

--yes

RCE: rename without asking first.

--json

Print the result as JSON; for an RCE device, { device }.

Examples

rk device update rce:my-tv --note signed-in

See also

• listDevices (GET /api/devices)
• updateDevice (PUT /api/devices/:id)
• update_device

usage

Summary

Show Roku Cloud Emulator usage for the token's user or the organisation.

Description

Shows the RCE usage of the token's user, or with --org the organisation's (owners only). RCE reports the values without stating a unit, and rk shows them as given.

Usage

rk device usage [--org] [--from <date>] [--to <date>] [--interval 1h|24h|1w|1mo] [--json]

Options

--org

Show the organisation's usage (owners only).

--from

Start of the period; it has to be before --to.

Example:

rk device usage --from 2026-09-01 --to 2026-10-01 --interval 1w

--to

End of the period.

--interval

Bucket size.

--json

Print the usage as JSON.

Examples

rk device usage --org --interval 1w