instagram-skill

Instagram CLI — Agent Usage Guide

Instagram CLI (instagram-cli) is a terminal client for Instagram. For agents, it exposes one-turn commands that print to stdout and exit — perfect for scripting and tool-use.

All one-turn commands require the user to already be logged in (instagram-cli auth login). If a command returns an auth error, prompt the user to log in first. Do not attempt to login using the CLI by yourself.

---

Thread Resolution

Every command that targets a thread accepts a <thread> argument resolved in this order:

1. Thread ID (20+ digit number like 340282366920938463...) — direct, zero extra API calls
2. Username — exact Instagram username (e.g. johndoe)
3. Thread title — fuzzy search across inbox (e.g. "Book Club")

Best practice for multi-step workflows: call inbox --output json first to get thread IDs, then pass those IDs directly to subsequent commands. This avoids redundant search API calls and is more reliable than username/title matching.

---

JSON Output

All commands accept -o json / --output json. Responses follow this envelope:

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

Always use --output json when you need to parse results programmatically.

---

Commands

List inbox

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

Returns recent threads. Each thread includes: id, title, users, lastMessage, lastActivity, unread.

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

Search threads

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

Searches by both username and thread title, merging results by relevance score.

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

Send a message

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