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+

License

MIT