plbx

CLI for Playbox Platform — deploy playable ads, manage projects, and process assets.

Installation

npm install -g @playbox-ai/plbx

Quick Start

# Login via browser
plbx login

# Deploy current directory
plbx deploy

# Deploy to a specific project
plbx deploy --project my-project

Commands

Authentication

plbx login                        # Browser OAuth
plbx login --token <api_key>      # API token (for CI/CD)
plbx logout
plbx whoami

Deploy

plbx deploy                            # Interactive, private by default
plbx deploy --prod                     # Deploy as public
plbx deploy --project <slug>           # Deploy to specific project
plbx deploy --name <name>              # Custom deployment name
plbx deploy --entry <file>             # Custom entry file (default: index.html)
plbx deploy --dir <path>               # Deploy specific directory
plbx deploy --force                    # Overwrite existing deployment
plbx deploy --orientation portrait     # Lock orientation: none | portrait | landscape

Manage Deployments

plbx list                         # List all deployments
plbx list --project <slug>        # List by project
plbx delete <deployment-slug>     # Delete deployment (with confirmation)
plbx delete <slug> --force        # Skip confirmation

Asset Tools

# Extract assets from a playable
plbx extract playable.html                     # From local file
plbx extract https://example.com/ad.html       # From URL
plbx extract playable.html --info              # Show info without extracting
plbx extract playable.html -o ./assets         # Custom output directory

# Compress PNG images
plbx compress ./images --recursive             # Auto mode (lossy/lossless)
plbx compress image.png --preset web           # Presets: web, fast, max, high-compression
plbx compress image.png --mode lossy -q 70-85  # Manual quality

# Convert images
plbx convert ./images -f webp --recursive      # Convert to WebP
plbx convert image.png -f jpeg --quality 85    # Convert with quality
plbx convert image.png --width 800             # Resize on convert
plbx convert image.png --info                  # Show metadata

Init Config

plbx init          # Create .plbx.json interactively
plbx init --force  # Overwrite existing config

Configuration

Create a .plbx.json file in your project directory:

{
  "name": "my-playable",
  "project": "my-project",
  "entryPoint": "index.html"
}

plbx deploy reads this config automatically if present.

CI/CD

Generate an Organization Deploy Key in Playbox Settings, then:

plbx login --token $PLBX_API_KEY
plbx deploy --project my-project --prod --force

CI / CD — non-interactive deploy

plbx ci deploy deploys without any prompts. Use it in CI pipelines.

Authentication

Provide the API token via environment variable (no plbx login needed):

• PLBX_TOKEN — API token (preferred)
• PLBX_API_KEY — alternative name for the token
• PLBX_API_URL — override the API endpoint (optional)
• PLBX_PROJECT — default project slug (optional)

Or pass --token <token> directly.

Usage

plbx ci deploy --prod -p my-project -n my-playable --json

| Flag | Description | |---|---| | --prod | Deploy as public (default: private) | | -p, --project <slug> | Project slug (falls back to PLBX_PROJECT, then .plbx.json) | | -n, --name <name> | Deployment name (default: directory name) | | -e, --entry <file> | Entry file (default: index.html) | | -d, --dir <dir> | Directory to deploy (default: current) | | -o, --orientation <lock> | none, portrait, or landscape | | --no-overwrite | Fail instead of replacing an existing deployment | | --json | Emit machine-readable JSON to stdout | | --token <token> | API token (or env PLBX_TOKEN / PLBX_API_KEY) |

An existing deployment with the same name is overwritten by default. Pass --no-overwrite to fail instead.

Exit codes

| Code | Meaning | Safe to retry the job? | |---|---|---| | 0 | Success | — | | 1 | Config / validation / auth error | No | | 2 | Transient error (network / upload / 5xx after retries) | Yes |

GitHub Actions example

- name: Deploy playable
  env:
    PLBX_TOKEN: ${{ secrets.PLBX_API_KEY }}
  run: npx @playbox-ai/plbx ci deploy --prod -p my-project -n my-playable --json

Requirements

• Node.js ≥ 18