Images Videos Audio Pricing Docs View as Markdown (Agent) Get started
Human Agent

CLI

The 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 and Video transcripts.

Audio

Original audio hosting (CLI 0.24.0+). See Host & transcribe 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) 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.

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.

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 wraps the batch endpoint and posts a sticky PR comment.

Source: github.com/pixelvault-dev/cli

Next steps