/generate-variant

name: cloudflare-images:generate-variant
description: Interactive variant generator for Cloudflare Images. Prompts for variant name, dimensions, fit mode, and quality, then generates API call to create the variant and optionally adds configuration to wrangler.jsonc.

Generate Cloudflare Images Variant

Interactive tool for creating named variants for Cloudflare Images. Walks through variant configuration and generates the API call to create it.

What This Command Does

When you run `/generate-variant`, Claude will: 1. Prompt for variant configuration (name, dimensions, fit, quality) 2. Validate variant name and options 3. Generate API call to create variant 4. Execute API call (if confirmed) 5. Output variant configuration 6. Optionally add variant to `wrangler.jsonc`

Usage

/generate-variant

Claude will ask interactive questions to gather variant configuration.

Variant Configuration Options

Variant Name

• **Format**: Alphanumeric + hyphens only
• **Max length**: 32 characters
• **Examples**: `thumbnail`, `avatar-lg`, `product-preview`
• **Reserved**: Cannot use `public` (default variant)

Dimensions

• **Width**: 1-9999 pixels (optional)
• **Height**: 1-9999 pixels (optional)
• **Note**: At least one dimension required

Fit Modes

• **scale-down** (default): Never enlarge, preserve aspect ratio
• **contain**: Resize to fit within box, preserve aspect ratio
• **cover**: Resize to cover entire box, crop if needed
• **crop**: Crop to exact dimensions
• **pad**: Resize to fit, pad with background color

Quality

• **Range**: 1-100
• **Default**: 85
• **Recommendations**:
• Thumbnails: 80
• Product photos: 85
• Hero images: 90

Optional Parameters

• **Background**: Color for padding (hex format: `#FFFFFF`)
• **Metadata**: `keep` | `copyright` | `none` (default: `none`)
• **Blur**: 1-250 pixels (for blur effect)

Implementation

Step 1: Interactive Configuration

Ask user for each parameter:

Variant Name (e.g., thumbnail, avatar-lg):
> thumbnail

Width (pixels, leave empty for auto):
> 300

Height (pixels, leave empty for auto):
> 300

Fit mode:
1. scale-down (never enlarge, default)
2. contain (fit within box)
3. cover (cover entire box, crop if needed)
4. crop (crop to exact dimensions)
5. pad (fit and pad with background)
> 3

Quality (1-100, default 85):
> 85

Background color for padding (optional, e.g., #FFFFFF):
> (skip)

Metadata (keep/copyright/none, default none):
> none

Blur radius (optional, 1-250):
> (skip)

Step 2: Validate Configuration

# Validate variant name
VARIANT_NAME="thumbnail"

if [[ ! "$VARIANT_NAME" =~ ^[a-z0-9-]+$ ]]; then
  echo "❌ Invalid variant name"
  echo "   Use only: a-z, 0-9, hyphens"
  exit 1
fi

if [ ${#VARIANT_NAME} -gt 32 ]; then
  echo "❌ Variant name too long (max 32 characters)"
  exit 1
fi

if [ "$VARIANT_NAME" = "public" ]; then
  echo "❌ Cannot use reserved name 'public'"
  exit 1
fi

echo "✅ Variant name valid: $VARIANT_NAME"

# Validate dimensions
WIDTH=300
HEIGHT=300

if [ -z "$WIDTH" ] && [ -z "$HEIGHT" ]; then
  echo "❌ At least one dimension (width or height) required"
  exit 1
fi

if [ ! -z "$WIDTH" ] && ([ "$WIDTH" -lt 1 ] || [ "$WIDTH" -gt 9999 ]); then
  echo "❌ Width must be between 1 and 9999"
  exit 1
fi

if [ ! -z "$HEIGHT" ] && ([ "$HEIGHT" -lt 1 ] || [ "$HEIGHT" -gt 9999 ]); then
  echo "❌ Height must be between 1 and 9999"
  exit 1
fi

echo "✅ Dimensions valid: ${WIDTH}x${HEIGHT}"

# Validate fit mode
FIT="cover"
VALID_FITS=("scale-down" "contain" "cover" "crop" "pad")

if [[ ! " ${VALID_FITS[@]} " =~ " ${FIT} " ]]; then
  echo "❌ Invalid fit mode: $FIT"
  echo "   Valid: scale-down, contain, cover, crop, pad"
  exit 1
fi

echo "✅ Fit mode valid: $FIT"

# Validate quality
QUALITY=85

if [ ! -z "$QUALITY" ] && ([ "$QUALITY" -lt 1 ] || [ "$QUALITY" -gt 100 ]); then
  echo "❌ Quality must be between 1 and 100"
  exit 1
fi

echo "✅ Quality valid: $QUALITY"

Step 3: Build Variant Configuration

echo ""
echo "📐 Variant Configuration:"
echo "  Name: $VARIANT_NAME"
echo "  Dimensions: ${WIDTH}x${HEIGHT}"
echo "  Fit: $FIT"
echo "  Quality: $QUALITY"

if [ ! -z "$BACKGROUND" ]; then
  echo "  Background: $BACKGROUND"
fi

if [ ! -z "$METADATA" ] && [ "$METADATA" != "none" ]; then
  echo "  Metadata: $METADATA"
fi

if [ ! -z "$BLUR" ]; then
  echo "  Blur: ${BLUR}px"
fi

echo ""

Step 4: Generate API Call

# Build JSON payload
PAYLOAD=$(cat <<EOF
{
  "id": "$VARIANT_NAME",
  "options": {
    "width": ${WIDTH},
    "height": ${HEIGHT},
    "fit": "$FIT",
    "metadata": "${METADATA:-none}"
  },
  "neverRequireSignedURLs": true
}
EOF
)

# Add optional parameters
if [ ! -z "$BACKGROUND" ]; then
  PAYLOAD=$(echo "$PAYLOAD" | jq ".options.background = \"$BACKGROUND\"")
fi

if [ ! -z "$BLUR" ]; then
  PAYLOAD=$(echo "$PAYLOAD" | jq ".options.blur = $BLUR")
fi

if [ ! -z "$QUALITY" ]; then
  PAYLOAD=$(echo "$PAYLOAD" | jq ".options.quality = $QUALITY")
fi

echo "🔧 Generated API Payload:"
echo "$PAYLOAD" | jq .
echo ""

Step 5: Execute API Call

echo "📤 Creating variant via API..."

# Check environment variables
if [ -z "$CF_ACCOUNT_ID" ] || [ -z "$CF_API_TOKEN" ]; then
  echo "❌ Missing environment variables"
  echo "   Required: CF_ACCOUNT_ID, CF_API_TOKEN"
  echo ""
  echo "   Set in .env:"
  echo "   CF_ACCOUNT_ID=your_account_id"
  echo "   CF_API_TOKEN=your_api_token"
  exit 1
fi

# Create variant
RESPONSE=$(curl -s -X POST \
  "https://api.cloudflare.com/client/v4/accounts/${CF_ACCOUNT_ID}/images/v1/variants" \
  -H "Authorization: Bearer ${CF_API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d "$PAYLOAD")

SUCCESS=$(echo "$RESPONSE" | jq -r '.success')

if [ "$SUCCESS" = "true" ]; then
  echo "✅ Variant created successfully!"
  echo ""
  echo "Variant details:"
  echo "$RESPONSE" | jq -r '.result | "  ID: \(.id)\n  Never require signed URLs: \(.neverRequireSignedURLs)"'
  echo ""
  echo "Options:"
  ech