npm package: @paperpod/cli
Description: PaperPod CLI - Agent-native sandbox execution from your terminal
Latest version: 0.1.8

# @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 <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

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