Skip to content
pixelvault-devPublic

About

CLI for PixelVault — agent-first image hosting

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

pixelvault-cli

npm CI

CLI for PixelVault — agent-first media hosting for developers and AI coding agents.

Install

npm install -g pixelvault-cli

Or use directly with npx:

npx pixelvault-cli upload photo.jpg

Quick Start

# Create an account (prompts for email + optional password)
pixelvault register

# Non-interactive / agent signup — no password, key saved automatically
pixelvault register --email you@example.com --passwordless

# Upload an image — prints the URL to stdout
pixelvault upload screenshot.png
# https://img.pixelvault.dev/proj_abc/img_xyz.png

# Upload a PDF — the URL always downloads the original file
pixelvault upload report.pdf
# https://img.pixelvault.dev/proj_abc/img_xyz.pdf

# Upload multiple images
pixelvault upload *.png --folder screenshots

# Upload a local MP4 without buffering it in memory
pixelvault upload demo.mp4
# https://img.pixelvault.dev/proj_abc/vid_xyz.mp4

# Or import a public MP4 without downloading it first
pixelvault upload "https://media.example.com/demo.mp4"
# https://img.pixelvault.dev/proj_abc/vid_xyz.mp4

# Private video + expiry-matched signed poster URL
pixelvault upload demo.mp4 --private --expires 12h --json

# Upload, convert, wait, and print a social-ready H.264/AAC fast-start URL
pixelvault upload demo.mp4 --social

# Convert an existing hosted video
pixelvault optimize-video vid_xyz

# Upload a local MP4, enrich it, wait, and print original/transcript/storyboard URLs
pixelvault enrich-video demo.mp4

# Resume the same server job without uploading again
pixelvault enrich-video vid_xyz

# Host and transcribe local audio; prints original/transcript URLs after completion
pixelvault audio enrich episode.mp3

# Resume without another upload or duplicate job
pixelvault audio enrich aud_xyz --timeout 1200 --json

# Enqueue and return the stable asset/job IDs immediately
pixelvault audio enrich episode.m4a --no-wait --json

# Hosting-only, discovery, fresh private links, or deletion
pixelvault audio upload "https://media.example.com/episode.ogg" --json
pixelvault audio list --folder podcasts --json
pixelvault audio sign aud_xyz --expires 1h
pixelvault audio delete aud_xyz

# List your images
pixelvault list

# Get an image's URL, or download it (optionally transformed)
pixelvault get img_xyz                                     # prints the CDN URL
pixelvault get img_xyz -o photo.png                        # download the original
pixelvault get img_xyz -o thumb.webp -t "w=400&fmt=webp"   # download a transformed variant

# Delete an image
pixelvault delete img_xyz

# Check quota before a bulk upload
pixelvault usage

# Manage API keys (secret key required)
pixelvault keys list
KEY=$(pixelvault keys create --label ci)   # raw key on stdout, shown once
pixelvault keys revoke key_abc123

# Attach a custom domain to the active project
pixelvault domains add media.example.com
pixelvault domains refresh dom_abc123
pixelvault upload photo.jpg --branded

# Export everything — manifest plus all project media and derived artifacts (no lock-in)
pixelvault export -o pixelvault-export.tar

Agent Integration

The CLI is designed for AI coding agents. Output contract:

  • upload prints only the URL to stdout for images, PDFs, and MP4 videos. PDFs are served as forced downloads and do not support image transforms. Add --optimized for the smaller WebP/AVIF image variant; it falls back to the original URL for SVG, GIF, PDF, and private images
  • Media JSON keeps the canonical url and includes optional branded_url when the active project has a ready custom domain. Add --branded to upload, list, get, or audio upload|list|get|update|sign to print it, with canonical fallback
  • upload streams local MP4 files and automatically switches to multipart upload above 100 MB. It also accepts public MP4 URLs and has PixelVault import them directly. --private [--expires 12h] returns signed video and poster URLs. --social requests a separate H.264/AAC fast-start copy, waits for it, and prints the post-ready URL while preserving the original; --json returns both original_url and social_ready_url. Every video response includes duration, dimensions, codecs, fast-start status, and social-compatibility warnings. Video limits: Free 25 MB, Starter 100 MB, Pro 250 MB
  • optimize-video converts an existing upload, waits for the derived social-ready URL, and prints only that URL; --no-wait enqueues and returns, while --json returns the full state
  • enrich-video uploads a local MP4 or reuses an existing vid_ asset, starts or resumes transcript + storyboard enrichment, and reports the stable asset/job IDs before bounded polling
  • audio upload hosts original MP3, PCM/float WAV, AAC M4A, or Opus/Vorbis OGG from a local path or public URL; actual bytes are validated. The approved global maximum is 25,000,000 bytes (not a plan allowance). --json returns the stable aud_ ID, detected codec/duration/sample rate/channels, privacy, and expiry
  • audio enrich accepts the same local or imported sources or an existing aud_ ID, starts or resumes transcription, and returns original plus available text, WebVTT, and timestamped JSON artifacts. It reports stable asset/job IDs before bounded polling; local timeout never cancels the server job
  • audio list|get|update|sign|delete cover discovery, organization, fresh private original/transcript links, and deletion without public fallbacks
  • Image and PDF uploads support --idempotency-key and --dedupe; folder, image optimization, reuse, metadata, and AI-description options are rejected for MP4 files and URLs
  • list outputs one URL per line
  • meta prints the stored metadata as JSON
  • delete outputs nothing on success
  • All human messages go to stderr
  • --json flag for structured output
# In agent workflows
URL=$(npx pixelvault-cli upload screenshot.png)
echo "Uploaded to: $URL"

Environment Variables

For CI/CD and headless agent usage:

export PIXELVAULT_API_KEY=pv_live_xxx
npx pixelvault-cli upload build-output.png

Commands

Command Description
register Create a new account
login Log in to existing account
upload <files-or-urls...> Upload images, PDFs, MP4 files, or public MP4 URLs (prints URLs to stdout)
generate <prompt> Generate an image from a prompt and host it (prints the URL; spends monthly AI credits)
list List uploaded images (filter by --tag, --search, --meta)
tags List the AI tags on your described images with counts
describe <id> Write an AI description (alt text, caption, OCR, tags) for an image you already uploaded
optimize <files...> Compress images locally — no account needed (resize, convert, strip metadata; never writes a bigger file)
optimize-video <id> Preserve a hosted MP4 and create a social-ready H.264/AAC fast-start copy
enrich-video <file.mp4|vid_id> Upload or resume transcript + storyboard enrichment, with bounded polling and structured artifact access data
audio upload <path-or-url> Host original MP3/WAV/M4A/OGG bytes with privacy, TTL, metadata, organization, and retry safety
audio enrich <path-or-url-or-aud_id> Host or resume audio transcription with bounded polling and typed artifact access data
audio list|get|update|sign|delete Discover and manage audio and transcript lifecycle by stable aud_ asset ID
get <id> Get an image's URL/metadata, or download it (optionally transformed)
meta <id> Replace an image's custom metadata (--meta k=v, --metadata '<json>', or --clear)
delete <id> Delete an image
export Export all project media and derived artifacts with a manifest
usage Show plan, period, storage/upload/bandwidth usage and limits, and AI generation credits
keys list|create|revoke List, create, and revoke the project's secret API keys
domains list|add|refresh|delete Manage the active project's custom domain and inspect account plan capacity
upgrade <starter|pro> Print a Stripe Checkout URL to subscribe (live key; you pay in the browser)
billing Print a Stripe billing-portal URL to change plan, update payment details or cancel (live key)
whoami Show current auth state
config get|set|show Manage CLI configuration

Upload Options

pixelvault upload photo.jpg              # Single file
pixelvault upload *.png --folder icons   # Bulk with folder
pixelvault upload shot.png --json        # Full JSON response
pixelvault upload shot.png --branded     # Ready custom-domain URL; canonical fallback
pixelvault upload demo.mp4 --social        # Upload + wait; prints the post-ready URL
pixelvault upload demo.mp4 --social --json # Includes original_url and social_ready_url
pixelvault upload "https://media.example.com/demo.mp4" --private --expires 12h --social --json
pixelvault upload shot.png --meta env=prod --meta run=42   # Tag with custom metadata (key=value, repeatable)
pixelvault upload shot.png --metadata '{"n":3}'           # ...or a JSON object (typed values)
pixelvault upload shot.png --describe                      # AI alt text + caption + OCR in the background
pixelvault upload shot.png --describe --wait --json        # ...wait (~10s) and include it in the JSON

MP4 file and URL uploads support --private, --expires, --social, and --json; image-only options such as --folder, --optimized, reuse, metadata, and AI descriptions are rejected. PixelVault stores the original video unchanged and returns a generated JPEG poster_url when frame extraction succeeds. --social creates a separate H.264/AAC fast-start copy, waits for it, and prints that URL; JSON output retains both original_url and social_ready_url. The response also reports duration, dimensions, codecs, fast-start layout, social_compatible, and actionable compatibility_warnings; questionable MP4s are preserved rather than rejected. Remote imports require a public HTTP(S) URL whose response includes a valid Content-Length; PixelVault fetches the video directly. Maximum video size is 25 MB on Free, 100 MB on Starter, and 250 MB on Pro.

Social-ready Video Options

pixelvault upload demo.mp4 --social        # upload + wait; prints social-ready URL
pixelvault upload demo.mp4 --social --json # original and social-ready URLs
pixelvault optimize-video vid_xyz          # convert an existing upload
pixelvault optimize-video vid_xyz --no-wait
pixelvault optimize-video vid_xyz --json

The source must be at most 100 MB and 60 seconds. Free includes 2 output minutes per month, Starter 30 minutes, and Pro 120 minutes. The command is idempotent: an already-compatible original is returned unchanged, a running job is reused, and a completed derivative is returned without another conversion. Failed jobs refund their reserved seconds.

Video Enrichment Options

pixelvault enrich-video demo.mp4                 # upload + enrich + wait
pixelvault enrich-video demo.mp4 --private       # private original and signed artifacts
pixelvault enrich-video demo.mp4 --no-wait --json
pixelvault enrich-video vid_xyz                  # resume/reuse an existing job
pixelvault enrich-video vid_xyz --timeout 1200 --json

The command accepts a local MP4 or an existing PixelVault video asset ID. URL sources are intentionally rejected: import one with pixelvault upload <url> --json, then pass the returned vid_ ID. Enrichment accepts sources from 1 second through 10 minutes and at most 100 MB. It is idempotent while queued, running, or complete; retrying a failed job creates a new job ID.

Polling backs off from one to ten seconds and stops after 600 seconds by default (--timeout changes the local bound). A timeout exits non-zero but does not cancel the server job; rerun the printed resume command. --no-wait returns the queued/running state immediately. Human output keeps URLs on stdout and progress, asset/job IDs, artifact types, visibility, and signed-link expiry on stderr. --json returns one object with asset_id, job_id, explicit state, resume_command, and only the artifact URLs that currently exist. Private artifacts inherit the video's privacy; the command never changes an existing asset's visibility.

Videos without audio return a skipped transcript and still produce a storyboard. Quota, duration, size, unavailable-metadata, failed-job, and local-timeout states exit explicitly. Monthly source minutes are Free 2, Starter 30, and Pro 120; check pixelvault usage for the current allowance and reset.

Audio Hosting

pixelvault audio upload episode.wav --idempotency-key episode-v1 --json
pixelvault audio enrich episode.mp3 --json
pixelvault audio enrich "https://media.example.com/episode.m4a" --folder podcasts --json
pixelvault audio enrich private.ogg --private --link-expires 12h --delete-after 7d --json
pixelvault audio enrich aud_xyz --no-wait --json
pixelvault audio enrich aud_xyz --timeout 1200 --json
pixelvault audio list --folder podcasts --json
pixelvault audio get aud_xyz --branded
pixelvault audio get aud_xyz --json
pixelvault audio update aud_xyz --folder archive --meta episode=7 --json
pixelvault audio sign aud_xyz --expires 1h --json
pixelvault audio delete aud_xyz

Audio hosting preserves original bytes and accepts MP3, PCM integer/IEEE-float WAV, AAC in M4A, and Opus or Vorbis in OGG. PixelVault validates the actual container and codec, not only the extension or supplied MIME type. The approved global original-file maximum is 25,000,000 bytes; it is not a plan allowance or capacity reservation. Existing storage, upload, bandwidth, private-asset, and retention rules apply.

Audio enrichment accepts hosted originals up to 25,000,000 bytes and 10 minutes. It produces plain text, WebVTT, and timestamped JSON when available. Audio and video enrichment share the existing plan allowance. It does not produce storyboards, summaries, chapters, show notes, or promo copy.

--link-expires controls only private bearer URLs. --delete-after deletes the original and transcript artifacts, including cancellation and quota refund for an active job. Local uploads with --idempotency-key send a byte checksum; exact retries return the original asset, while conflicting inputs fail. Private assets never fall back to public URLs; audio sign --json mints fresh original and transcript links with one expiry. Audio editing, conversion, and HLS/DASH remain unsupported.

Generate Options

pixelvault generate "flat vector hero, a robot at a laptop, no text"   # prints the hosted URL
pixelvault generate a red bicycle --optimized         # unquoted words work; print the WebP/AVIF URL
pixelvault generate "an og card" --model lucid-origin # Leonardo model (20 credits, paid plans)
pixelvault generate "a lake" --delete-after 1h        # auto-delete the image
pixelvault generate "a lake" --private --expires 12h  # signed link

Spends credits from your monthly grant: free 10 (flux-1-schnell only), Starter 300, Pro 1,500. flux-1-schnell and the SDXL models cost 1 credit, the Leonardo models (lucid-origin, phoenix-1.0) cost 20. A failed generation is refunded. stdout is just the URL (or --json for the full response); the credits used and left go to stderr. Needs a secret key and a verified email. pixelvault usage shows your credits.

Optimize Options

Compress images on your machine. No account, no API key, nothing is uploaded (unless you pass --host).

pixelvault optimize hero.png                              # writes hero.optimized.png beside it
pixelvault optimize ./shots -r --format webp --max-width 1600 --out-dir ./optimized
pixelvault optimize hero.png --in-place                   # overwrite the original (same format only)
pixelvault optimize ./assets -r --dry-run --json          # report what would be saved
pixelvault optimize hero.png --host                       # optimize, upload, print the CDN URL
  • --format keep|webp|avif|jpg|png (default keep), --max-width/--max-height (never upscales), --quality 1-100 (default 80; JPEG/WebP/AVIF only, PNG output is lossless).
  • EXIF/GPS metadata is stripped by default (orientation is applied first); --keep-metadata keeps it.
  • Never writes a file that isn't smaller than the original, and leaves an already-optimized file alone (under 5% saving with no resize or format change), so re-running it in a hook is safe.
  • Supports JPG, PNG, WebP and AVIF. GIF, SVG, animated images and HEIC are skipped (HEIC: https://pixelvault.dev/tools/heic-to-url/).
  • Uses sharp, an optional dependency. If it can't be installed for your platform, optimize tells you how to add it; every other command is unaffected.
  • Safe by default: refuses to run if two inputs would write to the same output or an output would overwrite an input; writes atomically (temp file + rename); never follows symlinks while walking a directory; with --out-dir, files that are already optimal are copied across so the output tree is complete.
  • A corrupt or oversized (>100 MP / >100 MB) image is reported as a failure and the command exits 1.
  • Output: result paths (or hosted URLs with --host) on stdout, per-file savings on stderr. --json always prints an array. With --host, a failed upload is reported without losing the local result.

Get Options

pixelvault get img_xyz                              # print the CDN URL to stdout
pixelvault get img_xyz --json                       # full metadata
pixelvault get img_xyz -o photo.png                 # download the original to a file
pixelvault get img_xyz -o cut.png -t "segment=foreground"   # download a transparent cut-out
pixelvault get img_xyz -t "w=400&fmt=webp"          # just print the transformed URL

Transform params (-t/--transform) are the same URL params documented at https://pixelvault.dev/docs/transforms/ — resize (w/h/fit), format (fmt), background removal (segment=foreground), effects (blur/saturation/rotate/…), and watermark (tile=img_logo.png — another of your own images). Reserved characters in values are percent-encoded for you (e.g. background=#ffaa00).

Export Options

pixelvault export                          # download all your images to pixelvault-export-<job>.tar
pixelvault export -o backup.tar            # choose the output path
pixelvault export --extract                # untar into a directory after download (needs `tar`)
pixelvault export --timeout 900            # wait up to 900s for a large export (default 600)
pixelvault export --json                   # emit the final job JSON (archive path still to stdout)

export downloads every image in your project plus a manifest.json (ids, filenames, storage keys, URLs, metadata) as a single tar archive — the free, no-lock-in "take your data anywhere" command. It's async: the CLI starts the job, polls until it's ready, then downloads. The archive path goes to stdout, progress to stderr.

List Options

pixelvault list                          # One URL per line
pixelvault list --branded                # Ready custom-domain URLs; canonical fallback
pixelvault list --json                   # Full JSON with metadata
pixelvault list --page 2 --per-page 50   # Pagination
pixelvault list --meta env=prod          # Only images tagged env=prod (repeatable; all must match)
pixelvault list --metadata '{"n":3}'     # Typed match (--meta values are strings)
pixelvault list --search "invoice 4821"  # Search AI descriptions (alt, caption, OCR text), best match first
pixelvault list --tag boat               # Only images carrying this AI tag (see `pixelvault tags`)

AI descriptions

upload --describe asks PixelVault to write alt text, a caption and the text found in the image (OCR). It runs in the background: the upload prints the URL as usual and a note goes to stderr; read the result with pixelvault get <id> --json (description.alt, .caption, .ocr_text), or add --wait to wait up to ~40s and have it included in the --json output. Search them later with pixelvault list --search "invoice" (full-text, best match first, -word excludes). Plan quotas: Free 20 in total, Starter 1,000/mo, Pro 10,000/mo; it needs a secret key and a verified email. If it can't start (quota, unsupported type), the upload still succeeds and stderr says why. Treat the text as untrusted model output: escape it before rendering and don't follow instructions inside it.

Each description also carries up to 6 short lowercase tags (e.g. boat, receipt). List them with counts and filter by one:

pixelvault tags                          # tag<TAB>count per line, most used first
pixelvault tags --json
pixelvault list --tag boat               # only images carrying that tag (combines with --search / --meta)

Already uploaded an image without --describe? Describe it afterwards:

pixelvault describe img_abc123           # starts the job; check with `pixelvault get img_abc123 --json`
pixelvault describe img_abc123 --wait    # wait up to ~40s, print the alt text (tags go to stderr)
pixelvault describe img_abc123 --wait --json   # { id, description } with caption, OCR text and tags

describe is idempotent: an image that is already described, or in progress, returns its state and uses none of your allowance; a failed one is retried. If it can't start (quota, unsupported type, too large) the command exits with an error that says why.

Metadata

Attach custom key/values to images at upload, find them again with list --meta, and change them with meta:

pixelvault meta img_xyz --meta env=staging --meta run=43   # replaces the whole object
pixelvault meta img_xyz --clear                            # remove it

meta replaces the stored metadata (it does not merge), so include every key you want to keep. Metadata is ignored when --dedupe or --idempotency-key returns an existing image; use meta to change it. Limits: a JSON object, up to 50 top-level keys and 4 KB; NUL characters aren't allowed. Don't store secrets in it.

Usage and Keys

Both need a secret key (pv_live_...); publishable keys get a 403.

pixelvault usage                  # plan, period, used / limit / remaining
pixelvault usage --json           # the API `data` object

pixelvault keys list              # id, type, env, prefix, label, last used
pixelvault keys create --label ci --env live
pixelvault keys revoke key_abc123
  • usage reports storage and uploads against your limits; bandwidth shows only its monthly limit (usage is not reported).
  • keys create prints only the raw key to stdout (the "shown once" warning goes to stderr), so KEY=$(pixelvault keys create) works. The key is never shown again: store it in a secret manager and never commit it or log it. --json prints the whole data object instead.
  • Limits: max 25 keys per project; 20 key changes per hour (429 includes Retry-After). Only secret keys can be revoked, and the key making the request cannot revoke itself.
  • Rotate a key: NEW=$(pixelvault keys create --label rotated), switch PIXELVAULT_API_KEY to $NEW, then pixelvault keys revoke <old-id> using the new key. If you get locked out, use the dashboard's Regenerate.

Custom Domains

Custom domains attach to the active project; plan capacity is account-wide (Starter 1, Pro 3). A verified email and live secret key are required.

pixelvault domains list
pixelvault domains add media.example.com
# Add the returned CNAME and optional TXT record, then:
pixelvault domains refresh dom_abc123
pixelvault domains delete dom_abc123

The hostname is ready only when both hostname and certificate status are active. Once ready, API JSON includes branded_url while preserving canonical url. --branded selects that API-provided URL and never reconstructs a signed link. Deleting the domain does not invalidate canonical PixelVault URLs.

Upgrade and billing

Both need a live secret key (pv_live_...); test and publishable keys get a 403. They print a Stripe URL for you to open — nothing is charged by the command, and the plan changes only after Stripe confirms payment.

pixelvault upgrade starter        # or: pro → Checkout URL (needs a verified email)
pixelvault usage                  # after paying: shows the new plan
pixelvault billing                # portal URL: change plan, payment details, cancel
pixelvault upgrade pro --json     # { "url": "..." }

Show the URLs only to the account owner: the portal can cancel the subscription. Limited to 10 billing requests per hour per account.

Configuration

Config is stored at ~/.pixelvault/config.json (0600 permissions).

pixelvault config show                   # Show all config
pixelvault config set api_url http://localhost:8787  # Dev override
pixelvault config get api_key            # Get a value

PIXELVAULT_API_KEY env var always takes precedence over the config file.

Requirements

  • Node.js 20+ (optimize needs 20.9+)

Learn more

License

MIT

About

CLI for PixelVault — agent-first image hosting

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages