@paperpod/cli

PaperPod CLI - Agent-native sandbox execution from your terminal.

Installation

npm install -g @paperpod/cli

Updating

npm update -g @paperpod/cli

Quick Start

# 1. Get token
curl -X POST https://paperpod.dev/login -d '{"email":"[email protected]"}'
# Check email → click magic link → copy token

# 2. Install & login
npm install -g @paperpod/cli
ppod login <your-token>

# 3. Try it
ppod exec "echo hello world"
ppod status

Authentication

| Method | How | Best for | |--------|-----|----------| | CLI login | ppod login pp_sess_... | Interactive use | | Env var | export PAPERPOD_TOKEN=pp_sess_... | Scripts, CI/CD |

Tokens are stored in ~/.paperpod/config.json (mode 0600). Tokens valid for 15 days.

Commands

Sandbox

| Command | Description | |---------|-------------| | ppod exec <cmd> | Run shell command | | ppod exec <cmd> --no-stream | Run without streaming output | | ppod write <path> [file] | Write file (stdin if no file) | | ppod read <path> | Read file | | ppod read <path> -o <file> | Save to local file | | ppod ls <path> | List directory |

Working directory is /workspace — relative paths like file.txt resolve to /workspace/file.txt.

Processes

| Command | Description | |---------|-------------| | ppod start <cmd> | Start background process | | ppod ps | List running processes | | ppod kill <id> | Stop a process |

Ports

| Command | Description | |---------|-------------| | ppod expose <port> | Get public URL for port (-q for URL only) |

Browser

All browser commands support both browser: prefix and short form.

| Command | Description | |---------|-------------| | ppod browser:screenshot <url> | Capture webpage | | ppod browser:screenshot <url> -o <file> | Save screenshot to file | | ppod browser:pdf <url> | Generate PDF | | ppod browser:pdf <url> -o <file> | Save PDF to file | | ppod browser:scrape <url> [selector] | Scrape elements (default: body) | | ppod browser:markdown <url> | Extract markdown from page | | ppod browser:content <url> | Get rendered HTML | | ppod browser:trace start | Start browser tracing | | ppod browser:trace stop -o trace.zip | Stop tracing, save file | | ppod browser:test <url> '<assertions>' | Run Playwright assertions | | ppod browser:acquire | Acquire reusable session | | ppod browser:connect <id> | Connect to existing session | | ppod browser:sessions | List active browser sessions | | ppod browser:limits | Check browser limits |

Session Management: By default, each browser command creates an ephemeral session. Use browser:acquire for multi-command workflows, --trace to capture Playwright traces.

Tip: Use ppod browser:screenshot --help to see all options for any command.

AI

| Command | Description | |---------|-------------| | ppod ai <prompt> | Text generation (LLM) | | ppod ai <prompt> --model <model> | Use specific model | | ppod ai:embed <text> | Generate embeddings | | ppod ai:image <prompt> | Generate image | | ppod ai:image <prompt> -o <file> | Save image to file | | ppod ai:transcribe <audio> | Transcribe audio to text | | ppod ai:models | List available AI models |

Code

| Command | Description | |---------|-------------| | ppod interpret <code> | Rich output (charts, images) | | ppod interpret <code> --language python | Specify language |

Memory (Persistent Storage)

| Command | Description | |---------|-------------| | ppod mem:write <path> [file] | Write to persistent storage | | ppod mem:read <path> | Read from persistent storage | | ppod mem:ls [prefix] | List memory files | | ppod mem:rm <path> | Delete from memory | | ppod mem:usage | Check quota (10MB) |

Account

| Command | Description | |---------|-------------| | ppod login [token] | Save token | | ppod logout | Clear token | | ppod status | Connection info | | ppod balance | Check credits | | ppod help | Show all commands | | ppod version | Show version |

Options

| Option | Description | |--------|-------------| | -h, --help | Show help for specific command | | --timeout <ms> | Command timeout (default: 60000) | | --json | Output as JSON | | -o, --output <file> | Write output to file | | --trace <file> | Capture browser trace (browser:* commands) | | --model <model> | AI model to use | | --language <lang> | Language for interpret (python/javascript) | | --width <px> | Screenshot/image width | | --height <px> | Screenshot/image height | | --full-page | Full page screenshot |

Examples

# Multi-step workflow
ppod exec "npm init -y"
ppod exec "npm install express"
ppod write /app/server.js ./server.js
ppod start "node /app/server.js"  # Server must bind to 0.0.0.0
ppod expose 3000  # Returns stable URL: https://3000-{id}-p3000_v1.paperpod.work

# File operations
echo "print('hello')" | ppod write /app/script.py
ppod exec "python /app/script.py"
ppod read /app/output.txt -o ./local.txt

# Browser automation
ppod browser:screenshot https://example.com -o page.png
ppod browser:pdf https://example.com -o page.pdf
ppod browser:markdown https://example.com -o page.md
ppod browser:scrape https://news.ycombinator.com "a.titlelink"

# Browser tracing (debug)
ppod browser:screenshot https://example.com --trace debug.zip

# AI generation
ppod ai "Write a haiku about coding"
ppod ai:image "A sunset over mountains" -o sunset.png
ppod ai:embed "This is a test sentence"
ppod ai:transcribe audio.mp3
ppod ai:models                       # List all available models

# Code interpreter (rich output)
ppod interpret "import matplotlib.pyplot as plt; plt.plot([1,2,3]); plt.savefig('plot.png')"

# Browser testing
ppod test https://example.com '[{"type":"visible","selector":"h1"}]'

# Persistent storage
echo '{"step": 3}' | ppod mem:write state.json
ppod mem:read state.json
ppod mem:ls

Exit Codes

The CLI returns the exit code of the executed command:

ppod exec "npm test" && ppod exec "npm run build"

if ppod exec "test -f /app/config.json"; then
  echo "Config exists"
fi

Programmatic Usage

import { PaperpodTransport } from "@paperpod/cli";

const transport = new PaperpodTransport();
await transport.connect();

// Execute commands
const result = await transport.exec("ls -la");
console.log(result.stdout);

// File operations
await transport.writeFile("/app/script.py", "print('hello')");
const content = await transport.readFile("/app/script.py");

// AI
const text = await transport.aiGenerate("Write a poem");
const embeddings = await transport.aiEmbed("Hello world");
const image = await transport.aiImage("A cat");

// Browser
const screenshot = await transport.browserScreenshot("https://example.com");
const markdown = await transport.browserMarkdown("https://example.com");

// Memory
await transport.memoryWrite("state.json", '{"step": 1}');
const state = await transport.memoryRead("state.json");

transport.disconnect();

Environment Variables

| Variable | Description | |----------|-------------| | PAPERPOD_TOKEN | Auth token (overrides config file) | | PAPERPOD_API_URL | WebSocket URL (default: wss://paperpod.dev/ws) |

License

MIT