@paperpod/cli 0.1.0

package/README.md

@@ -0,0 +1,245 @@
+# @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
+# Get a token (one-time)
+curl -X POST https://paperpod.dev/login -d '{"email":"you@email.com"}'
+# Click link in email → copy token
+
+# Login (saves token)
+ppod login pp_sess_...
+
+# Discover all commands
+ppod help
+
+# Get help for specific command
+ppod exec --help
+ppod browser:screenshot --help
+
+# Execute commands
+ppod exec "ls -la"
+ppod exec "python -c 'print(2+2)'"
+```
+
+## 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 |
+
+### 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 |
+
+### 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:sessions` | List active browser sessions |
+| `ppod browser:limits` | Check browser limits |
+
+**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 |
+
+### 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"
+ppod expose 3000
+
+# 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
+
+# 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

package/dist/cli.d.ts

@@ -0,0 +1,22 @@
+#!/usr/bin/env node
+/**
+ * PaperPod CLI
+ *
+ * Agent-native sandbox execution from your terminal.
+ *
+ * Usage:
+ *   ppod exec "ls -la"               # Execute a command
+ *   ppod exec "npm test" --timeout 120000
+ *   ppod write /app/script.py ./local.py
+ *   cat file.txt | ppod write /app/file.txt
+ *   ppod read /app/output.txt
+ *   ppod ls /app
+ *   ppod login                        # Save token
+ *   ppod status                       # Check connection
+ *
+ * Environment:
+ *   PAPERPOD_TOKEN      - Authentication token (overrides config file)
+ *   PAPERPOD_API_URL    - API URL (default: wss://paperpod.dev/ws)
+ */
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AACA;;;;;;;;;;;;;;;;;;GAkBG"}