PIPPI How-To Guide

Everyday operations with PIPPI using the Cookie Jar Game as an example.

Getting Started

First, make sure the oculus-api service is running:

# Check service status
ccp status

# If needed, start it
ccp start oculus-api

Discover Available Pipelines

See what pipeline fences are available to run:

pippi list

Output shows pipeline fences with their addresses:

Available Pipelines (3)

  Address                                           Node             Section
 ─────────────────────────────────────────────────────────────────────────────
  cookie-jar-game-play-the-game-fence-0             cookie-jar-game  Play the Game
  cookie-jar-game-data-only-no-formatting-fence-0   cookie-jar-game  Data Only

Filter by name:

pippi list cookie

Run a Pipeline

Execute a pipeline fence:

pippi run cookie-jar-game-play-the-game-fence-0

You'll see output like:

Running: cookie-jar-game-play-the-game-fence-0
Session: session-f737fc5d9fd6-1769385791438
{
  "players": ["Uma"],
  "thief": "Uma",
  "lyrics": ["Who stole the cookie..."],
  "game_over": true
}

With Parameters

Override default parameters:

pippi run cookie-jar-game-play-the-game-fence-0 --params '{"count": 3}'

View Run History

List Recent Runs

pippi runs

Output:

                          Pipeline Runs (6)
 ───────────────────────────────────────────────────────────────────────
  #  Pipeline         Created   Duration  Session ID
  0  cookie-jar-game  00:08:11      50ms  session-f737fc5d9fd6-1769386091136
  1  cookie-jar-game  00:03:11      28ms  session-f737fc5d9fd6-1769385791438
  ...

Filter by Pipeline

pippi runs cookie-jar-game

Quick Access to Latest Run

pippi runs -1

Output:

session-f737fc5d9fd6-1769386091136
  Pipeline: cookie-jar-game
  Created: 2026-01-26T00:08:11.489004Z
  Duration: 50ms

pippi show session-f737fc5d9fd6-1769386091136

Inspect a Run

Full Details

pippi show session-f737fc5d9fd6-1769385791438

Just the Output

pippi show session-f737fc5d9fd6-1769385791438 --output

This returns the final output data as JSON:

{
  "players": ["Uma"],
  "thief": "Uma",
  "lyrics": [...],
  "game_over": true
}

Just the Source

pippi show session-f737fc5d9fd6-1769385791438 --source

View Execution Edges

Edges show what changed at each pipeline step:

pippi edges session-f737fc5d9fd6-1769385791438

Output:

Edges for session-f737fc5d9fd6-1769385791438:

cookie-jar-round
  + Added:
    lyrics: ['Who stole the cookie from the cookie jar?'...
    game_over: True
    thief: Uma
  ~ Changed:
    players: ['Diana', 'Victor', 'Zara', 'Kevin', 'Uma'] -> ['Uma']
  - Removed: count

Detailed View

For full values (not truncated):

pippi edges session-f737fc5d9fd6-1769385791438 --details

Compare Two Runs

Diff the output of two runs:

pippi diff session-f737fc5d9fd6-1769385791438 session-f737fc5d9fd6-1769382608395

Output (unified diff format):

--- session-f737fc5d9fd6-1769385791438 (2026-01-26T00:03:11.489004Z)
+++ session-f737fc5d9fd6-1769382608395 (2026-01-25T23:10:08.424273Z)

- thief: "Uma"
+ thief: "Alice"
~ lyrics: {"type": "list_diff", "before_len": 33, "after_len": 33, "items_changed": true}

Visual Diff

Pipe to a visual diff tool like delta:

pippi diff session-a session-b | delta

Interactive Sessions

For step-by-step pipeline exploration:

Start a Session

pippi session start --context '{"message": "hello"}'

Execute Fences

pippi session live-abc123-1234567890 exec random-names --count 3

Peek at Context

pippi session live-abc123-1234567890 peek
pippi session live-abc123-1234567890 peek players

End Session

pippi session live-abc123-1234567890 end

Common Workflows

Debug a Pipeline

• Run the pipeline and note the session ID
• View the edges to see what each step did
• Use --details for full values
• Compare with a known-good run

pippi run my-pipeline
# Session: session-xxx

pippi edges session-xxx --details
pippi diff session-xxx session-known-good

Reproduce a Run

• Get the source snapshot from an old run
• Use it as input for a new run

# Get source from old run
pippi show session-old --source > source.json

# Use as params for new run
pippi run my-pipeline --params "$(cat source.json)"

Tags

tags:
  - tool:pippi
  - pattern:how-to
  - docs:tutorial

South

slots:
- slug: pippi-guide
  context:
  - Reference documentation

Provenance

Document

• Status: 🔴 Unverified

Changelog

• 2026-01-26 00:12: Node created by mcp - Creating Pippi how-to guide with practical examples

North

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

East

slots:
- slug: cookie-jar-game-staged
  context:
  - Linking how-to to example pipeline