instagram skill
- Repo stars 1,952
- Author repo instagram-cli
- Domain
- Other
- Author-declared agents
- No explicit declaration found; this is not inferred or tested compatibility
- Static check
- 88 / 100 · heuristic scan, not runtime safety proof
- Runtime evidence
- Not run; no isolated runtime test evidence is currently recorded
- Author / version / license
- @supreme-gg-gg · no license declared
- Token usage
- Lean
- Setup complexity
- Plug-and-play
- External API key
- Not required
- Operating systems
- Unspecified (assume cross-platform)
- Runtime requirements
- No explicit requirements detected
- Detected file/system behavior
-
- Read-only
- Network behavior
- Local-only
- Install commands
- None (reference only)
Heads up: Tool permissions are not declared; actual access depends on the runtime.
# JSON Output
{ "ok": true, "data": { ... } }
{ "ok": false, "error": "message" }
# 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:
```json
{ "ok": true, "data": { ... } }
{ "ok": false, "error": "message" }
```
Always use `--output json` when you need to parse results programmatically.
---
## Commands
### List inbox
```bash
instagram-cli inbox [--limit <n>] [--output json]
```
Returns recent threads. Each thread includes: `id`, `title`, `users`, `lastMessage`, `lastActivity`, `unread`.
```bash
# Get 10 most recent threads as JSON
instagram-cli inbox --limit 10 --output json
```
### Search threads
```bash
instagram-cli inbox --search <query> [--limit <n>] [--output json]
```
Searches by both username and thread title, merging results by relevance score.
```bash
instagram-cli inbox --search "alice" --output json
```
### Send a message
```bash
instagram-cli send <thread> --text <message> [--output json]
instagram-cli send <thread> --file <path> [--type photo|video] [--output json]
```
`<thread>` is a thread ID, username, or title. `--text` and `--file` are mutually exclusive.
Media type is auto-detected from extension; use `--type` to override.
```bash
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
```
### Read messages
```bash
instagram-cli read <thread> [--limit <n>] [--cursor <cursor>] [--mark-seen] [--output json]
```
Returns messages newest-first. Use `cursor` from the previous response to paginate older messages.
Pass `--mark-seen` to mark the thread as read after fetching.
```bash
instagram-cli read johndoe --limit 20 --output json
instagram-cli read 340282366920938463123456789 --mark-seen
```
Each message in JSON output includes: `id`, `itemType`, `text`, `userId`, `username`, `timestamp`, `isOutgoing`.
### Download media from a message
```bash
instagram-cli read <thread> --message-id <id> --download <path> [--output json]
```
Finds the message by ID (paginates up to `--max-pages`, default 10) and saves the media file.
The file extension is automatically inferred if not provided.
```bash
instagram-cli read johndoe --message-id 340282366... --download ./media
```
### Reply to a message
```bash
instagram-cli reply <thread> --message-id <id> --text <text> [--output json]
```
Sends a threaded reply to a specific message.
```bash
instagram-cli reply johndoe --message-id 340282366... --text "Totally agree!"
```
### Unsend a message
```bash
instagram-cli unsend <thread> --message-id <id> [--output json]
```
```bash
instagram-cli unsend johndoe --message-id 340282366...
```
---
## Multi-Account Support
All commands accept `-u <username>` / `--username <username>` to target a specific logged-in account.
Omitting it uses the default account set via `instagram-cli auth switch`.
```bash
instagram-cli inbox -u myworkaccount --output json
instagram-cli send johndoe --text "Hi" -u mypersonalaccount
```
---
## Typical Agent Workflow
```bash
# 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
```
---
## Error Handling
- **Auth errors** → user needs to run `instagram-cli auth login`
- **"No thread found matching"** → the username/title didn't resolve; try `inbox --search` first
- **`"ok": false`** in JSON output → the `error` field contains the reason
- Rate limits / network errors are surfaced as error messages; retry with backoff if needed
Sections and files
Listed in source order.
sections -> Thread Resolution → JSON Output → Commands → List inbox → Search threads → Send a message
terms -> one-turn commands · Thread ID · Username · Thread title · Best practice for multi-step workflows · Auth errors · "No thread found matching" · "ok": false
files/cmd -> instagram-cli · instagram-cli auth login · <thread> · 340282366920938463... · johndoe · "Book Club" · inbox --output json · -o json
body sha256 -> 7ab8bb154bee
Thread Resolution
Every command that targets a thread accepts a
<thread>argument resolved in this order: Thread ID (20+ digit number like340282366920938463...) — direct, zero extra API calls Username — exact Instagram username (e.g.johndoe) Thread title — fuzzy search across inbox (e.g."Book Club") Best practice for multi-step workflows: callinbox --output jsonfirst to get thread IDs,JSON Output
All commands accept
-o json/--output json. Responses follow this envelope: Always use--output jsonwhen you need to parse results programmatically.List inbox
Returns recent threads. Each thread includes:
id,title,users,lastMessage,lastActivity,unread.Search threads
Searches by both username and thread title, merging results by relevance score.
Send a message
<thread>is a thread ID, username, or title.--textand--fileare mutually exclusive. Media type is auto-detected from extension; use--typeto override.