Home
Guides
  1. DEVELOPER
  2. RSG 2.0 SDK documentation
  3. Runtime and debugging
  4. rk

rk logs

The rk logs command collects and queries Roku device logs in server mode. A log session maintains a persistent telnet connection to the device and stores a circular buffer in memory for retrieval, search, and tailing.

You start a log session for a device and port, and then you retrieve, search, or tail the buffered logs from the CLI or through Model Context Protocol (MCP). When you enable log storage in .roku/roku-dev-config.json, the server also persists logs to disk under .roku/logs/ and reloads the in-memory buffer from recent files when a session starts.

Log collection requires a running rk server, and the tail subcommand is not available through MCP. See Requirements for more information.

Requirements

Log collection has the following requirements:

  • Server mode: Log collection requires a running rk server.
    • You can start the server with npx rk server, or you can use the Pilot extension, which enables server mode by default.
  • Developer mode: You must enable developer mode on the target Roku device.
  • Network access: The device must be reachable from your machine on the selected telnet port.
  • Roku Cloud Emulator (RCE) devices (--device rce:<name>): The device must be running, and the server needs an RCE token (set RK_RCE_TOKEN in its environment, or save one with rk device set-rce-token). A session ends when the device's run ends. See Logs for more information.

Synopsis

The following syntax shows how to run the command:

rk logs <subcommand> [options]

The rk logs command has the following subcommands:

  • start: Starts collecting logs for a device and port
  • list: Lists log sessions
  • stop: Stops log sessions
  • get: Gets the last N log lines
  • search: Searches buffered logs with a regular expression
  • tail: Streams logs in real time (CLI only)
  • ports: Lists known Roku log ports

Commands

Each of the following sections describes one subcommand, its syntax, and its behavior. See rk logs for more information about every option and default.

start

The start subcommand starts a log session (it creates a persistent telnet connection and a buffer):

rk logs start [options]

The start subcommand behaves as follows:

  • It returns an error if a session is already active for the same device and port.
  • It requires server mode. If the server is not running, the command fails.
  • It returns a response that includes logDir (the absolute path to .roku/logs) when disk storage is enabled, and null otherwise.

list

The list subcommand lists active log sessions:

rk logs list [options]

The list subcommand groups sessions by device and shows the status and buffer usage of each port.

get

The get subcommand retrieves the last N log lines from a buffer:

rk logs get [options]

The get subcommand behaves as follows:

  • Without --output, it prints logs to stdout.
  • With --format json, the output is an array of [timestamp, device, line].

search

The search subcommand searches buffered logs with a JavaScript regular expression:

rk logs search <pattern> [<pattern>...] [options]

The search subcommand behaves as follows:

  • It requires at least one pattern. When you provide multiple patterns, a log line matches if it matches any of them.
  • It limits regular-expression evaluation to 1000 ms. A timeout returns HTTP 408.

tail

The tail subcommand streams logs in real time (CLI only):

rk logs tail [options]

The --source option selects the log source. The value console (the default) streams the app's console. The value firmware streams the firmware log of a Roku Cloud Emulator device (system output, not the app's console) and runs without a server. The firmware source takes --device and --from-start (to begin with the lines that the device already logged).

The tail subcommand behaves as follows:

  • It streams with server-sent events (SSE). With --source firmware, the subcommand connects directly to RCE.
  • You can stop the stream with Ctrl+C.
  • It is not available through MCP because AI tools cannot stream.

stop

The stop subcommand stops log sessions (it disconnects the stream but keeps the buffer in memory):

rk logs stop [options]

The stop subcommand behaves as follows:

  • With --all and --device, it stops all ports for that device.
  • With --all only, it stops all sessions for all devices.
  • Without --all, it stops the active device session for the selected port.

ports

The ports subcommand lists the known Roku log ports:

rk logs ports

Examples

The following sections show examples for each subcommand.

start

The following commands start log sessions:

# Active device, default port 8085
npx rk logs start

# Specific device and port
npx rk logs start --device "Living Room" --port 8086

# Larger buffer
npx rk logs start --buffer-size 20000

list

The following commands list log sessions:

npx rk logs list
npx rk logs list --verbose

The list subcommand prints output like the following example:

Active Log Sessions:
  Living Room (192.0.2.10)
    Port 8085: active (523/10000 lines)

get

The following commands retrieve logs:

# Default: last 50 lines
npx rk logs get

# Specific device and port, with a line count
npx rk logs get --device 192.0.2.10 --port 8086 --lines 100

# Export to file
npx rk logs get --output logs.txt

# Append to existing file
npx rk logs get --output logs.txt --append

# Export with metadata (JSON)
npx rk logs get --output logs.json --format json

With --format json, the output looks like the following example:

[
  ["2026-02-24T10:00:00.000Z", "Living Room", "Some log line"],
  ["2026-02-24T10:00:01.000Z", "Living Room", "Another log line"]
]

search

The following commands search the buffered logs:

# Search by regular expression (case-insensitive by default)
npx rk logs search "error|warning"

# Multiple patterns (matches any of them)
npx rk logs search error warning

# Literal search (escape special characters)
npx rk logs search "\\*\\*\\* Error"

# Case-sensitive search
npx rk logs search "Invalid token" --case-sensitive

# Limit the number of matches returned
npx rk logs search timeout --lines 200

# Advanced regular expression examples
npx rk logs search "^ERROR:"             # Lines starting with ERROR:
npx rk logs search "error.*timeout"      # error followed by timeout
npx rk logs search "\\d{1,3}\\.\\d{1,3}"  # IP address pattern

tail

The following commands stream logs:

npx rk logs tail
npx rk logs tail --prefix
npx rk logs tail --device "Living Room" --port 8086

stop

The following commands stop log sessions:

# Stop active device session on default port
npx rk logs stop

# Stop a specific session
npx rk logs stop --device "Living Room" --port 8085

# Stop all sessions for a device
npx rk logs stop --device "Living Room" --all

# Stop all sessions
npx rk logs stop --all

ports

The following command lists the known log ports:

npx rk logs ports

The ports subcommand prints output like the following example:

Known Roku Telnet Ports:
  8085 - Main device logs
  8086 - Screensaver logs

Known ports

Roku devices expose the following telnet log ports:

  • 8085: Main device logs (default)
  • 8086: Screensaver logs
  • Custom ports: Supported; you can use --port <number> to connect to any Roku telnet log port

Integrating with rk dev --console

The log collector shares the telnet connection that rk dev --console uses when it runs in server mode. Roku devices allow only one connection for each device and port; therefore, the server coordinates access through a shared console manager.

You should use the following workflow:

# Start server mode (if not already running)
npx rk server

# Start a log session
npx rk logs start --port 8085

# Deploy and stream console output
npx rk dev --console

The following points describe how the connection is shared:

  • When the server manages both features, the server shares the connection between them.
  • If you run rk dev --console outside server mode while a server log session is active on the same port, the second connection may fail because Roku devices allow only one connection for each port.
  • You can use --auto-console-close with rk dev --console to close the console connection after a successful deploy.

See rk dev for more information about console flags.

Troubleshooting

The following list describes common errors and their fixes:

  • Server mode required: Start the server first with npx rk server.
  • No active device set: Set a device with rk device set-active, or pass --device.
  • Device not found: Verify that the device exists with rk device ls.
  • Session not found: Start a session with rk logs start before you run the get, search, or tail subcommand.
  • Regular expression invalid or timed out: Simplify the pattern or anchor it (for example, ^ERROR), and then retry.
  • Connection refused: Verify that the device is reachable and in developer mode.
  • Buffer wrapped: You can increase --buffer-size to keep more history.

Enabling disk persistence

Disk persistence is off by default. You can enable it in .roku/roku-dev-config.json. The following example shows the available settings:

{
  "logStorage": {
    "enabled": true,
    "maxFileSizeMB": 50,
    "maxFiles": 10,
    "maxAgeDays": 7,
    "maxTotalSizeMB": 500
  }
}

When you omit a field, the following defaults apply:

  • enabled: false
  • maxFileSizeMB: 50
  • maxFiles: 10
  • maxAgeDays: 7
  • maxTotalSizeMB: 500

The server writes log files with the following layout:

  • Directory: .roku/logs/
  • File name: <ip>-<port>-<YYYYMMDD>-<HHmmss>.log
  • Format: plain text, one log line per file line (without extra timestamps)

Disk persistence behaves as follows:

  • The server rotates a file when its size exceeds maxFileSizeMB.
  • On session start, the server reloads the in-memory circular buffer from the newest matching files for the same device:port.
  • Garbage collection (GC) runs when a session starts and after rotation, and applies the age, file count, and total size limits.
  • The logs search action remains the preferred way to analyze logs in AI workflows because it searches in memory with a regular expression, which is fast.

Using the logs MCP tool

The logs MCP tool supports the start, list, stop, get, and search actions. MCP does not support streaming (tail).

When disk storage is enabled, the start response includes logDir with the absolute .roku/logs path. AI assistants should still prefer logs search for analysis.

The following examples show MCP payloads:

{ "action": "start", "device": "Living Room", "port": 8085, "bufferSize": 10000 }
{ "action": "get", "device": "Living Room", "port": 8086, "lines": 100 }
{ "action": "search", "device": "Living Room", "port": 8086, "lines": 100, "filter": "error|warning", "caseSensitive": false }

See rk server for more information about the MCP endpoint.

Workflow examples

The following sections show complete workflows.

Debugging with AI assistance

The following commands start log collection and deploy the app:

# Start log collection
npx rk logs start

# Deploy and test
npx rk dev --console

In an AI assistant, the interaction looks like the following:

  • Ask: "Check the logs for any errors in the last 200 lines."
  • MCP call: { "command": "logs", "action": "search", "filter": "error", "lines": 200 }
  • Result: The AI summarizes the matches and suggests fixes

Developing with multiple devices

The following commands collect logs from two devices and monitor one of them:

# Collect logs from multiple devices
npx rk logs start --device "Living Room"
npx rk logs start --device "Bedroom"

# Monitor one device in terminal
npx rk logs tail --device "Living Room"

In an AI assistant, the interaction looks like the following:

  • Ask: "Show the last 100 lines from the Bedroom device."
  • MCP call: { "command": "logs", "action": "get", "device": "Bedroom", "lines": 100 }

Testing the screensaver

The following commands collect and search screensaver logs:

# Collect screensaver logs
npx rk logs start --port 8086

# Search for specific events
npx rk logs search "screensaver" --port 8086

Understanding log session behavior

The following points describe how log sessions behave:

  • Sessions are server-only and live in memory; they do not persist across server restarts.
  • A circular buffer stores logs; when the buffer is full, new entries overwrite the old entries.
  • Log collection is separate from ECP. You can use rk ecp for device control and UI inspection.
  • The CLI accepts multiple positional patterns and matches a log line against any of them. In MCP, you must combine the patterns into a single regular expression (for example, "error|warning").

Related documentation

  • rk logs: Lists every option and default for the rk logs subcommands.
  • Roku Cloud Emulator devices: Describes log collection for Roku Cloud Emulator devices.
  • rk dev: Describes the console flags that work with rk dev --console.
  • rk server: Describes the MCP endpoint details for the server.
  • rk ecp: Describes device control and UI inspection.

Updated about 3 hours ago

Did this page help you?