@paperpod/cli

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

Installation

``bash
npm install -g @paperpod/cli
`

Updating

`bash
npm update -g @paperpod/cli
`

Quick Start

`bash


1. Get token

curl -X POST https://paperpod.dev/login -d '{"email":"you@email.com"}'

Check email → click magic link → copy token

2. Install & login

npm install -g @paperpod/cli
ppod login

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

$3

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

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

$3

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

$3

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

$3

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

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

$3

| Command | Description |
|---------|-------------|
| ppod ai | Text generation (LLM) |
| ppod ai --model | Use specific model |
| ppod ai:embed | Generate embeddings |
| ppod ai:image | Generate image |
| ppod ai:image -o | Save image to file |
| ppod ai:transcribe

$3

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

$3

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

$3

| 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 | Command timeout (default: 60000) |
| --json | Output as JSON |
| -o, --output | Write output to file |
| --trace | Capture browser trace (browser:* commands) |
| --model | AI model to use |
| --language | Language for interpret (python/javascript) |
| --width | Screenshot/image width |
| --height | Screenshot/image height |
| --full-page | Full page screenshot |

Examples

`bash


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:

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

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

Programmatic Usage

`typescript
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