npm package: @playvideo/playvideo-cli
Description: CLI for PlayVideo API - Upload, manage, and stream videos from the command line
Author: PlayVideo
Latest version: 1.0.0

# PlayVideo CLI

[![npm version](https://img.shields.io/npm/v/@playvideo/playvideo-cli.svg)](https://www.npmjs.com/package/@playvideo/playvideo-cli)
[![npm downloads](https://img.shields.io/npm/dm/@playvideo/playvideo-cli.svg)](https://www.npmjs.com/package/@playvideo/playvideo-cli)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

Command-line interface for PlayVideo API. Upload, manage, and stream videos from your terminal.

## Features

- **Interactive mode** - Guided workflows for uploads and management
- **Video management** - List, inspect, and delete videos
- **Collections** - Organize videos into collections
- **Authentication** - OAuth login or API key support
- **Webhooks** - Configure and test webhooks
- **API keys** - Create and manage API keys
- **Embed settings** - Inspect embed configuration
- **Usage** - View plan limits and usage

## Installation

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

Or run without installing:

```bash
npx @playvideo/playvideo-cli <command>
```

## Quick Start

### Interactive Mode (Recommended)

```bash
playvideo
```

The CLI will guide you through authentication and present a menu:

```
Upload Video     - Upload and transcode videos
Manage Videos    - List, view, delete videos  
Collections      - Organize videos into collections
Webhooks         - Configure event notifications
API Keys         - Manage API keys
Embed Settings   - Customize video player
Account          - View account & usage
```

### Command Mode

```bash
# Login (opens browser for authentication)
playvideo auth login

# Create a collection
playvideo collections create "My Videos"

# Upload a video
playvideo upload video.mp4 -c my_videos

# Check status
playvideo videos list
```

**Short alias:** You can use `pv` instead of `playvideo` for all commands:

```bash
pv auth login
pv upload video.mp4 -c my_videos
```

## Authentication

The CLI uses browser-based OAuth for secure authentication.

```bash
# Login via browser (recommended)
playvideo auth login

# Or use an API key directly
playvideo auth login --api-key play_live_xxx

# Check auth status
playvideo auth status

# Logout
playvideo auth logout

# Set custom API URL (for self-hosted)
playvideo auth set-url https://video.yourdomain.com
```

## Commands

### Collections

```bash
# List all collections
playvideo collections list
pv col ls

# Create a collection
playvideo collections create "Tutorial Videos" -d "Video tutorials"

# Show collection details
playvideo collections show tutorial_videos

# Delete a collection (requires --force)
playvideo collections delete tutorial_videos --force
```

### Videos

```bash
# List all videos
playvideo videos list
pv vid ls

# Filter by collection or status
playvideo videos list -c my_collection
playvideo videos list -s COMPLETED
playvideo videos list -s PROCESSING

# Show video details
playvideo videos show <video-id>

# Delete a video
playvideo videos delete <video-id>
```

### Upload

```bash
# Upload a video
playvideo upload video.mp4 -c my_collection

# Upload and wait for processing
playvideo upload video.mp4 -c my_collection --wait
```

### Usage & Billing

```bash
# Check current usage and limits
playvideo usage
```

### API Keys

```bash
# List API keys
playvideo api-keys list
pv keys ls

# Create a new API key
playvideo api-keys create "My App"

# Delete an API key
playvideo api-keys delete <key-id>
```

### Webhooks

```bash
# List webhooks
playvideo webhooks list

# Create a webhook
playvideo webhooks create https://example.com/webhook -e video.completed,video.failed

# Test a webhook
playvideo webhooks test <webhook-id>

# Delete a webhook
playvideo webhooks delete <webhook-id>
```

### Embed Settings

```bash
# Show current embed settings
playvideo embed show
```

### Account & Domain Settings

```bash
# Show account settings
playvideo config show
```

## Examples

### Upload and Get Stream URL

```bash
# Upload and wait for processing
playvideo upload tutorial.mp4 -c tutorials --wait

# Output:
# Uploading tutorial.mp4 (125.5 MB)...
# Uploaded: clx1234567890
# Status: PENDING
#
# Waiting for processing...
# Processing complete!
#
# Playlist URL: https://cdn.playvideo.dev/{userId}/.../playlist.m3u8
# Thumbnail: https://cdn.playvideo.dev/{userId}/.../thumb.jpg
```

### Batch Upload

```bash
# Upload multiple files
for f in videos/*.mp4; do
  playvideo upload "$f" -c my_collection
done
```

### CI/CD Integration

```yaml
# GitHub Actions example
- name: Upload video
  env:
    PLAYVIDEO_API_KEY: ${{ secrets.PLAYVIDEO_API_KEY }}
  run: |
    npx @playvideo/playvideo-cli upload ./demo.mp4 -c releases --wait
```

## Configuration

The CLI stores configuration in `~/.config/playvideo/config.json`.

### Environment Variables

| Variable | Description |
|----------|-------------|
| `PLAYVIDEO_API_KEY` | API key (overrides saved key) |
| `PLAYVIDEO_URL` | API base URL (for self-hosted instances) |
| `CI` | Set to `true` to disable interactive mode |
| `PLAYVIDEO_NO_INTERACTIVE` | Set to `true` to disable interactive mode |

```bash
# Use environment variable instead of saved key
export PLAYVIDEO_API_KEY=play_live_xxx
playvideo videos list

# Disable interactive mode in CI/CD
CI=true playvideo upload video.mp4 -c my_collection
```

## Self-Hosted

Point the CLI to your self-hosted PlayVideo instance:

```bash
# Set custom URL
playvideo auth set-url https://video.yourdomain.com

# Or use environment variable
PLAYVIDEO_URL=https://video.yourdomain.com playvideo videos list
```

## Troubleshooting

### "API key not configured"

Run `playvideo auth login` or set `PLAYVIDEO_API_KEY` environment variable.

### "Collection not found"

Make sure the collection exists. List collections with `playvideo col ls`.

### Upload fails with "File too large"

Check your plan limits with `playvideo usage`. Upgrade for larger file sizes.

### Browser doesn't open for login

If the browser doesn't open automatically, the CLI will print the URL. Copy and paste it manually.

## Links

- [Documentation](https://playvideo.dev/docs)
- [API Reference](https://playvideo.dev/docs/api)
- [Dashboard](https://playvideo.dev/dashboard)

## License

MIT