PIPPI Manual

Pipeline Inspector and Processor Interface - CLI for running, inspecting, and interactively composing pipeline workflows.

Installation

pip install -e ~/working/pippi

Commands

Run Pipelines

pippi run <pipeline-fence>               # Run pipeline, show output
pippi run cookie-jar-game:pipeline       # Run specific pipeline
pippi run my-pipeline --format tokens    # Rendered output
pippi run my-pipeline --params '{"count": 5}'

Inspect Runs

pippi runs                              # List recent runs
pippi runs my-pipeline                  # Filter by pipeline
pippi show <session-id>                 # Full run details
pippi show <session-id> --output        # Just output snapshot
pippi edges <session-id>                # Execution deltas
pippi diff <a> <b>                      # Compare two runs
pippi diff <a> <b> | delta              # Pipe to visual diff

Interactive Sessions (REPL)

# Start session
pippi session start
pippi session start --context '{"game": "cookie-jar"}'

# Work with session
pippi session <id>                      # Show state
pippi session <id> exec random-names    # Execute fence
pippi session <id> exec random-names --count 5
pippi session <id> peek                 # See full context
pippi session <id> peek players         # See specific path
pippi session <id> poke filter.min 10   # Write to context
pippi session <id> steps                # Execution history
pippi session <id> end                  # End and get provenance

# Management
pippi sessions                          # List active
pippi session <id> delete               # Delete
pippi cleanup                           # Remove expired

Configuration

OCULUS_API_URL: http://localhost:7778  # Default

Example Session

# Start interactive session
$ pippi session start --context '{"game": "cookie-jar"}'
Session started: live-abc123-1234567890

# Execute fences
$ pippi session live-abc123-1234567890 exec random-names --count 5
{
  "players": ["Alice", "Bob", "Charlie", "Diana", "Eddie"],
  "count": 5
}

# Check context
$ pippi session live-abc123-1234567890 peek players
["Alice", "Bob", "Charlie", "Diana", "Eddie"]

# Continue pipeline
$ pippi session live-abc123-1234567890 exec cookie-jar-round
{
  "thief": "Eddie",
  "lyrics": [...],
  "game_over": true
}

# End session
$ pippi session live-abc123-1234567890 end
Session ended: live-abc123-1234567890
Duration: 3421ms
Steps: 2

Architecture

PIPPI is a thin CLI wrapper around the Oculus API:

• Pipeline Sessions (/api/pipeline/*) - Historical pipeline execution records
• Live Sessions (/api/session/*) - Interactive step-by-step execution

Unlike pipelines that run all at once, live sessions let you:

• Start with initial context
• Execute fences one at a time
• Peek/poke context between steps
• End session and get full provenance

This enables any-language workflow composition via HTTP.

Related

• Pipeline Provider - The engine that executes pipeline fences
• Live Session API - HTTP endpoints for interactive sessions
• Cookie Jar Game - Demo pipeline

North

slots:
- slug: wanderland-clients
  context:
  - Adding PIPPI to client registry
  - Linking PIPPI to client registry

Provenance

Document

• Status: 🔴 Unverified

Changelog

• 2026-01-25 23:00: Node created by mcp - Creating documentation node for PIPPI CLI tool