📁 Picsha Dropzone CLI

picsha-dropzone is an ultra-fast, concurrent CLI utility designed for photographers, developers, and AI researchers to upload, analyze, and catalog local media directories with Picsha AI.

It processes media files in parallel, triggers AI analysis pipelines (labels, descriptions, reverse-geocoding, and transcoding), generates a predictive Delivery CDN thumbnail set, and outputs local JSON sidecars along with a neat README.md catalog sheet.

🚀 Getting Started

Option A: Standalone Executable (Zero-Dependency)

Perfect for non-technical users and photographers. No Python or virtual environments required!

Download the pre-compiled picsha-dropzone binary for your platform.
Drag it into the folder containing your images.
Open a terminal and run it:
```
./picsha-dropzone . -k <your_api_key>
```

Option B: Python Package (Global / Developer)

If you prefer standard python package management:

# Install globally via pip
pip install picsha-dropzone

# Process a directory
picsha-dropzone /path/to/media -k <your_api_key>

⚙️ CLI Command Reference

usage: picsha-dropzone [-h] [-k API_KEY] [-u API_URL] [-w WORKERS] [-c CONFIG] [--content-moderation {true,false}] [-d] directory

Positional Arguments

directory: The path to the folder containing the images or documents you want to process. (Use . for the current active directory).

Optional Flags

-k, --api-key: Your Picsha API Key (e.g. sk_live_...). If not provided, the CLI will look for the PICSHA_API_KEY environment variable.
-u, --api-url: The Picsha API endpoint. Defaults to the production server https://api.picsha.ai.
-w, --workers: Number of concurrent uploads and workers. Defaults to 5 to guarantee high speed without overloading servers.
-c, --config: Customizes the ingestion pipeline. Accepts either a raw JSON string (e.g., '{"auto_summarize": false}') or a path to a .json file containing pipeline configurations.
--content-moderation: Explicitly enables or disables AWS Rekognition Content Moderation. Accepts true or false (defaults to false).
-d, --download-thumbnails: Tells the CLI to download small and medium thumbnails locally into a hidden .thumbnails/ folder and link them as relative paths in the JSON sidecar instead of using CDN URLs.

🛠️ Ingestion Configuration

The -c / --config parameter maps directly to Picsha's Ingestion Pipeline schema. You can toggle individual AI capabilities on or off to balance speed, cost, and metadata richness:

Key	Type	CLI Default*	Description
`auto_tag`	`boolean`	`true`	Runs AWS Rekognition for object, label, and face detection.
`auto_summarize`	`boolean`	`true`	Generates short descriptive AI captions/summaries (Anthropic Claude for images).
`vectorize`	`boolean`	`true`	Generates a Titan multimodal embedding vector for high-dimensional similarity search.
`location_lookup`	`boolean`	`true`	Reverse-geocodes EXIF GPS coordinates via Google Maps API.
`adaptive_stream`	`boolean`	`false`	Transcodes video uploads to adaptive HLS stream playlists using AWS MediaConvert.
`content_moderation`	`boolean`	`false`	Runs AWS Rekognition Content Moderation safety checks.
`render_on_upload`	`string`	`null`	Semicolon-separated delivery parameters to pre-warm the CDN cache (e.g. `"w=300; w=800"`).

*Note: These are CLI defaults, which differ from the standard API defaults of false.

Example JSON Config (`settings.json`):

{
  "auto_summarize": true,
  "auto_tag": false,
  "content_moderation": false,
  "location_lookup": true
}

💡 Practical Examples

1. Ultra-Fast Upload & Analyze (Default)

Standard run uploading files in parallel using the default API key:

export PICSHA_API_KEY="sk_live_..."
picsha-dropzone /Volumes/Photos/AdobeStock

2. Disabling Costly AI Features

Turn off summarization and Rekognition labels for a raw upload pipeline:

picsha-dropzone . -k sk_live_... -c '{"auto_summarize": false, "auto_tag": false}'

3. Local DAM Mode (Offline Thumbnails)

Downloads low-resolution thumbnails locally into the directory so other offline applications can display them immediately without network requests:

picsha-dropzone . -k sk_live_... --download-thumbnails

Creates a .thumbnails/ folder next to your photos, downloading <filename>_small.jpg (300px width) and <filename>_medium.jpg (800px width).