stow-cli

CLI for Stow file storage. Upload, search, and manage files from the terminal.

Installation

npm install -g stow-cli

Quick Start

# Set your API key
export STOW_API_KEY="stow_..."

# Check connection
stow whoami

# Upload a file
stow upload ./photo.jpg --bucket photos

# Quick share (returns a short URL)
stow drop ./screenshot.png

# Search
stow search text 'sunset beach' -b photos

Authentication

Stow CLI uses environment variables for authentication:

| Variable | Required | Description | | ------------------- | -------- | --------------------------------------------------------------- | | STOW_API_KEY | Yes | Your Stow API key (get one at app.stow.sh/dashboard/api-keys) | | STOW_API_URL | No | Override the default API URL (https://api.stow.sh) | | STOW_ADMIN_SECRET | No | Required for admin commands only |

Commands

Upload and Share

stow upload <file> -- Upload a file to a bucket.

stow upload ./logo.png --bucket brand-assets
stow upload ./clip.mov --quiet

Options: -b, --bucket <name>, -q, --quiet

stow drop <file> -- Upload a file and get a short URL (quick share).

stow drop ./video.mp4
stow drop ./notes.txt --quiet

Options: -q, --quiet

Buckets

stow buckets -- List your buckets.

stow buckets create <name> -- Create a new bucket.

stow buckets create photos
stow buckets create docs --description "Product docs"
stow buckets create public-media --public

Options: -d, --description <text>, --public

stow buckets rename <name> <new-name> -- Rename a bucket. Note: renaming can break existing public URLs.

stow buckets rename old-name new-name --yes

Options: -y, --yes (skip confirmation)

stow buckets delete <id> -- Delete a bucket by ID.

stow buckets delete 8f3d1ab4-...

Files

stow files <bucket> -- List files in a bucket.

stow files photos
stow files photos --search avatars/ --limit 100
stow files photos --json

Options: -s, --search <prefix>, -l, --limit <count>, --json

stow files get <bucket> <key> -- Get details for a single file.

stow files get photos hero.png
stow files get photos hero.png --json

Options: --json

stow files update <bucket> <key> -- Update file metadata.

stow files update photos hero.png -m alt='Hero image'
stow files update photos hero.png -m category=banner -m priority=high

Options: -m, --metadata <kv...>, --json

stow files enrich <bucket> <key> -- Generate title, description, and alt text for an image. Requires a searchable bucket with image files.

stow files enrich photos hero.jpg

stow files missing <bucket> <type> -- List files missing processing data. Valid types: dimensions, embeddings, colors.

stow files missing brera dimensions
stow files missing brera embeddings --limit 200
stow files missing brera colors --json

Options: -l, --limit <count>, --json

Search

stow search text <query> -- Semantic text search.

stow search text 'sunset beach' -b photos --limit 10 --json

stow search similar --file <key> -- Find files similar to a given file.

stow search similar --file hero.png -b photos

stow search color --hex <color> -- Search by color.

stow search color --hex "#ff0000" -b photos --limit 20

stow search diverse -- Diversity-aware search.

stow search diverse -b photos --limit 20

All search commands accept: -b, --bucket <name>, -l, --limit <count>, --json

Tags

stow tags -- List tags.

stow tags create <name> -- Create a new tag.

stow tags create "Hero Images"
stow tags create "Featured" --color "#ff6600"

Options: --color <hex>, --json

stow tags delete <id> -- Delete a tag by ID.

Drops

stow drops -- List your drops with usage info.

stow drops delete <id> -- Delete a drop by ID.

stow drops delete drop_abc123

Profiles

stow profiles create -- Create a taste profile.

stow profiles create --name "My Profile" -b photos

Options: --name <name> (required), -b, --bucket <id>, --json

stow profiles get <id> -- Get a taste profile with clusters.

stow profiles get profile_abc123 --json

Options: --json

stow profiles delete <id> -- Delete a taste profile.

Jobs

stow jobs -- List processing jobs for a bucket.

stow jobs --bucket <id>
stow jobs --bucket <id> --status failed
stow jobs --bucket <id> --queue extract-colors --json

Options: -b, --bucket <id> (required), -s, --status <status>, -q, --queue <name>, -l, --limit <count>, --json

stow jobs retry <id> -- Retry a failed job.

stow jobs retry job123 --queue generate-title --bucket <id>

Options: -q, --queue <name> (required), -b, --bucket <id> (required)

stow jobs delete <id> -- Remove a job.

stow jobs delete job123 --queue extract-colors --bucket <id>

Options: -q, --queue <name> (required), -b, --bucket <id> (required)

Admin

All admin commands require the STOW_ADMIN_SECRET environment variable.

stow admin health -- Check system health and queue depths.

stow admin health
stow admin health --json

stow admin backfill <type> -- Backfill processing data. Valid types: dimensions, colors, embeddings.

stow admin backfill dimensions --bucket <id> --dry-run
stow admin backfill colors --bucket <id> --limit 200
stow admin backfill embeddings --bucket <id> --limit 100 --json

Options: --bucket <id>, -l, --limit <count>, --dry-run, --json

stow admin cleanup-drops -- Remove expired drops.

stow admin cleanup-drops --max-age-hours 24 --dry-run

Options: --max-age-hours <hours>, --dry-run, --json

stow admin purge-events -- Purge old webhook events.

stow admin purge-events --dry-run

Options: --dry-run, --json

stow admin reconcile-files -- Reconcile files between R2 and database.

stow admin reconcile-files --bucket <id> --dry-run

Options: --bucket <id> (required), --dry-run, --json

stow admin retry-sync-failures -- Retry failed S3 sync operations.

stow admin retry-sync-failures

Options: --json

stow admin jobs -- List and manage processing jobs (cross-org).

stow admin jobs
stow admin jobs --status failed
stow admin jobs --org <id> --queue generate-title

Options: --org <id>, --bucket <id>, -s, --status, -q, --queue, -l, --limit, --json

stow admin jobs retry <id> / stow admin jobs delete <id> -- Retry or remove a job.

stow admin jobs retry job123 --queue generate-title
stow admin jobs delete job123 --queue extract-colors

stow admin queues -- Show queue depths and counts.

stow admin queues
stow admin queues --json

stow admin queues clean <name> -- Clean jobs from a queue.

stow admin queues clean generate-title --failed
stow admin queues clean extract-colors --completed --grace 3600

Options: --failed, --completed, --grace <seconds>

Utility

stow whoami -- Show account info, usage stats, and API key details.

stow open <bucket> -- Open a bucket in the browser.

stow delete <bucket> <key> -- Delete a file from a bucket.

stow delete photos hero/banner.png

Interactive Mode

Run stow with no arguments or stow -i to launch the interactive TUI. Browse buckets, files, and perform actions with a keyboard-driven interface.

stow
stow --interactive

JSON Output

Most commands support --json for machine-readable output. Useful for scripting and piping into tools like jq:

stow files photos --json | jq '.[].key'
stow search text 'landscape' -b photos --json | jq length

Environment Variables

| Variable | Default | Description | | ------------------- | --------------------- | -------------------------- | | STOW_API_KEY | -- | API key for authentication | | STOW_API_URL | https://api.stow.sh | API base URL | | STOW_ADMIN_SECRET | -- | Secret for admin commands |

License

MIT