<!-- Markdown twin of https://pixelvault.dev/docs/cli/ -->

# CLI

The [pixelvault-cli](https://www.npmjs.com/package/pixelvault-cli) package provides agent-friendly media hosting and custom-domain management from any terminal. URLs go to stdout; progress and resume identifiers go to stderr, so the output pipes cleanly. Custom domains and `--branded` require version 0.26.0 or newer.

```
npm install -g pixelvault-cli@latest
```

## Core commands

Or use it directly with `npx`:

```
# Create account, stores API key
npx pixelvault-cli register
# Headless/agent signup, no password
npx pixelvault-cli register --email you@example.com --passwordless
# Prints CDN URL to stdout
npx pixelvault-cli upload photo.jpg
# One URL per line
npx pixelvault-cli list
# Print URL, or download with -o (and -t to transform)
npx pixelvault-cli get img_abc
# Silent on success
npx pixelvault-cli delete img_abc
# Download all project media and derived artifacts as a .tar with a manifest
npx pixelvault-cli export
```

## Upload options

Bulk-upload with a shell glob, organize into a folder, upload privately (signed URL), or emit the full JSON:

```
# Bulk upload (shell glob), grouped in a folder
npx pixelvault-cli upload *.png --folder icons
# Full JSON includes canonical url and optional branded_url
npx pixelvault-cli upload shot.png --json
# Prefer the active custom domain when ready; canonical fallback
npx pixelvault-cli upload shot.png --branded
# Private signed URL (needs a secret key)
npx pixelvault-cli upload secret.png --private
# …with a 24h link lifetime (default 7d)
npx pixelvault-cli upload secret.png --private --expires 24h
```

## Video

Upload, social-ready optimization, and transcript/storyboard enrichment (CLI 0.23.0+ for `enrich-video`). `upload --social` uploads, waits for optimization, and prints the post-ready URL; JSON output keeps both `original_url` and `social_ready_url`.

```
# Upload, wait for the social-ready copy, print the post-ready URL
npx pixelvault-cli upload launch-demo.mp4 --social
# Upload a local MP4, start enrichment, wait, return typed JSON artifacts
npx pixelvault-cli enrich-video demo.mp4 --json
# Private local upload; signed original and artifact links expire together
npx pixelvault-cli enrich-video demo.mp4 --private --expires 12h --json
# Resume the active/completed server job for an existing asset
npx pixelvault-cli enrich-video vid_abc --timeout 1200 --json
# Return queued/running state immediately
npx pixelvault-cli enrich-video vid_abc --no-wait --json
```

`enrich-video` reports the asset and stable job IDs before polling, backs off for up to 600 seconds by default, and returns explicit queued, running, complete, failed, or timeout states. A local timeout does not cancel the server job. `--no-wait` returns immediately; `--timeout 1200` changes only the local wait bound. For a new private upload use `--private --expires 12h`; an existing asset keeps its visibility. JSON includes typed artifact URLs with visibility and signed-link expiry, and omits transcript/storyboard URLs until they exist. URL sources are not accepted by this command: import with `pixelvault upload <url> --json`, then enrich the returned `vid_` ID. Walkthroughs: [Social-ready video](/docs/guides/social-ready-video/) and [Video transcripts](/docs/guides/video-transcripts/).

## Audio

Original audio hosting (CLI 0.24.0+). See [Host & transcribe audio](/docs/guides/audio/).

```
# Local original; prints the CDN URL
npx pixelvault-cli audio upload episode.mp3
# Private link expires in 12h; the asset is deleted after 7d
npx pixelvault-cli audio upload episode.m4a --private --link-expires 12h --delete-after 7d --json
# Secure server-side URL import with replay safety
npx pixelvault-cli audio upload https://media.example/episode.ogg --idempotency-key episode-v1 --json
# Resume lifecycle work from the stable aud_ ID
npx pixelvault-cli audio get aud_abc --json
npx pixelvault-cli audio sign aud_abc --expires 1h
npx pixelvault-cli audio delete aud_abc
```

## Optimize images locally

`optimize` compresses images **on your machine** — no account, no API key, nothing is uploaded. It resizes, converts and strips metadata, never writes a file bigger than the original, and is safe to re-run in a hook or CI:

```
# Writes hero.optimized.png next to the original
npx pixelvault-cli optimize hero.png
# A folder to WebP, capped at 1600px wide, into ./optimized
npx pixelvault-cli optimize ./shots -r --format webp --max-width 1600 --out-dir ./optimized
# Preview the saving without writing anything
npx pixelvault-cli optimize ./assets -r --dry-run
# Optimize, upload, and print the CDN URL (needs an API key)
npx pixelvault-cli optimize hero.png --host
```

Supports JPG, PNG, WebP and AVIF (needs Node 20.9+). For an image that is already hosted, use the CDN params instead (`?fmt=webp&q=75&w=1600`, see [transforms](/docs/transforms/)) or the `optimized_url` returned on upload.

## Custom domains

Attach a customer-owned hostname to the active project, inspect account plan capacity, and refresh DNS/certificate state. Once ready, media JSON includes `branded_url`; `--branded` selects it with canonical fallback. See [Custom domains](/docs/guides/custom-domains/).

```
pixelvault domains list
pixelvault domains add media.example.com
pixelvault domains refresh dom_abc123
pixelvault domains delete dom_abc123
```

## Webhooks

Manage signed callback endpoints (Starter and Pro). See [Webhooks](/docs/webhooks/).

```
pixelvault webhooks create https://api.example.com/pixelvault-events
pixelvault webhooks list
pixelvault webhooks deliveries <id>
```

## CI and headless agents

Set `PIXELVAULT_API_KEY` and the CLI skips interactive login:

```
export PIXELVAULT_API_KEY=pv_live_xxx
npx pixelvault-cli upload screenshot.png
```

For CI screenshots on GitHub, the [screenshots action](/docs/guides/ci-screenshots/) wraps the batch endpoint and posts a sticky PR comment.

Source: [github.com/pixelvault-dev/cli](https://github.com/pixelvault-dev/cli)

## Next steps

-   [Claude Code skill](/docs/claude-code/) wraps the CLI for agents.
-   [SDKs](/docs/sdks/) for the same workflows from code.
-   [Export all media](/docs/guides/export-media/) as a tar with a manifest.
