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.