sideline/REPL_USAGE.md

REPL Usage Guide

The REPL (Read-Eval-Print Loop) effect provides an interactive command-line interface for controlling Mainline's pipeline in real-time.

How to Access the REPL

Method 1: Using CLI Arguments (Recommended)

Run Mainline with the repl effect added to the effects list:

# With empty source (for testing)
python mainline.py --pipeline-source empty --pipeline-effects repl

# With headlines source (requires network)
python mainline.py --pipeline-source headlines --pipeline-effects repl

# With poetry source
python mainline.py --pipeline-source poetry --pipeline-effects repl

Method 2: Using a Preset

Add a preset to your ~/.config/mainline/presets.toml or ./presets.toml:

[presets.repl]
description = "Interactive REPL control"
source = "headlines"
display = "terminal"
effects = ["repl"]
viewport_width = 80
viewport_height = 24

Then run:

python mainline.py --preset repl

Method 3: Using Graph Config

Create a TOML file (e.g., repl_config.toml):

source = "empty"
display = "terminal"
effects = ["repl"]

Then run:

python mainline.py --graph-config repl_config.toml

REPL Commands

Once the REPL is active, you can type commands:

• help - Show available commands
• status - Show pipeline status and metrics
• effects - List all effects in the pipeline
• effect <name> <on|off> - Toggle an effect
• param <effect> <param> <value> - Set effect parameter
• pipeline - Show current pipeline order
• clear - Clear output buffer
• quit/exit - Show exit message (use Ctrl+C to actually exit)

Keyboard Controls

• Enter - Execute command
• Up/Down arrows - Navigate command history
• Backspace - Delete last character
• Ctrl+C - Exit Mainline

Visual Features

The REPL displays:

• HUD header (top 3 lines): Shows FPS, frame time, command count, and output buffer size
• Content area: Main content from the data source
• Separator line: Visual divider
• REPL area: Output buffer and input prompt

Example Session

MAINLINE REPL | FPS: 60.0 | 12.5ms
COMMANDS: 3 | [2/3]
OUTPUT: 5 lines
────────────────────────────────────────
Content from source appears here...
More content...
────────────────────────────────────────
> help
Available commands:
  help - Show this help
  status - Show pipeline status
  effects - List all effects
  effect <name> <on|off> - Toggle effect
  param <effect> <param> <value> - Set parameter
  pipeline - Show current pipeline order
  clear - Clear output buffer
  quit - Show exit message
> effects
Pipeline effects:
  1. repl
> effect repl off
Effect 'repl' set to off

Notes

• The REPL effect needs a content source to overlay on (e.g., headlines, poetry, empty)
• The REPL uses terminal display with raw input mode
• Command history is preserved across sessions (up to 50 commands)
• Pipeline mutations (enabling/disabling effects) are handled automatically