# plbx

CLI for [Playbox Platform](https://plbx.ai) — deploy playable ads, manage projects, and process assets.

## Installation

```bash
npm install -g @playbox-ai/plbx
```

## Quick Start

```bash
# Login via browser
plbx login

# Deploy current directory
plbx deploy

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

## Commands

### Authentication

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

### Deploy

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

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

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

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

## Configuration

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

```json
{
  "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](https://app.plbx.ai/settings/organization/deploy-keys), then:

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

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

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