pixelvault-cli

CLI for PixelVault — agent-first image 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 multiple images
pixelvault upload *.png --folder screenshots
# 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
# Export everything — all your images as a tar archive (no lock-in)
pixelvault export -o my-images.tar

Agent Integration

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

• upload prints only the URL to stdout
• list outputs one URL per line
• 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...>	Upload images (prints URLs to stdout)
list	List uploaded images
get <id>	Get an image's URL/metadata, or download it (optionally transformed)
delete <id>	Delete an image
export	Export all project images as a tar archive
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

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 --json # Full JSON with metadata
pixelvault list --page 2 --per-page 50 # Pagination

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+

Learn more

• PixelVault — agent-first image hosting
• API docs — full REST reference + OpenAPI 3.1
• Guide: Image hosting for AI agents
• The simplest image hosting API
• Agent skill — for Claude Code, Codex, and Cursor

License

MIT