Research: roo-cli Interface & Stream Format

CLI Binary & Version

• Binary name: roo (installed via npm at /Users/skven/.local/share/mise/installs/node/20.20.0/bin/roo)
• Version: 0.1.15
• Source: /Users/skven/workplace/Roo-Code/apps/cli/

CLI Flags (from roo --help)

Core Execution Flags

Model/Provider Flags

AWS Bedrock Flags

Mode & Behavior Flags

Session Flags

Stdin Streaming

Stream-JSON Format

Protocol

• Protocol: roo-cli-stream
• Schema version: 1
• NDJSON (newline-delimited JSON)

Event Types (from source: types/json-events.ts)

Example Stream Output (observed)

{"type":"system","subtype":"init","content":"Task started","schemaVersion":1,"protocol":"roo-cli-stream","capabilities":["stdin:start","stdin:message","stdin:cancel","stdin:ping","stdin:shutdown"]}
{"type":"user","id":1772593478580,"content":"Say hello in one sentence","done":true}
{"type":"assistant","id":1772593481508,"content":"Hello"}
{"type":"assistant","id":1772593481508,"content":"! Welcome"}
{"type":"assistant","id":1772593481508,"content":" to the"}
{"type":"assistant","id":1772593481508,"content":" ralph"}
{"type":"assistant","id":1772593481508,"content":"-orchest"}
{"type":"assistant","id":1772593481508,"content":"rator project"}
{"type":"assistant","id":1772593481508,"content":"."}
{"type":"assistant","id":1772593481508,"content":"Hello! Welcome to the ralph-orchestrator project.","done":true}
{"type":"result","id":1772593482878,"content":"Hello! I'm Roo, ready to help you with the ralph-orchestrator project.","done":true,"success":true}

Key Schema Fields (from JsonEvent type)

type JsonEvent = {
  type: JsonEventType          // Event discriminator
  id?: number                  // Message ID for correlation
  content?: string             // Text content
  done?: boolean               // Final message flag
  subtype?: string             // Categorization (e.g., "init", "tool", "command")
  schemaVersion?: number       // Protocol version (on system.init)
  protocol?: string            // Transport protocol (on system.init)
  capabilities?: string[]      // Supported capabilities (on system.init)
  taskId?: string              // Active task ID
  requestId?: string           // Correlation ID
  command?: string             // Command name for control events
  code?: string                // Machine-readable error code
  tool_use?: JsonEventToolUse  // Tool call info
  tool_result?: JsonEventToolResult  // Tool result info
  success?: boolean            // Task success (result events)
  cost?: JsonEventCost         // Token/cost usage (result events)
  queueDepth?: number          // Queue depth
  queue?: JsonEventQueueItem[] // Queue snapshots
}

Cost Structure

type JsonEventCost = {
  totalCost: number
  inputTokens: number
  outputTokens: number
  cacheWrites?: number
  cacheReads?: number
}

Comparison with Claude Stream Format

Key Differences

1. Claude emits full turns (assistant, user) with all content blocks
2. Roo emits streaming deltas (many small assistant events building up content, then a done:true final)
3. Roo has separate event types for tool_use and tool_result (Claude embeds in message content blocks)
4. Roo has thinking as a separate event type (Claude has it as a content block type)
5. Roo supports bidirectional stdin streaming (--stdin-prompt-stream)

Headless Mode Command (confirmed working)

roo --provider bedrock --aws-profile roo-bedrock --aws-region us-east-1 \\
    --model anthropic.claude-sonnet-4-6 --max-tokens 64000 \\
    --print "Say hello in one sentence"

Mapping to Ralph Adapter Pattern

For a text-mode (simplest) integration:

roo --print <prompt>

For a stream-json integration:

roo --print --output-format stream-json <prompt>

For interactive mode:

roo <prompt>  (no --print flag)