clinstagram

Full Instagram CLI — posting, DMs, stories, analytics, followers, hashtags, likes, comments. Supports Meta Graph API (official, safe) and private API (full f...

Security Scan

The skill largely matches its stated purpose (an Instagram CLI combining Graph API and a private API) but contains implementation/metadata mismatches and a few design choices that deserve scrutiny before installation.

Purpose & Capability

The name/description (Instagram CLI, Graph + private API) matches the included code and commands. Requested artifacts (binary 'clinstagram' and a config dir env var) are appropriate. However there are inconsistencies: the registry metadata claimed 'No install spec / instruction-only' while the SKILL.md includes an install hint (pip install clinstagram) and the skill bundle contains a full Python package source tree. Also a declared primary credential env var (CLINSTAGRAM_SECRETS_FILE) is present in metadata but the visible code uses OS keychain and an encrypted-file fallback — I couldn't find a clear use of that env var in the shown files. These mismatches are explainable but should be clarified.

Instruction Scope

SKILL.md instructs the agent to run the clinstagram CLI and to use CLINSTAGRAM_CONFIG_DIR for config — that is within scope. It explicitly describes compliance modes and safety gates (e.g., growth actions disabled by default), and documents remediation commands to run on auth failure. One operational concern: SKILL.md tells agents to read an error 'remediation' field and execute the remediation command automatically; that gives an agent broad discretion to run login/config commands if it follows those instructions autonomously. The instructions also include interactive challenge handling (prompts) which may block non-interactive runs. No instructions were found that ask the agent to read unrelated system files or unrelated environment variables.

Install Mechanism

SKILL.md metadata includes an explicit pip install (pip: clinstagram) which is a standard install path. However the registry metadata summary indicated there was 'No install spec — instruction-only' despite a full source tree being bundled. That inconsistency (bundle contains full package + SKILL.md lists a pip install) is a red flag for sloppy packaging or for a mismatch between what will actually be executed by the platform and what the developer intended. Installing from PyPI via pip is normal, but confirm the package origin (PyPI project vs. the bundled source) before installing. No high-risk download-from-URL or archive-extract installs were seen.

Credentials

The skill asks only for CLINSTAGRAM_CONFIG_DIR and declares CLINSTAGRAM_SECRETS_FILE as the primary credential — a small and plausible set for a CLI that needs a config directory and secrets. There are no unrelated credentials (AWS, GCP, etc.). However, the declared primary env var (CLINSTAGRAM_SECRETS_FILE) is not obviously referenced in the visible code (which prefers OS keychain and encrypted-file fallback), so the need for this particular env var should be clarified. The code also requires network access and may ask for username/password (private API) during auth — expected for the stated functionality.

Persistence & Privilege

The skill does not request 'always: true' and does not attempt to change other skills' configurations. It persists sessions/secrets in OS keychain or an encrypted file (as documented), which is normal for a CLI that logs into services. One risk factor: the platform-default autonomous invocation combined with the ability to use a private Instagram session means an autonomous agent could take account-affecting actions (DMs, follow/unfollow) if it enables private-enabled mode or the --enable-growth-actions flag. The skill tries to mitigate this (growth actions disabled by default and a compliance mode system), but the combination of autonomous invocation + private API capability increases potential impact if the skill is misused or if agent prompts are followed without user confirmation.

What to consider before installing

What to check before installing: - Clarify the packaging/install path: SKILL.md includes a pip install, the bundle contains a full Python package, and the registry entry said 'instruction-only' — ask the publisher which you should install (the bundled source or pip) and verify the package source (PyPI project page or the GitHub repo). Avoid blindly pip-installing an unverified package. - Confirm how secrets are provided: the metadata declares CLINSTAGRAM_SECRETS_FILE as the primary credential, but the code uses OS keychain (keyring) and mentions an encrypted-file fallback. Ask where that env var is read and how the secret file is formatted. If you plan to run non-interactively (CI/agent), prefer an explicit, documented secrets-file workflow and avoid putting plaintext credentials in env vars. - Prefer conservative compliance mode: if you only need official Graph API functionality (posting, analytics, comments), run in official-only mode to avoid the private API. If you must use private features, use hybrid-safe (read-only private) rather than private-enabled. - Be cautious with autonomous agents: the skill can be invoked by agents autonomously (platform default). If you allow autonomous invocation, restrict what the agent can do (do not enable --enable-growth-actions, do not enable private-enabled mode) and ensure the agent prompts you before enabling risky flags. - Audit the remaining source files (private backend and any networking code) for any hard-coded endpoints or telemetry/exfil endpoints not belonging to Instagram/Meta. The visible code hits graph.instagram.com / graph.facebook.com and uses instagrapi for private API — that's expected. If you are not comfortable sharing production credentials, test with a throwaway Instagram account first. If you want, I can: (1) search the rest of the bundled source for references to CLINSTAGRAM_SECRETS_FILE or any unexpected remote endpoints, (2) list the exact files that reference network calls, or (3) extract the obvious places agent-automation could run commands so you can add containment policies.

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.