clinstagram 0.4.0

Let your AI agent run your Instagram.

Post, reply, answer DMs and read the numbers, from one command line your agent already knows how to use.

  

Running an Instagram account is a hundred small jobs a day: publish the post, put up the story, answer the comments, clear the message requests, check what worked. Each is easy. Together they eat the day.

clinstagram hands those jobs to an AI agent. Claude Code, Codex, Cursor, OpenClaw or a plain cron script calls it like any other command and gets short, clean JSON back. No browser to drive, no screen to scrape. The agent reads, decides and acts; you set the rules.

What your agent can do

• Publish. Photos, carousels, reels and stories with link stickers and mentions. Fix a caption after the fact, or take a post down.
• Keep up with people. Read and answer comments, pin the best one, clear message requests, reply to DMs, mark threads read.
• Look after the profile. Name, bio and profile picture, a switch to a Creator or Business account, and the activity feed of new followers, likes and mentions.
• Read the numbers. Reach, saves and shares per post, account insights, follower counts.
• Find people. Search users and hashtags, see who follows an account, who liked a post, where someone is tagged. Download any post or reel.
• Run several accounts. Each keeps its own login, device identity and proxy. Switch with one word.

Getting started

Ask your agent:

Install clinstagram with pip install clinstagram, run clinstagram agent-info, then log me in to Instagram.

That's the whole setup. agent-info tells the agent every command and option, so it needs no manual. To do it by hand:

pip install clinstagram
clinstagram auth login -u your_username
clinstagram profile show

clinstagram needs Python 3.10 or newer, and ffmpeg if you post video.

Safe by default

Instagram punishes accounts that act like bots, so clinstagram is careful out of the box:

• Reading is open, writing is opt-in. The default mode uses Meta's official API wherever it can and the unofficial one only to read. Posting and messaging through the unofficial API wait until you switch on private-enabled.
• Follows and likes need a second key. Every such call must carry --enable-growth-actions, so an agent can't start mass-liking by accident.
• It paces itself. Writes are spaced out with random delays, and hourly and daily caps on DMs, follows and likes live in ~/.clinstagram/config.toml.
• Secrets stay in your keychain. Logins and tokens go to the macOS Keychain, Secret Service on Linux or Windows Credential Manager. Nothing sits on disk in plain text.

Give a new account a week of normal use before you automate it. Instagram trusts new accounts least: they see fewer posts and hit limits sooner.

Made for agents

Every command answers in compact JSON: the fields an agent needs, without the long image links that waste its context. --full brings everything back; --fields id,caption returns only what you ask for.

When something goes wrong, the exit code says what kind of problem it is (bad input, expired login, rate limit, blocked by your settings) and the error carries the exact fix, so the agent can recover without asking you.

clinstagram reaches Instagram two ways and picks one per command: Meta's official Graph API for Business and Creator accounts, and instagrapi for everything the official API can't do. --backend forces either.

Running a channel

The news-channel playbook lays out a full day for a niche news account: the morning post and story, the comment and DM rounds, the evening numbers, and how to find the people worth reaching. It's written around AgingResearch.News, and the routine carries over to any channel.

Contributing

Bug reports and pull requests are welcome. See CONTRIBUTING.md.

License

MIT