{"id":48963777,"url":"https://github.com/paperfoot/clinstagram","last_synced_at":"2026-04-18T03:04:10.294Z","repository":{"id":342590801,"uuid":"1174488484","full_name":"paperfoot/clinstagram","owner":"paperfoot","description":"Instagram CLI for AI agents. Meta Graph API + instagrapi private API. JSON output, policy routing.","archived":false,"fork":false,"pushed_at":"2026-04-17T20:43:01.000Z","size":1962,"stargazers_count":4,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-04-17T22:29:22.057Z","etag":null,"topics":["ai-agent-tools","ai-agents","automation","cli","graph-api","instagram","instagram-api","instagram-automation","instagram-bot","instagram-cli","instagram-dm","instagram-posting","instagram-stories","instagrapi","meta-graph-api","openclaw","python","python-cli","social-media","social-media-automation"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/paperfoot.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-06T13:57:27.000Z","updated_at":"2026-04-17T20:43:05.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/paperfoot/clinstagram","commit_stats":null,"previous_names":["199-biotechnologies/clinstagram","paperfoot/clinstagram"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/paperfoot/clinstagram","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/paperfoot%2Fclinstagram","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/paperfoot%2Fclinstagram/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/paperfoot%2Fclinstagram/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/paperfoot%2Fclinstagram/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/paperfoot","download_url":"https://codeload.github.com/paperfoot/clinstagram/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/paperfoot%2Fclinstagram/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31954738,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-18T00:39:45.007Z","status":"online","status_checked_at":"2026-04-18T02:00:07.018Z","response_time":103,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agent-tools","ai-agents","automation","cli","graph-api","instagram","instagram-api","instagram-automation","instagram-bot","instagram-cli","instagram-dm","instagram-posting","instagram-stories","instagrapi","meta-graph-api","openclaw","python","python-cli","social-media","social-media-automation"],"created_at":"2026-04-18T03:04:03.961Z","updated_at":"2026-04-18T03:04:10.273Z","avatar_url":"https://github.com/paperfoot.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n\u003cimg src=\"assets/logo.png\" alt=\"Clinstagram\" width=\"128\"\u003e\n\n# Clinstagram\n\n**The Instagram CLI that AI agents actually use.**\n\n\u003cbr /\u003e\n\n[![Star this repo](https://img.shields.io/github/stars/paperfoot/clinstagram?style=for-the-badge\u0026logo=github\u0026label=%E2%AD%90%20Star%20this%20repo\u0026color=yellow)](https://github.com/paperfoot/clinstagram/stargazers)\n\u0026nbsp;\u0026nbsp;\n[![Follow @longevityboris](https://img.shields.io/badge/Follow_%40longevityboris-000000?style=for-the-badge\u0026logo=x\u0026logoColor=white)](https://x.com/longevityboris)\n\n\u003cbr /\u003e\n\n[![PyPI](https://img.shields.io/pypi/v/clinstagram?style=for-the-badge\u0026logo=pypi\u0026logoColor=white)](https://pypi.org/project/clinstagram/)\n[![Python 3.10+](https://img.shields.io/badge/python-3.10+-3776ab?style=for-the-badge\u0026logo=python\u0026logoColor=white)](https://www.python.org/)\n[![License: MIT](https://img.shields.io/badge/license-MIT-green?style=for-the-badge)](LICENSE)\n[![Tests](https://img.shields.io/badge/tests-120%20passing-brightgreen?style=for-the-badge)](tests/)\n\n---\n\nOne CLI. Two backends. Zero browser automation. Clinstagram wraps the official Meta Graph API and the instagrapi private API behind a single command-line interface with structured JSON output. Policy-driven routing picks the safest path for every command automatically.\n\n[Install](#install) | [How It Works](#how-it-works) | [Commands](#commands) | [Contributing](#contributing)\n\n\u003c/div\u003e\n\n## Why This Exists\n\nEvery Instagram automation tool makes you choose: official API (safe but limited) or private API (full-featured but risky). Clinstagram gives you both.\n\nYou run one command. The router checks your compliance mode, inspects your configured backends, and picks the safest path. No Playwright. No Selenium. No headless browsers. Just structured JSON output with exit codes that AI agents can parse.\n\n```bash\n$ clinstagram --json dm inbox\n{\"exit_code\":0,\"data\":[{\"thread_id\":\"839201\",\"thread_title\":\"alice\", ...}],\"backend_used\":\"graph_fb\"}\n```\n\n## Install\n\nRequires **Python 3.10+**.\n\n```bash\npip install clinstagram\n```\n\nOr from source:\n\n```bash\ngit clone https://github.com/paperfoot/clinstagram.git\ncd clinstagram\npip install -e \".[dev]\"\n```\n\n### Quick Start\n\n```bash\n# 1. Log in (username, email, or phone — locale auto-detected)\nclinstagram auth login -u your_username\n\n# 2. Optional: connect official Graph API tokens\nclinstagram auth connect-ig --token \u003cinstagram-login-token\u003e\nclinstagram auth connect-fb --token \u003cfacebook-login-token\u003e\n\n# 3. Check what is configured\nclinstagram --json auth status\n\n# 4. Start using it\nclinstagram --json dm inbox\nclinstagram --json analytics profile\nclinstagram --json post photo cat.jpg --caption \"via clinstagram\"\n```\n\n\u003e **Note:** `--json`, `--proxy`, and `--account` are **global flags** and go **before** the command name.\n\n## How It Works\n\nClinstagram routes every command through a policy engine that picks the best backend based on your compliance mode and available credentials.\n\n```\nCLI Command\n    ↓\nPolicy Router (capability matrix x compliance mode)\n    ↓\n┌──────────┬──────────┬────────────┐\n│ graph_ig │ graph_fb │  private   │\n│ (OAuth)  │ (OAuth)  │(instagrapi)│\n│ Post     │ Post+DM  │ Everything │\n│ Comments │ Stories  │ + proxy    │\n│Analytics │ Webhooks │ + keychain │\n└──────────┴──────────┴────────────┘\n```\n\n### Three Backends\n\n| Backend | Auth | Best For |\n|---------|------|----------|\n| `graph_ig` | Instagram Login token | Posting, comments, analytics |\n| `graph_fb` | Facebook Login token | Above + DMs, story publishing |\n| `private` | Username/password/2FA | Everything. Cold DMs. Personal accounts. |\n\n### Three Compliance Modes\n\n| Mode | Official API | Private API | Risk |\n|------|-------------|-------------|------|\n| `official-only` | Full | Disabled | Zero |\n| `hybrid-safe` | Full | Read-only | Low |\n| `private-enabled` | Full | Full | High |\n\nDefault is `hybrid-safe`. You get official API for everything it supports, plus private API for read-only operations like viewing stories.\n\n## Commands\n\n### Posting\n\n```bash\nclinstagram --json post photo \u003cpath|url\u003e --caption \"...\" --tags \"@user\"\nclinstagram --json post video \u003cpath|url\u003e --caption \"...\"\nclinstagram --json post reel \u003cpath|url\u003e --caption \"...\"\nclinstagram --json post carousel img1.jpg img2.jpg --caption \"...\"\n```\n\n### Direct Messages\n\n```bash\nclinstagram --json dm inbox --unread --limit 10\nclinstagram --json dm thread @alice --limit 20\nclinstagram --json dm send @alice \"Thanks for reaching out!\"\nclinstagram --json dm send-media @alice photo.jpg\nclinstagram --json dm search \"project\"\n```\n\n### Stories\n\n```bash\nclinstagram --json story list\nclinstagram --json story list @alice\nclinstagram --json story post-photo photo.jpg --mention @alice\nclinstagram --json story post-video clip.mp4 --link \"https://...\"\nclinstagram --json story viewers \u003cstory_id\u003e\n```\n\n### Analytics\n\n```bash\nclinstagram --json analytics profile\nclinstagram --json analytics post \u003cmedia_id\u003e\nclinstagram --json analytics hashtag \"photography\"\n```\n\n### Comments\n\n```bash\nclinstagram --json comments list \u003cmedia_id\u003e --limit 50\nclinstagram --json comments reply \u003ccomment_ref\u003e \"Great point!\"\nclinstagram --json comments delete \u003ccomment_ref\u003e\n```\n\n### Followers\n\n```bash\nclinstagram --json followers list --limit 100\nclinstagram --json followers following\nclinstagram --json --enable-growth-actions followers follow @user\nclinstagram --json --enable-growth-actions followers unfollow @user\n```\n\n### User Lookup\n\n```bash\nclinstagram --json user info @username\nclinstagram --json user search \"alice\"\nclinstagram --json user posts @username --limit 10\n```\n\n### Auth \u0026 Config\n\n```bash\nclinstagram agent-info               # Machine-readable manifest (ACF)\nclinstagram doctor                   # Health check (sessions, environment)\nclinstagram update --check           # Check for CLI updates\nclinstagram auth status              # Show configured backends\nclinstagram auth probe               # Live-check token validity\nclinstagram auth login -u user       # Private API login\nclinstagram auth connect-ig          # Store Instagram Login token\nclinstagram auth connect-fb          # Store Facebook Login token\nclinstagram auth logout --yes        # Clear all sessions\n\nclinstagram config mode hybrid-safe  # Set compliance mode\nclinstagram config set proxy socks5://localhost:1080\n```\n\n### Global Flags\n\n| Flag | Description |\n|------|-------------|\n| `--json` | JSON output (auto-enabled when piped) |\n| `--account \u003cname\u003e` | Switch between stored accounts |\n| `--backend auto\\|graph_ig\\|graph_fb\\|private` | Force a specific backend |\n| `--proxy \u003curl\u003e` | SOCKS5/HTTP proxy for private API |\n| `--dry-run` | Preview without executing |\n| `--enable-growth-actions` | Unlock follow/unfollow |\n\n## For AI Agents\n\nClinstagram is built for AI agents like [OpenClaw](https://github.com/openclaw/openclaw). Every command returns structured JSON with a `backend_used` field so your agent knows which path was taken.\n\nExit codes tell the agent exactly what happened:\n\n| Exit Code | Meaning | Agent Action |\n|-----------|---------|--------------|\n| 0 | Success | Parse JSON |\n| 1 | Bad arguments | Fix command |\n| 2 | Auth error | Run `auth login` |\n| 3 | Rate limited | Retry after `retry_after` seconds |\n| 4 | API error | Retry or report |\n| 5 | Challenge required | Prompt user (2FA) |\n| 6 | Policy blocked | Change compliance mode |\n| 7 | Capability unavailable | Connect additional backend |\n\nEvery error includes a `remediation` field with the exact fix:\n\n```json\n{\"exit_code\": 2, \"error\": \"session_expired\", \"remediation\": \"Run: clinstagram auth login\"}\n```\n\n### OpenClaw Integration\n\n```bash\npip install clinstagram\n# The included SKILL.md tells OpenClaw what commands are available\n```\n\n## Configuration\n\n```toml\n# ~/.clinstagram/config.toml\n[rate_limits]\ngraph_dm_per_hour = 200       # Meta's hard limit\nprivate_dm_per_hour = 30      # Conservative default\nprivate_follows_per_day = 20  # Below Instagram's threshold\nrequest_delay_min = 2.0       # Seconds between private API writes\nrequest_delay_max = 5.0\nrequest_jitter = true         # Randomized delays\n```\n\nSecrets are stored in your OS keychain (macOS Keychain, Linux Secret Service, Windows Credential Manager). No plaintext tokens on disk.\n\n## Contributing\n\nContributions are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.\n\n```bash\ngit clone https://github.com/paperfoot/clinstagram.git\ncd clinstagram\npip install -e \".[dev]\"\npytest tests/ -v   # 120 tests\n```\n\n## License\n\n[MIT](LICENSE)\n\n---\n\n\u003cdiv align=\"center\"\u003e\n\nBuilt by [Boris Djordjevic](https://github.com/longevityboris) at [199 Biotechnologies](https://github.com/199-biotechnologies) | [Paperfoot AI](https://paperfoot.ai)\n\n\u003cbr /\u003e\n\n**If this is useful to you:**\n\n[![Star this repo](https://img.shields.io/github/stars/paperfoot/clinstagram?style=for-the-badge\u0026logo=github\u0026label=%E2%AD%90%20Star%20this%20repo\u0026color=yellow)](https://github.com/paperfoot/clinstagram/stargazers)\n\u0026nbsp;\u0026nbsp;\n[![Follow @longevityboris](https://img.shields.io/badge/Follow_%40longevityboris-000000?style=for-the-badge\u0026logo=x\u0026logoColor=white)](https://x.com/longevityboris)\n\n\u003c/div\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpaperfoot%2Fclinstagram","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpaperfoot%2Fclinstagram","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpaperfoot%2Fclinstagram/lists"}