# 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:

```bash
# 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`:

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

Then run:
```bash
python mainline.py --preset repl
```

### Method 3: Using Graph Config

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

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

Then run:
```bash
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
```

## Scrolling Support

The REPL output buffer supports scrolling through command history:

**Keyboard Controls:**
- **PageUp** - Scroll up 10 lines
- **PageDown** - Scroll down 10 lines
- **Mouse wheel up** - Scroll up 3 lines
- **Mouse wheel down** - Scroll down 3 lines

**Scroll Features:**
- **Scroll percentage** shown in HUD (like vim, e.g., "50%")
- **Scroll position** shown in output line (e.g., "(5/20)")
- **Auto-reset** - Scroll resets to bottom when new output arrives
- **Max buffer** - 50 lines (excluding empty lines)

## 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