cloudinary/cli repository overview

⁠Cloudinary CLI

A powerful command-line interface for Cloudinary that enables you to interact with Cloudinary through the command line. Perform Admin and Upload API operations, try out transformations and optimizations, and automate media management tasks without setting up a formal coding environment.

⁠Characteristics

⁠Available Commands

This CLI provides comprehensive access to Cloudinary's functionality:

• Upload API - Upload images, videos, and raw files with transformations
• Admin API - Manage assets, transformations, and account settings
• Search API - Search and filter assets using Lucene query syntax
• URL Generation - Generate optimized delivery URLs with transformations
• Folder Operations - Upload entire directories and sync local/remote folders
• Asset Migration - Migrate assets from external sources to Cloudinary
• Transformation Management - Create, test, and manage image/video transformations

⁠Quick Start

⁠Basic Usage

# Check version
docker run --rm cloudinary/cli --version

# Check configuration
docker run --rm -e CLOUDINARY_URL cloudinary/cli config

# Upload an image
docker run --rm -e CLOUDINARY_URL \
  -v ./images:/app/images \
  cloudinary/cli uploader upload /app/images/sample.jpg

# Generate a transformation URL
docker run --rm -e CLOUDINARY_URL \
  cloudinary/cli url sample w_500,h_300,c_fill

# Search for assets
docker run --rm -e CLOUDINARY_URL \
  cloudinary/cli search "resource_type:image"

⁠Environment Variables

Set your Cloudinary credentials using environment variables:

export CLOUDINARY_URL="cloudinary://api_key:api_secret@cloud_name"

Or use individual variables:

export CLOUDINARY_CLOUD_NAME="your_cloud_name"
export CLOUDINARY_API_KEY="your_api_key"
export CLOUDINARY_API_SECRET="your_api_secret"

⁠Working with Files

Upload local files by mounting volumes:

# Upload a directory
docker run --rm -e CLOUDINARY_URL \
  -v /path/to/local/folder:/app/upload \
  cloudinary/cli upload_dir /app/upload -f remote_folder

# Sync directories
docker run --rm -e CLOUDINARY_URL \
  -v /path/to/local/folder:/app/sync \
  cloudinary/cli sync --push /app/sync remote_folder

⁠Interactive Mode

Run in interactive mode for multiple commands:

docker run --rm -it -e CLOUDINARY_URL --entrypoint /bin/bash cloudinary/cli

Then within the container:

cld config
cld search "resource_type:image" --max_results 5
cld url sample w_500,h_300,c_fill

⁠Common Use Cases

• Bulk Upload: Upload entire directories while maintaining folder structure
• Asset Management: Organize, tag, and manage large media libraries
• Transformation Testing: Quickly test and iterate on image/video transformations
• Automation: Integrate with CI/CD pipelines for automated media processing
• Migration: Move assets from other platforms to Cloudinary
• Analytics: Monitor usage and performance metrics

⁠Platform Support

This Docker image supports multiple architectures:

• linux/amd64 (Intel/AMD 64-bit)
• linux/arm64 (ARM 64-bit, including Apple Silicon)

⁠Requirements

• Docker installed on your system
• Valid Cloudinary account credentials
• Network access to Cloudinary API endpoints

⁠Security & Best Practices

• Non-root execution: Runs as non-root user (UID 1000)
• Debian-based: Built on stable Debian 12 "Bookworm" for security and compatibility
• No credentials stored: No sensitive data baked into the image
• Environment variables: Secure credential management via environment variables
• Health checks: Built-in health monitoring for container orchestration
• Multi-arch support: Optimized builds for both Intel/AMD and ARM architectures
• Industry standard: Uses recommended python:slim-bookworm base image

For detailed documentation, advanced usage examples, and troubleshooting, visit the GitHub repository⁠ or the official documentation⁠.