PIPPI User Guide

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

Installation

pip install -e /path/to/pippi

Quick Reference

Command	Description
pippi list	List available pipeline fences
pippi pipelines	List pipelines with run history
pippi run <fence>	Execute a pipeline
pippi runs	List recent pipeline runs
pippi show <id>	Show run details
pippi edges <id>	Show execution deltas
pippi diff <a> <b>	Compare two runs
pippi session start	Start interactive session

Pipeline Discovery

List Available Pipelines

# List all pipeline fences
pippi list

# Filter by pattern
pippi list cookie

# JSON output
pippi list --json

List Pipelines with History

# Show pipelines that have been executed
pippi pipelines

Running Pipelines

Basic Execution

# Run a pipeline
pippi run <fence-address>

# With parameters
pippi run <fence-address> --params '{"count": 5}'

Output Formats

# Default: JSON data
pippi run my-pipeline

# Rendered tokens (markdown)
pippi run my-pipeline --format tokens

# YAML output
pippi run my-pipeline --format yaml

Inspecting Runs

List Recent Runs

# List all recent runs
pippi runs

# Filter by pipeline
pippi runs cookie-jar-game

# Most recent run
pippi runs -1

# Show full session IDs (for scripting)
pippi runs --ids

# Limit results
pippi runs --limit 50

View Run Details

# Full session details
pippi show <session-id>

# Just the output
pippi show <session-id> --output

# Just the source
pippi show <session-id> --source

# JSON output
pippi show <session-id> --json

View Execution Edges

Edges show what changed at each step of the pipeline:

# Summary view
pippi edges <session-id>

# Detailed view (full values)
pippi edges <session-id> --details

# JSON output
pippi edges <session-id> --json

Comparing Runs

Diff Two Runs

# Unified diff format
pippi diff <session-a> <session-b>

# Pipe to visual diff tool
pippi diff <session-a> <session-b> | delta

# JSON output
pippi diff <session-a> <session-b> --json

Interactive Sessions

Interactive sessions let you execute fences step-by-step with a persistent context.

Start a Session

# Start empty session
pippi session start

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

# Custom TTL (seconds)
pippi session start --ttl 7200

Work with Sessions

# View session state
pippi session <id>

# Execute a fence
pippi session <id> exec <fence-id>
pippi session <id> exec <fence-id> --count 5

# Read from context
pippi session <id> peek
pippi session <id> peek players

# Write to context
pippi session <id> poke filter.min 10

# View execution history
pippi session <id> steps

End or Delete Session

# End session (get provenance)
pippi session <id> end

# Delete session
pippi session <id> delete

List Sessions

# List active sessions
pippi sessions

# Include ended sessions
pippi sessions --all

Maintenance

Cleanup Expired Sessions

pippi cleanup

Configuration

Variable	Description	Default
OCULUS_API_URL	Oculus API base URL	http://localhost:7778

Storage

Pipeline sessions are stored with:

• SQLite for metadata (fast queries)
• Filesystem for content (snapshots, edges)

Location: ~/.local/share/oculus/.cache/pipeline-sessions/

Tags

tags:
  - tool:pippi
  - pattern:cli
  - pattern:pipeline
  - docs:reference

North

slots:
- slug: pippi-how-to
  context:
  - Practical how-to guide
- slug: wanderland-tools
  context:
  - Parent tools documentation

Provenance

Document

• Status: 🔴 Unverified

Changelog

• 2026-01-26 00:12: Node created by mcp - Creating Pippi user guide reference documentation

South

slots:
- slug: pippi-how-to
  context:
  - Linking guide to how-to