Giil
Zero-setup bash CLI that downloads full-resolution images from iCloud/Dropbox/Google Photos share links, bridging iPhone screenshots to remote AI coding sessions
Install / Use
/learn @Dicklesworthstone/GiilREADME
<p align="center">
curl -fsSL "https://raw.githubusercontent.com/Dicklesworthstone/giil/main/install.sh?v=3.0.0" | bash
🎯 The Primary Use Case: Remote AI-Assisted Debugging
The scenario: You're SSH'd into a remote server running Claude Code, Codex, or another AI coding assistant. You need to debug a UI issue on your iPhone, but how do you get that screenshot to your remote terminal session?
┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ iPhone │────▶│ iCloud │────▶│ Photos.app │────▶│ Share Link │
│ Screenshot │ │ Sync │ │ (Mac) │ │ (Copy) │
└─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘
│
▼
┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ AI Agent │◀────│ giil │◀────│ Paste │◀────│ Remote SSH │
│ Analyzes │ │ Downloads │ │ URL │ │ Terminal │
└─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘
The workflow:
- Screenshot the UI bug on your iPhone
- Wait a moment for iCloud to sync to your Mac
- Right-click the image in Photos.app → Share → Copy iCloud Link
- Paste the link into your remote terminal session
- Run giil and the image is now local to your remote machine
# On your remote server (SSH session with Claude Code/Codex)
giil "https://share.icloud.com/photos/0a1Abc_xYz..." --format json
# AI assistant can now analyze the screenshot directly
# {"path": "/tmp/icloud_20240115_143022.jpg", "width": 1170, "height": 2532, ...}
Comparison:
| Without giil | With giil | |--------------|-----------| | Download image locally, SCP to server, tell AI the path | One command, AI sees it instantly | | Email yourself, download on server, hope it works | Paste link, done | | Set up complex file sync between devices | Just use iCloud's built-in sharing | | Break your flow to context-switch between devices | Stay in your terminal |
This bridges your Apple devices and remote AI coding sessions. No file transfers, no context switching, no friction.
Table of Contents
- The Primary Use Case
- Why giil Exists
- Highlights
- Quickstart
- Usage
- Output Modes
- Album Mode
- How It Works
- Browser Emulation
- Capture Strategies in Detail
- Platform-Specific Optimizations
- Image Processing Pipeline
- Download Verification
- Design Principles
- Architecture
- Testing & Quality Assurance
- File Locations
- Performance
- Troubleshooting
- Exit Codes
- Terminal Styling
- Environment Variables
- Dependencies
- Security & Privacy
- Uninstallation
- Contributing
- License
💡 Why giil Exists
Cloud photo sharing services present unique challenges for automation:
| Problem | Why It's Hard | How giil Solves It |
|---------|---------------|-------------------|
| JavaScript-heavy SPAs | Standard curl/wget can't execute JS or render pages | Headless Chromium via Playwright (or direct download for Dropbox) |
| Dynamic image loading | Images load asynchronously from CDN after page render | Network interception captures CDN responses |
| No direct download links | URLs are session-specific and expire quickly | Clicks native Download button or intercepts live requests |
| Copy/paste loses quality | Manual screenshots result in compressed/cropped images | Captures original resolution from source |
| HEIC format on Apple devices | Many tools can't process Apple's HEIC/HEIF format | Platform-aware conversion (sips/heif-convert) |
| Platform fragmentation | Each service has different URL patterns and APIs | Automatic platform detection with optimized strategies |
giil lets you programmatically download full-resolution images from iCloud, Dropbox, Google Photos, and Google Drive share links—which is otherwise impossible without manual browser interaction.
Typical workflow: Debugging a UI issue with Claude Code or Codex on a remote server? Screenshot on iPhone → iCloud syncs → Share link from Photos.app → Paste into SSH terminal → giil fetches it → AI analyzes the image. No SCP, no email, no friction.
✨ Highlights
<table> <tr> <td width="50%">Zero-Setup Installation
One-liner installer handles everything:
- Node.js detection/installation
- Playwright + Chromium (~200MB, cached)
- Sharp image processing library
- Optional gum for beautiful CLI output
Four-Tier Capture Strategy
Maximum reliability through intelligent fallbacks:
- Download button → Original file
- CDN interception → Full resolution
- Element screenshot → Rendered image
- Viewport screenshot → Last resort
Album Support
Download entire shared albums with --all:
- Automatic thumbnail detection
- Sequential full-resolution capture
- Collision-free filenames with indices
- Continues on individual failures
Flexible Output
Multiple output modes for any workflow:
- File path → Default, for scripting
- JSON metadata → Path, datetime, dimensions
- Base64 → Embedding, piping, APIs
- Album mode → One output per photo
Smart Filenames
EXIF-aware datetime stamping:
- Extracts
DateTimeOriginalfrom EXIF - Falls back to capture timestamp
- Format:
icloud_YYYYMMDD_HHMMSS.jpg - Automatic collision avoidance
Image Processing
MozJPEG compression by default:
- Optimal size/quality balance
--preserveto keep original bytes--convertfor format conversion- HEIC auto-conversion supported
⚡ Quickstart
Installation
One-liner (recommended):
curl -fsSL "https://raw.githubusercontent.com/Dicklesworthstone/giil/main/install.sh?v=3.0.0" | bash
# Download script
curl -fsSL https://raw.githubusercontent.com/Dicklesworthstone/giil/main/giil -o ~/.local/bin/giil
chmod +x ~/.local/bin/giil
# Ensure ~/.local/bin is in PATH
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc # or ~/.bashrc
source ~/.zshrc
# Custom install directory
DEST=/opt/bin curl -fsSL .../install.sh | bash
# System-wide installation (requires sudo)
GIIL_SYSTEM=1 curl -fsSL .../install.sh | bash
# Skip PATH modification
GIIL_NO_ALIAS=1 curl -fsSL .../install.sh | bash
# Verified installation with SHA256 checksum
GIIL_VERIFY=1 curl -fsSL .../install.sh | bash
# Install specific version
GIIL_VERSION=2.1.0 curl -fsSL .../install.sh | bash
For security-conscious installations, giil supports SHA256 checksum verification:
GIIL_VERIFY=1 curl -fsSL https://raw.githubusercontent.com/Dicklesworthstone/giil/main/install.sh | bash
How it works:
- Downloads
giilscript from the release - Fetches
giil.sha256checksum file from the same release - Computes SHA256 of downloaded file
- Compares against expected checksum
- Aborts installation if mismatch detected
Requirements:
- Either
sha256sum(Linux) orshasum(macOS) - GitHub release must include
giil.sha256file
Output on success:
✓ Checksum verified: a1b2c3d4e5f6...
First Run
giil "https://share.icloud.com/photos/02cD9okNHvVd-uuDnPCH3ZEEA"
Note: First run downloads Playwright Chromium (~200MB). This is cached for future runs in
~/.cache/giil/.
🚀 Usage
giil <icloud-photo-url> [options]
Options
| Flag | Default | Description |
|------|---------|-------------|
| --output DIR | . | Output directory for saved images |
| --preserve | off | Preserve original bytes (skip MozJPEG compression) |
| --convert FMT | — | Convert to format: jpeg, png, webp |
| --quality N | 85 | JPEG quality 1-100 |
| --format FMT | — | S
