instagram-skill

Instagram CLI — エージェント利用ガイド

Instagram CLI（instagram-cli）は、Instagram 用のターミナルクライアントです。エージェント向けに、標準出力に出力して終了する1 回限りのコマンドを提供しており、スクリプトやツールの利用に最適です。

すべての1回限りのコマンドを実行するには、ユーザーがすでにログインしている必要があります（instagram-cli auth login）。 コマンドが認証エラーを返した場合は、まずログインするようユーザーに促してください。CLI を使って自分でログインしようとしないでください。

---

スレッドの特定

スレッドを対象とする各コマンドは、次の順序で解決される <thread> 引数を受け取ります。

1. スレッド ID（340282366920938463... のような20桁以上の数字）— 直接指定でき、余分な API 呼び出しは不要です
2. ユーザー名 — Instagram の正確なユーザー名（例：johndoe）
3. スレッド名 — 受信トレイ全体からのあいまい検索（例："Book Club"）

複数ステップのワークフローでのベストプラクティス： まず inbox --output json を呼び出してスレッド ID を取得し、その後のコマンドには ID を直接渡します。これにより、重複した検索 API 呼び出しを避けられ、ユーザー名やスレッド名での照合よりも確実です。

---

JSON 出力

すべてのコマンドで -o json / --output json を指定できます。レスポンスは次の形式に従います。

{ "ok": true, "data": { ... } }
{ "ok": false, "error": "message" }

結果をプログラムで解析する必要がある場合は、必ず --output json を使用してください。

---

コマンド

受信トレイの一覧表示

instagram-cli inbox [--limit <n>] [--output json]

最近のスレッドを返します。各スレッドには id、title、users、lastMessage、lastActivity、unread が含まれます。

# Get 10 most recent threads as JSON
instagram-cli inbox --limit 10 --output json

スレッドの検索

instagram-cli inbox --search <query> [--limit <n>] [--output json]

ユーザー名とスレッド名の両方で検索し、関連度スコアに基づいて結果を統合します。

instagram-cli inbox --search "alice" --output json

メッセージの送信

instagram-cli send <thread> --text <message> [--output json]
instagram-cli send <thread> --file <path> [--type photo|video] [--output json]

<thread> にはスレッド ID、ユーザー名、またはスレッド名を指定します。--text と --file は同時に指定できません。 メディアの種類は拡張子から自動判定されます。上書きするには --type を使用してください。

instagram-cli send johndoe --text "Hey, are you free tonight?"
instagram-cli send 340282366920938463123456789 --text "Got it!"
instagram-cli send "Book Club" --file ./photo.jpg --output json

メッセージの読み取り

instagram-cli read <thread> [--limit <n>] [--cursor <cursor>] [--mark-seen] [--output json]

メッセージを新しい順に返します。前のレスポンスの cursor を使用して、古いメッセージをページネーションで取得します。 取得後にスレッドを既読にするには、--mark-seen を指定します。

instagram-cli read johndoe --limit 20 --output json
instagram-cli read 340282366920938463123456789 --mark-seen

JSON 出力の各メッセージには id、itemType、text、userId、username、timestamp、isOutgoing が含まれます。

メッセージからメディアをダウンロード

instagram-cli read <thread> --message-id <id> --download <path> [--output json]

ID でメッセージを検索し（--max-pages で指定したページ数まで、デフォルトは10）、メディアファイルを保存します。 指定されていない場合、ファイル拡張子は自動的に推定されます。

instagram-cli read johndoe --message-id 340282366... --download ./media

メッセージへの返信

instagram-cli reply <thread> --message-id <id> --text <text> [--output json]

特定のメッセージにスレッド形式で返信を送信します。

instagram-cli reply johndoe --message-id 340282366... --text "Totally agree!"

メッセージの送信取り消し

instagram-cli unsend <thread> --message-id <id> [--output json]

instagram-cli unsend johndoe --message-id 340282366...

---

複数アカウントのサポート

すべてのコマンドで -u <username> / --username <username> を指定すると、ログイン済みの特定のアカウントを対象にできます。 省略した場合は、instagram-cli auth switch で設定されたデフォルトアカウントが使用されます。

instagram-cli inbox -u myworkaccount --output json
instagram-cli send johndoe --text "Hi" -u mypersonalaccount

---

エージェントの一般的なワークフロー

# 1. Get inbox to find the right thread
INBOX=$(instagram-cli inbox --output json --limit 20)
# Parse "id" fields from INBOX to find the target thread

# 2. Read recent messages (use thread ID for speed)
THREAD_ID="340282366920938463..."
instagram-cli read "$THREAD_ID" --limit 10 --output json

# 3. Reply or send
instagram-cli send "$THREAD_ID" --text "On my way!" --output json

# 4. Mark as seen
instagram-cli read "$THREAD_ID" --mark-seen

---

エラー処理

• 認証エラー → ユーザーは instagram-cli auth login を実行する必要があります
• "No thread found matching" → ユーザー名またはスレッド名を解決できませんでした。まず inbox --search を試してください
• JSON 出力で "ok": false が返された場合 → error フィールドに理由が含まれています
• レート制限やネットワークエラーはエラーメッセージとして表示されます。必要に応じて、間隔を空けて再試行してください