CLI & parsers reference

CLI commands

--timeout=SECONDS

Overrides PTYRunner's 30-second default. Only recognized before a -- separator, so it can never be mistaken for a flag belonging to the wrapped command:

# applies to rune, overrides the timeout
rune run --timeout=5 -- sleep 30

# --timeout here belongs to the wrapped command, passed through untouched
rune run -- some-other-cli --timeout=5

A timed-out run returns exit code 124 and appends a message to the output, never an unhandled exception.

rune watch --log=PATH

rune watch always writes an NDJSON event log: one start event, one output event per streamed chunk, and one exit event, so an agent can tail -f the session while a human drives it. It defaults to an announced temp file rather than stderr, since stderr shares the same terminal as the live passthrough and would interleave JSON noise into an otherwise-clean interactive session:

# default: announces a temp file path once, up front
rune watch -- some-interactive-cli

# or point it somewhere specific
rune watch --log=/tmp/session.ndjson -- some-interactive-cli

Requires a real terminal: rune watch refuses to run if stdin isn't a TTY, since there's no meaningful non-interactive mode for live passthrough.

Rune::Parsers

TableParser.parse(text, format: :auto)

Converts space- or pipe-delimited table text into an array of hashes with lowercase, underscored symbol keys.

Known limitation: the space-delimited heuristic is column-alignment dependent. :space mode splits on runs of 2+ spaces (falling back to single-space token spans only when the header has one word). Cell values that don't align to the header's column boundaries, or that contain internal runs of 2+ spaces, can be misattributed to the wrong column.

:auto detection is a single check. It only inspects whether the header line contains |: free-text tables whose header happens to contain a literal pipe character will be misdetected as pipe tables unless format: :space is passed explicitly. When source output is unreliable or known in advance, pass an explicit format: rather than relying on :auto.

# Force pipe parsing even without a markdown separator row
Rune::Parsers::TableParser.parse("Name | Status\nrune | active", format: :pipe)
# => [{ name: 'rune', status: 'active' }]

KeyValueParser.parse(text)

Converts key-value text lines (key: val) into a hash, coercing integer, float, and boolean values automatically.

Rune::Parsers::KeyValueParser.parse("threads: 4")
# => { threads: 4 }

TextSanitizer.strip_ansi(text)

Strips ANSI escape codes and normalizes line endings. Returns an empty string for nil input.

PromptDetector.detect?(line)

Reports whether a single line of output looks like an interactive prompt awaiting input, powering the prompt_detected field on rune run/rune watch results. Strips ANSI codes before matching, and deliberately excludes a few common false-positive shapes: digit-percent progress output ("Downloading 100%") and <placeholder>-style example lines ("...install <owner/repo>") are never mistaken for a trailing %/> shell prompt.

Rune::Script

A step-by-step DSL for driving interactive TUI prompts and menus, consumed by PTYRunner's script: option: