clinstagram
Hybrid Instagram CLI for AI agents. Routes between Meta Graph API and instagrapi private API based on compliance policy.
Install
pip install clinstagram
Critical: Global Flags Before Subcommand
clinstagram --json --account main dm inbox # CORRECT
clinstagram dm inbox --json # WRONG — Typer limitation
Global flags: --json, --account NAME, --backend auto|graph_ig|graph_fb|private, --proxy URL, --dry-run, --enable-growth-actions
Quick Start
# Check status
clinstagram --json auth status
# Set compliance mode
clinstagram config mode official-only # Graph API only, zero risk
clinstagram config mode hybrid-safe # Graph primary, private read-only (default)
clinstagram config mode private-enabled # Full access, user accepts risk
# Connect backends
clinstagram auth connect-ig # Instagram Login (posting, comments, analytics)
clinstagram auth connect-fb # Facebook Login (adds DMs, stories, webhooks)
clinstagram auth login # Private API (username/password/2FA via instagrapi)
Commands
| Group |
Commands |
Notes |
auth |
status, login, connect-ig, connect-fb, probe, logout |
Start with auth status --json |
post |
photo, video, reel, carousel |
Accepts local paths or URLs |
dm |
inbox, thread ID, send @user "text", send-media, search |
Cold DMs = private API only |
story |
list [@user], post-photo, post-video, viewers ID |
|
comments |
list MEDIA_ID, add, reply, delete |
add/reply need --enable-growth-actions |
analytics |
profile, post ID|latest, hashtag TAG |
|
followers |
list, following, follow @user, unfollow @user |
follow/unfollow need --enable-growth-actions |
user |
info @user, search QUERY, posts @user |
|
hashtag |
top TAG, recent TAG |
|
like |
post MEDIA_ID, undo MEDIA_ID |
Needs --enable-growth-actions |
config |
show, mode MODE, set KEY VAL |
Modes: official-only, hybrid-safe, private-enabled |
JSON Output
Success:
{"exit_code": 0, "data": {}, "backend_used": "graph_fb"}
Error:
{"exit_code": 2, "error": "session_expired", "remediation": "Run: clinstagram auth login", "retry_after": null}
Exit Codes
| Code |
Meaning |
Action |
| 0 |
Success |
Parse data |
| 1 |
Bad arguments |
Fix syntax |
| 2 |
Auth error |
Run remediation command |
| 3 |
Rate limited |
Wait retry_after seconds |
| 4 |
API error |
Retry |
| 5 |
Challenge required |
Check challenge_type, prompt user |
| 6 |
Policy blocked |
Change compliance mode |
| 7 |
Capability unavailable |
Connect another backend |
Agent Workflow
# 1. Check what's available
clinstagram --json auth status
# 2. Probe capabilities
clinstagram --json auth probe
# 3. Preview before acting
clinstagram --dry-run --json post photo img.jpg --caption "test"
# 4. Execute
clinstagram --json dm inbox --unread --limit 20
# 5. On error, read remediation field and execute it
Growth Actions (Disabled by Default)
Follow, unfollow, like, unlike, comment add/reply require --enable-growth-actions. This is a safety gate — confirm with user before enabling.
Backend Capability Matrix
| Feature |
graph_ig |
graph_fb |
private |
| Post |
Y |
Y |
Y |
| DM inbox |
- |
Y |
Y |
| Cold DM |
- |
- |
Y |
| Stories |
- |
Y |
Y |
| Comments |
Y |
Y |
Y |
| Analytics |
Y |
Y |
Y |
| Follow/Unfollow |
- |
- |
Y |
| Hashtag |
Y |
Y |
Y |
Preference order: graph_ig > graph_fb > private. Override with --backend.
Examples
# Check DMs
clinstagram --json dm inbox --unread
# Reply to a message
clinstagram --json dm send @alice "Thanks!"
# Post a photo
clinstagram --json post photo /path/to/img.jpg --caption "Hello world"
# Get analytics
clinstagram --json analytics post latest
# Search users
clinstagram --json user search "coffee shops"
# Browse hashtag
clinstagram --json hashtag top photography --limit 10
Config
File: ~/.clinstagram/config.toml. Override dir with CLINSTAGRAM_CONFIG_DIR env var.
1---2name: clinstagram3description: Full Instagram CLI — posting, DMs, stories, analytics, followers, hashtags, likes, comments. Supports Meta Graph API (official, safe) and private API (full features). Three compliance modes: official-only, hybrid-safe, private-enabled.4---56# clinstagram78Hybrid Instagram CLI for AI agents. Routes between Meta Graph API and instagrapi private API based on compliance policy.910## Install1112```bash13pip install clinstagram14```1516## Critical: Global Flags Before Subcommand1718```bash19clinstagram --json --account main dm inbox # CORRECT20clinstagram dm inbox --json # WRONG — Typer limitation21```2223Global flags: `--json`, `--account NAME`, `--backend auto|graph_ig|graph_fb|private`, `--proxy URL`, `--dry-run`, `--enable-growth-actions`2425## Quick Start2627```bash28# Check status29clinstagram --json auth status3031# Set compliance mode32clinstagram config mode official-only # Graph API only, zero risk33clinstagram config mode hybrid-safe # Graph primary, private read-only (default)34clinstagram config mode private-enabled # Full access, user accepts risk3536# Connect backends37clinstagram auth connect-ig # Instagram Login (posting, comments, analytics)38clinstagram auth connect-fb # Facebook Login (adds DMs, stories, webhooks)39clinstagram auth login # Private API (username/password/2FA via instagrapi)40```4142## Commands4344| Group | Commands | Notes |45|-------|----------|-------|46| `auth` | `status`, `login`, `connect-ig`, `connect-fb`, `probe`, `logout` | Start with `auth status --json` |47| `post` | `photo`, `video`, `reel`, `carousel` | Accepts local paths or URLs |48| `dm` | `inbox`, `thread ID`, `send @user "text"`, `send-media`, `search` | Cold DMs = private API only |49| `story` | `list [@user]`, `post-photo`, `post-video`, `viewers ID` | |50| `comments` | `list MEDIA_ID`, `add`, `reply`, `delete` | add/reply need `--enable-growth-actions` |51| `analytics` | `profile`, `post ID\|latest`, `hashtag TAG` | |52| `followers` | `list`, `following`, `follow @user`, `unfollow @user` | follow/unfollow need `--enable-growth-actions` |53| `user` | `info @user`, `search QUERY`, `posts @user` | |54| `hashtag` | `top TAG`, `recent TAG` | |55| `like` | `post MEDIA_ID`, `undo MEDIA_ID` | Needs `--enable-growth-actions` |56| `config` | `show`, `mode MODE`, `set KEY VAL` | Modes: `official-only`, `hybrid-safe`, `private-enabled` |5758## JSON Output5960Success:61```json62{"exit_code": 0, "data": {}, "backend_used": "graph_fb"}63```6465Error:66```json67{"exit_code": 2, "error": "session_expired", "remediation": "Run: clinstagram auth login", "retry_after": null}68```6970## Exit Codes7172| Code | Meaning | Action |73|------|---------|--------|74| 0 | Success | Parse `data` |75| 1 | Bad arguments | Fix syntax |76| 2 | Auth error | Run `remediation` command |77| 3 | Rate limited | Wait `retry_after` seconds |78| 4 | API error | Retry |79| 5 | Challenge required | Check `challenge_type`, prompt user |80| 6 | Policy blocked | Change compliance mode |81| 7 | Capability unavailable | Connect another backend |8283## Agent Workflow8485```bash86# 1. Check what's available87clinstagram --json auth status8889# 2. Probe capabilities90clinstagram --json auth probe9192# 3. Preview before acting93clinstagram --dry-run --json post photo img.jpg --caption "test"9495# 4. Execute96clinstagram --json dm inbox --unread --limit 209798# 5. On error, read remediation field and execute it99```100101## Growth Actions (Disabled by Default)102103Follow, unfollow, like, unlike, comment add/reply require `--enable-growth-actions`. This is a safety gate — confirm with user before enabling.104105## Backend Capability Matrix106107| Feature | graph_ig | graph_fb | private |108|---------|:--------:|:--------:|:-------:|109| Post | Y | Y | Y |110| DM inbox | - | Y | Y |111| Cold DM | - | - | Y |112| Stories | - | Y | Y |113| Comments | Y | Y | Y |114| Analytics | Y | Y | Y |115| Follow/Unfollow | - | - | Y |116| Hashtag | Y | Y | Y |117118Preference order: `graph_ig` > `graph_fb` > `private`. Override with `--backend`.119120## Examples121122```bash123# Check DMs124clinstagram --json dm inbox --unread125126# Reply to a message127clinstagram --json dm send @alice "Thanks!"128129# Post a photo130clinstagram --json post photo /path/to/img.jpg --caption "Hello world"131132# Get analytics133clinstagram --json analytics post latest134135# Search users136clinstagram --json user search "coffee shops"137138# Browse hashtag139clinstagram --json hashtag top photography --limit 10140```141142## Config143144File: `~/.clinstagram/config.toml`. Override dir with `CLINSTAGRAM_CONFIG_DIR` env var.
dvcrn