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
- Claude Code skill wraps the CLI for agents.
- SDKs for the same workflows from code.
- Export all media as a tar with a manifest.