openclaw/clinstagram

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.