giil

GIIL — Get Image [from] Internet Link

クラウド写真共有からフル解像度の画像をダウンロードする、セットアップ不要の CLI です。iPhone のスクリーンショットとリモート AI コーディングセッションをつなぐ欠けていたリンクです。

開発の背景

主な用途：リモートでの AI 支援デバッグ

Claude Code、Codex、または別の AI アシスタントを実行しているリモートサーバーに SSH で接続しています。iPhone の UI の問題をデバッグする必要がありますが、そのスクリーンショットをリモートターミナルに送るにはどうすればよいでしょうか？

giil を使わない場合：

Download image locally → SCP to server → Tell AI the path
Email yourself → Download on server → Hope it works
Set up complex file sync between devices

giil を使う場合：

giil "https://share.icloud.com/photos/0a1Abc_xYz..." --json
# {"path": "/tmp/icloud_20240115_143022.jpg", "width": 1170, ...}

コマンドは 1 つだけです。AI がすぐに画像を確認できます。ファイル転送も、コンテキストの切り替えも必要ありません。

ワークフロー

iPhone Screenshot → iCloud Sync → Photos.app Share Link → Paste to SSH → giil Downloads → AI Analyzes

クラウド共有が難しい理由

問題	難しい理由	giil による解決方法
JavaScript を多用する SPA	標準の curl/wget では JavaScript を実行できません	Playwright 経由のヘッドレス Chromium
動的な画像読み込み	画像は CDN から非同期に読み込まれます	ネットワークインターセプトで CDN の応答を取得します
直接ダウンロードできるリンクがない	URL はセッションごとに異なり、有効期限があります	ダウンロードボタンをクリックするか、実行中のリクエストをインターセプトします
コピー＆ペーストで画質が落ちる	手動のスクリーンショットでは画像が圧縮されます	ソースから元の解像度で取得します
Apple の HEIC 形式	多くのツールは HEIC/HEIF を処理できません	プラットフォームに対応した変換（sips/heif-convert）

クイックスタート

# Install
curl -fsSL "https://raw.githubusercontent.com/Dicklesworthstone/giil/main/install.sh?v=3.0.0" | bash

# Download single image
giil "https://share.icloud.com/photos/02cD9okNHvVd-uuDnPCH3ZEEA"

# JSON output (best for AI workflows)
giil "https://share.icloud.com/photos/..." --json

# Download entire album
giil "https://share.icloud.com/photos/..." --all --output ~/album

注： 初回の実行時に Playwright Chromium（約 200MB）がダウンロードされ、~/.cache/giil/ にキャッシュされます。

対応プラットフォーム

プラットフォーム	URL パターン	方法	ブラウザーが必要
iCloud	share.icloud.com/photos/*、icloud.com/photos/#*	4 段階の取得戦略	はい
Dropbox	dropbox.com/s/*、dropbox.com/scl/fi/*	curl による直接取得（raw=1）	いいえ
Google Photos	photos.app.goo.gl/*、photos.google.com/share/*	URL 抽出 + =s0 修飾子	はい
Google Drive	drive.google.com/file/d/*、drive.google.com/open?id=*	認証検出を含む複数段階の方法	はい

Dropbox の高速経路： ブラウザー処理を介さず、curl で直接ダウンロードします。通常は 1〜2 秒で完了します。

Google Photos のフル解像度取得： CDN の URL に =s0 を自動的に追加し、最大解像度で取得します。

4 段階の取得戦略

giil は信頼性を最大限に高めるため、フォールバック戦略を実装しています。

1. ダウンロードボタン（最高品質）

• 9 種類のセレクターパターンを使って、表示されているダウンロードボタンを検出します
• クリックして、ブラウザーのダウンロードイベントを待ちます
• 元のファイルを取得します（再エンコードによる画質の劣化はありません）
• HEIC/HEIF のオリジナル画像にも対応します

2. ネットワークインターセプト（フル解像度）

• すべての HTTP 応答を監視し、CDN パターン（cvws.icloud-content.com など）を探します
• content-type でフィルタリングします（画像形式のみ）
• 最大の画像バッファーを取得します（サムネイルを除外するため、しきい値は 10KB 超）
• UI 要素が隠れている場合でも機能します

3. 要素のスクリーンショット

• 10 種類のセレクターパターンを使って、画像要素を検索します
• 要素が表示されていて、サイズが 100×100 ピクセル以上であることを確認します
• 要素の PNG スクリーンショットを撮影します

4. ビューポートのスクリーンショット（最後の手段）

• 表示されているビューポート（1920×1080）を取得します
• ページが読み込まれれば必ず成功します
• ページの状態をデバッグするのに便利です

コマンドリファレンス

基本的な使い方

giil <url> [options]

オプション

フラグ	デフォルト	説明
--output DIR	.	出力ディレクトリ
--preserve	off	元のバイト列を保持します（MozJPEG 圧縮をスキップします）
--convert FMT	—	変換先：jpeg、png、webp
--quality N	85	JPEG の品質（1～100）
--base64	off	base64 を標準出力に出力します（ファイルは保存しません）
--json	off	JSON メタデータを出力します
--all	off	アルバム内のすべての写真をダウンロードします
--timeout N	60	ページ読み込みのタイムアウト時間（秒）
--debug	off	失敗時にデバッグ用ファイルを保存します
--verbose	off	詳細な進行状況を表示します
--trace	off	詳細なデバッグ用に Playwright のトレースを有効にします
--print-url	off	解決された CDN URL を出力します（ダウンロードしません）
--debug-dir DIR	.	デバッグ用ファイルのディレクトリ
--update	off	依存関係を強制的に再インストールします

出力モード

デフォルト：ファイルパス

giil "https://share.icloud.com/photos/XXX"
# stdout: /current/dir/icloud_20240115_143245.jpg

スクリプトでの使用：

IMAGE_PATH=$(giil "..." --output ~/Downloads 2>/dev/null)

JSON モード

giil "https://share.icloud.com/photos/XXX" --json

成功：

{
  "ok": true,
  "schema_version": "1",
  "platform": "icloud",
  "path": "/absolute/path/to/icloud_20240115_143245.jpg",
  "datetime": "2024-01-15T14:32:45.000Z",
  "sourceUrl": "https://cvws.icloud-content.com/...",
  "method": "network",
  "size": 245678,
  "width": 4032,
  "height": 3024
}

エラー：

{
  "ok": false,
  "schema_version": "1",
  "platform": "icloud",
  "error": {
    "code": "AUTH_REQUIRED",
    "message": "Login required - link is not publicly shared",
    "remediation": "The file is not publicly shared. The owner must enable public access."
  }
}

フィールド	説明
method	キャプチャ方法：download、network、element-screenshot、viewport-screenshot、direct
error.code	エラーコード（終了コードを参照）
error.remediation	推奨される修正方法

Base64 モード

# Decode to file
giil "..." --base64 | base64 -d > image.jpg

# Create data URI
echo "data:image/jpeg;base64,$(giil '...' --base64)" > uri.txt

# Pipe to API
giil "..." --base64 | curl -X POST -d @- https://api.example.com/upload

URL のみのモード

giil "https://share.icloud.com/photos/XXX" --print-url
# stdout: https://cvws.icloud-content.com/B/...

外部ダウンローダー、キャッシュ、デバッグに便利です。

アルバムモード

--all を指定すると、共有アルバム全体をダウンロードします：

giil "https://share.icloud.com/photos/XXX" --all --output ~/album

動作の仕組み

1. アルバムページを読み込みます
2. サムネイルのグリッドを検出します（11 種類のセレクター戦略）
3. 各サムネイルについて、クリック → キャプチャ → 閉じる → 次へ進みます
4. 写真ごとにパスまたは JSON を出力します

アルバムの機能

• 堅牢性： 写真の取得に失敗しても、次の写真の処理を続けます
• 連番ファイル名： 並び順を示す _001、_002 などを付けます
• レート制限： 写真の間に 1 秒の待機時間を設けます（配慮のあるダウンロード）
• 指数バックオフ： レート制限の兆候がある場合に自動で再試行します

アルバムの出力

# Default
/path/to/album/icloud_20240115_143245_001.jpg
/path/to/album/icloud_20240115_143246_002.jpg

# With --json
{"path": "...001.jpg", "method": "download", "width": 4032, ...}
{"path": "...002.jpg", "method": "network", "width": 3024, ...}

画像処理パイプライン

EXIF の日時抽出

ファイル名の生成に使用する優先順位：

1. DateTimeOriginal（写真の撮影日時）
2. CreateDate
3. DateTimeDigitized
4. ModifyDate
5. 現在の時刻（フォールバック）

HEIC/HEIF の変換

プラットフォーム	ツール	備考
macOS	sips	標準搭載されており、常に利用できます
Linux	heif-convert	libheif-examples パッケージが必要です

# Install HEIC support on Linux
sudo apt-get install libheif-examples  # Debian/Ubuntu
sudo dnf install libheif-tools         # Fedora

MozJPEG 圧縮（デフォルト）

デフォルトでは、giil は最適なサイズと品質を実現するために MozJPEG で圧縮します：

• 同等の品質の標準 JPEG より 40～50% 小さくなります
• 品質 85（--quality で設定できます）
• 元のバイト列を保持するには --preserve を使用します

ファイル名の形式

icloud_YYYYMMDD_HHMMSS[_NNN][_counter].jpg
        │              │      │
        │              │      └── Collision counter (if file exists)
        │              └── Album index (--all mode only)
        └── Date/time from EXIF or capture time

ダウンロードの検証

giil は、次の 3 段階でダウンロードを検証します：

1. Content-Type の検証

HTTP の Content-Type が想定される画像形式と一致するか検証します。

2. マジックバイトの検出

サーバーの申告内容にかかわらず、バイナリ署名を検証します：

形式	マジックバイト
JPEG	FF D8 FF
PNG	89 50 4E 47
GIF	47 49 46 38
WebP	WEBP を含む RIFF コンテナー
HEIC/HEIF	ISO ベースメディアファイル（ftyp ボックス）

3. HTML エラーページの検出

画像ではなくエラーページを示す HTML コンテンツを拒否します。

終了コード

コード	名前	説明
0	成功	画像をキャプチャし、保存または出力しました
1	キャプチャ失敗	すべてのキャプチャ方法が失敗しました
2	使用方法エラー	引数が無効、または URL がありません
3	依存関係エラー	Node.js、Playwright、または Chromium の問題です
10	ネットワークエラー	タイムアウト、DNS の失敗、またはホストに到達できません
11	認証が必要	ログインへのリダイレクト、パスワードが必要、または一般公開されていません
12	見つかりません	リンクの期限切れ、ファイルの削除、または 404 です
13	未対応の形式	動画、Google ドキュメント、または画像以外のコンテンツです
20	内部エラー	giil のバグです（報告してください！）

スクリプトでの使用：

giil "https://share.icloud.com/photos/XXX" 2>/dev/null
case $? in
    0) echo "Success!" ;;
    10) echo "Network issue - retry later" ;;
    11) echo "Link not public - ask owner to share" ;;
    12) echo "Link expired" ;;
    *) echo "Failed with code $?" ;;
esac

環境変数

ランタイム変数

変数	説明	デフォルト
XDG_CACHE_HOME	キャッシュの基本ディレクトリ	~/.cache
GIIL_HOME	giil のランタイムディレクトリ	$XDG_CACHE_HOME/giil
PLAYWRIGHT_BROWSERS_PATH	カスタム Chromium キャッシュ	$GIIL_HOME/ms-playwright
GIIL_NO_GUM	gum のスタイル設定を無効化	未設定
GIIL_CHECK_UPDATES	アップデート確認を有効化	未設定

インストーラー変数

変数	説明	デフォルト
DEST	カスタムインストールディレクトリ	~/.local/bin
GIIL_SYSTEM	/usr/local/bin にインストール	未設定
GIIL_VERIFY	SHA256 チェックサムを検証	未設定
GIIL_VERSION	特定のバージョンをインストール	最新

ファイルの場所

パス	用途
~/.local/bin/giil	メインスクリプト
~/.cache/giil/	ランタイムディレクトリ
~/.cache/giil/node_modules/	Playwright、Sharp、exifr
~/.cache/giil/extractor.mjs	生成された Node.js スクリプト
~/.cache/giil/ms-playwright/	Chromium ブラウザーのキャッシュ

デバッグ用ファイル（--debug を指定して失敗した場合）

ファイル	内容
giil_debug_<timestamp>.png	ページ全体のスクリーンショット
giil_debug_<timestamp>.html	ページの DOM コンテンツ

パフォーマンス

フェーズ	初回実行	2 回目以降
Chromium のダウンロード	30-60s	スキップ（キャッシュ済み）
ブラウザーの起動	2-3s	2-3s
ページの読み込み	3-10s	3-10s
画像のキャプチャ	1-5s	1-5s
合計	40-80s	5-15s

Dropbox： 1-2 秒（ブラウザーを使わず、curl で直接処理）。

トラブルシューティング

「Auth required」エラー

リンクが一般公開されていません。所有者がクラウド設定で一般公開を有効にする必要があります。

タイムアウトエラー

タイムアウトを延長します：giil "..." --timeout 120

画像が誤っている／小さい

--debug を指定して実行し、ページの状態を確認します。デバッグ用ファイルを添えて問題を報告してください。

Linux で HEIC の変換に失敗する

sudo apt-get install libheif-examples  # Debian/Ubuntu
sudo dnf install libheif-tools         # Fedora

Chromium の起動に失敗する

giil "..." --update
# Or manually:
cd ~/.cache/giil && npx playwright install --with-deps chromium

デバッグ

# Verbose output
giil "..." --verbose

# Debug artifacts on failure
giil "..." --debug

# Playwright trace (generates trace.zip)
giil "..." --trace
npx playwright show-trace ~/.cache/giil/trace.zip

インストール

# One-liner (recommended)
curl -fsSL "https://raw.githubusercontent.com/Dicklesworthstone/giil/main/install.sh?v=3.0.0" | bash

# Verified installation
GIIL_VERIFY=1 curl -fsSL .../install.sh | bash

# System-wide
GIIL_SYSTEM=1 curl -fsSL .../install.sh | bash

# Manual
curl -fsSL https://raw.githubusercontent.com/Dicklesworthstone/giil/main/giil -o ~/.local/bin/giil
chmod +x ~/.local/bin/giil

アンインストール

rm ~/.local/bin/giil
rm -rf ~/.cache/giil
rm -rf ~/.cache/ms-playwright  # If no other Playwright tools

セキュリティとプライバシー

• ローカルで実行： すべての処理はお使いのマシン上で行われます
• テレメトリなし： クラウドサービス以外にはデータを送信しません
• 認証情報を保存しない： 一般公開共有の仕組みを使用します
• Cookie を保存しない： ブラウザーコンテキストは一時的なものです
• 一時ファイルのクリーンアップ： ダウンロードしたファイルは処理後に削除されます

Flywheel との連携

ツール	連携方法
Claude Code	SSH 経由でビジュアルデバッグ用のスクリーンショットをダウンロード
NTM	マルチエージェントセッション間で画像を共有
Agent Mail	ダウンロードした画像をエージェントのメッセージに添付
CASS	画像のコンテキストとして giil を使用したセッションを検索