Download Gravatar Images

Download Gravatar avatar images to local files.

Usage

npx tsx scripts/download.ts <email> <output-file> [options]

Arguments

| Argument | Required | Description | |----------|----------|-------------| | email | Yes | Email address | | output-file | Yes | Path where image will be saved |

Options

| Option | Description | |--------|-------------| | --size=N | Image size in pixels (default: 200, max: 2048) | | --default=TYPE | Default image type: mp, identicon, monsterid, wavatar, retro, robohash, blank | | --rating=LEVEL | Rating level: g, pg, r, x (default: g) | | --no-cache | Bypass cache and fetch fresh data |

Output

Email: user@example.com
Output: avatar.jpg
Hash: b48bf4373d7b7374351c0544f36f7fc3

✓ Downloaded successfully
  Size: 12.4 KB
  File: avatar.jpg

Script Execution (Preferred)

npx tsx scripts/download.ts <email> <output-file> [options]

Options:

--size=N - Image size in pixels (default: 200, max: 2048)
--default=TYPE - Default image type: mp, identicon, monsterid, wavatar, retro, robohash, blank
--rating=LEVEL - Rating level: g, pg, r, x (default: g)
--no-cache - Bypass cache and fetch fresh data

Run from the gravatar plugin directory: ~/.claude/plugins/cache/gravatar/

How It Works

Generates Gravatar URL with specified parameters
Downloads image using cached HTTP request
Saves image to specified file path
Caches downloaded images for 24 hours

Examples

Basic download (200px PNG):

npx tsx scripts/download.ts user@example.com avatar.png

Large avatar (800px):

npx tsx scripts/download.ts user@example.com large-avatar.jpg --size=800

Download with fallback to identicon:

npx tsx scripts/download.ts newuser@example.com avatar.png --default=identicon

Force fresh download:

npx tsx scripts/download.ts user@example.com avatar.png --no-cache

Image Size Options

| Size | Use Case | File Size (approx) | |------|----------|-------------------| | 80 | Small thumbnails | 2-4 KB | | 200 | Profile avatars (default) | 8-15 KB | | 400 | Large profile images | 20-35 KB | | 800 | High-resolution displays | 50-90 KB | | 2048 | Maximum quality | 200-400 KB |

Default Image Types

When no Gravatar exists, these defaults are used:

| Type | Description | |------|-------------| | mp | Mystery Person (simple silhouette) | | identicon | Geometric pattern based on email hash | | monsterid | Unique monster generated from email | | wavatar | Unique face generated from email | | retro | 8-bit arcade-style face | | robohash | Unique robot generated from email | | blank | Transparent PNG |

Use Cases

Team Avatar Cache

Download avatars for all team members:

for email in dev1@company.com dev2@company.com dev3@company.com; do
  npx tsx scripts/download.ts "$email" "avatars/${email}.png" --size=400
done

Profile Image Backup

Save user avatars locally:

npx tsx scripts/download.ts maintainer@project.org backup/maintainer.jpg --size=800

Generate Placeholder Avatars

Create consistent default avatars:

npx tsx scripts/download.ts user1@example.com user1.png --default=identicon
npx tsx scripts/download.ts user2@example.com user2.png --default=identicon

High-Resolution Display

Download retina-ready images:

npx tsx scripts/download.ts user@example.com avatar@2x.png --size=400

Caching

Downloaded images are cached for 24 hours:

Same email + parameters = cached file returned
Different parameters = new download
--no-cache = fresh download

This reduces API calls and bandwidth usage.

Error Handling

The script will fail if:

Email is missing or invalid format
Output file path is missing
Network errors occur
Disk write fails

Error messages indicate the specific failure for troubleshooting.

File Formats

Gravatar serves images in these formats:

JPG - Smaller file size, good for photos
PNG - Better for geometric/generated images (identicon, robohash)
WebP - Modern format, smallest size (when supported)

The file extension in the output path determines the format saved.

Use gravatar-check skill to verify Gravatar exists before downloading
Use gravatar-url skill to generate URLs for web display
Combine with npm/GitHub user data to download contributor avatars

gravatar-download