instagram

# Instagram CLI ## Purpose Read, manage, and answer questions about Instagram data. ## Analyzing posts and reels Before working with the content of an Instagram post or reel, read [Instagram content questions](references/content-questions.md) with `muse.read`. State what you checked, distinguish guesses from verified facts, and say what you could not verify. ## Account Linking Every `instagram-cli` command except `accounts`, `connect-url`, `disconnect-url`, and `--help` requires `--account-id`. Use the user's `user_fbid` from an `instagram-cli accounts` result already in context. If it is missing, run `instagram-cli accounts` once to get it. For a user-requested task, recheck after an account change or authentication error. A timeout or rate limit does not establish an account change or disconnection. If several accounts are returned without a selection in the task, or the selected linked account conflicts with the requested publishing destination, resolve the account choice before running the affected command. Reuse an explicit account choice already in the task without asking again. An agent in live conversation asks the user about an unresolved choice. A subagent returns an unresolved choice to its parent agent. A detached worker reports an unresolved choice in its final message. Do not choose an account arbitrarily. For a user-requested task, if a command says Instagram is not connected, check its `--account-id` against the refreshed `accounts` result. If the selected account is returned with a different `user_fbid`, retry with that value. Treat Instagram as unlinked only when `accounts` returns an empty list or the command reports it is not connected using the selected account's freshly verified `user_fbid`. If unlinked and the task requires an account, run `instagram-cli connect-url` and use its `connect_url` in the message below: > Your Instagram account is not connected. To connect it, visit [Meta Accounts Center](`connect_url`) and link your Instagram account. A link to a post or reel does not need the user's account. Follow Instagram content questions for it. Reading a public profile does not require connecting Instagram. If no account is linked, use web search or a browser task for public-profile questions. If browser inspection is still needed, use `browser.spawn_task` when available. A subagent returns the known profile URL or username and unresolved question to its parent agent only if browser inspection is still needed and `browser.spawn_task` is unavailable. The native `profile`, `user-profile`, and `post` commands still require a linked account. Do not send a connect link for a public-only task unless the user asks to connect. If the user asks to disconnect Instagram, run `instagram-cli disconnect-url` and send the user its `disconnect_url`: > To disconnect your Instagram account, visit [Meta Accounts Center](`disconnect_url`) and remove the linked account. Use the URL returned by the corresponding command. Do not hardcode it. ## Related skills - Use the `instagram_messages` skill for inbox, thread, and message reads, DM search and sending, and top recipients. Follow its separate messaging connection and sending rules. - Use `social.search` for general post discovery. - Use this skill for direct `account-insights` reports and for explaining or rewriting supplied metric values. Use `social_content_performance` for performance comparisons, trends, or content recommendations for the user's own accounts and posts. Use `social_competitor_analysis` for competitor, peer, or category comparisons. When every account in a performance comparison belongs to the user, use `social_content_performance`. If `social_content_performance` or `social_competitor_analysis` is unavailable, use this skill's documented reads for the parts of the request they support. Use `account-insights` only for the user's linked accounts. For competitors, use public `profile` and `posts` data under the Account Linking rules. Do not substitute the user's account totals for competitor metrics or invent missing values. State which requested metrics or comparisons remain unavailable. ## Running commands Run `instagram-cli` commands with `exec`. Use flag names exactly as documented. Unknown flags can be ignored without an error. For `fetch-post-comments` and `fetch-post-likers`, use `--post-ids` even for one post. For `save-post`, `unsave-post`, and `media-understanding`, use `--media-ids` even for one item. The singular flags `--post-id` and `--media-id` are unsupported. Reuse results already in your context. When a script will process a result, redirect the first call's output to a file under `~/workspace/` and read that file. Do not rerun a successful command with the same arguments in the same task. The Instagram API enforces rate limits. If a request returns `429 Too Many Requests`, stop all `instagram-cli` calls for this task, including calls issued by scripts. For a post or reel link, continue with the fallbacks in Instagram content questions. Otherwise, report what you completed and what remains. In scripts, check the exit status of each `instagram-cli` call. Stop at the first 429, and do not treat a failed call as an empty result. If a bulk read repeatedly returns HTTP 500, stop issuing calls for that bulk read, including from scripts. An HTTP 500 alone does not identify a rate limit. State how much you read and what remains. For requests covering an entire list, fetch every page while pagination makes progress. Stop before requesting a cursor already used for that list. Also stop when a page reports more pages but adds no new items. Apply these checks inside pagination scripts. If you stop before completing the requested scope, state how much you read and what remains. When a request needs a separate `user-profile`, `profile`, or `post` call for each of more than 50 accounts or posts, start with the 50 most recent. Stop after those 50. Report their results and how many remain for a later batch. Instagram rate-limits these calls after a few dozen. Perform write actions only when the user explicitly asks for the change. This includes interest updates, publishing, and profile changes. `instagram-cli` does not support following, unfollowing, removing followers, blocking, liking, commenting, replying to comments, deleting posts, archiving posts, pinning posts, or editing captions. ### Post output `posts`, `feed`, and `post` return the same compact post collection used by `social.search`. Read `posts[]` directly. Do not guess a provider GraphQL path or pipe these commands through `jq`: ```json { "format": "social_posts_v1", "count": 1, "posts": [{ "rank": 1, "post_id": "...", "url": "https://www.instagram.com/...", "platform": "instagram", "post_created_at": {"utc":"...","user_local":"...","user_timezone":"..."}, "username": "account", "post_caption": "..." }], "next_cursor": "...", "has_next_page": true } ``` Prefer `post_created_at.user_local` when presenting a post time. The response retains `created_at` for compatibility. Fields unavailable in the provider response are omitted. A feed item can omit `url` or `created_at`. Before quoting, dating, or linking a selected feed item, run `post --id <post_id>` and use the returned record. A valid partial response includes the provider's reason in optional `provider_error`. Do not describe it as a complete page. If required post data is absent, the CLI fails and includes that reason when the provider supplied one. Without a provider reason, it reports the schema mismatch rather than returning an empty post list. Post rows can include the author's `username`, `author_name`, `author_bio`, `follower_count`, and `verified`. Use these returned fields instead of a separate profile lookup for the same information, unless the request needs missing or refreshed profile information. The `posts`, `feed`, and `post` responses can include per-post counts in `likes` and `comments`, but do not expose per-post views, reach, saves, or shares. Do not assign account-level totals to individual posts. ### Global options - `--account-id <user_own_fbid>` selects the account. Use the user's own `user_fbid` from Account Linking. Do not pass another user's ID. - `--retries <N>` retries transient failures. The default is 0. Nonzero values are unsupported for `post-story`, `post-feed`, `set-profile-picture`, and `profile-banner`. - `--after <cursor>` supplies the pagination cursor from the previous response, except for `own-stories-archive`, which uses `--max-id`. Omit the cursor to fetch the first page. For `fetch-post-comments` and `fetch-post-likers`, pagination is per `post_groups[]` entry. To fetch another page for an entry with `has_next_page` set to true, pass only its `media_id` as `--post-ids` and its `end_cursor` as `--after`. ## Commands Available commands: - `accounts` - `connect-url` - `disconnect-url` - `profile` - `current-interests` - `posts` - `followers` - `following` - `close-friends` - `feed` - `activity-notifications` - `user-profile` - `tagged-posts` - `post` - `fetch-post-comments` - `fetch-post-likers` - `saved-posts` - `saved-collections` - `create-saved-collection` - `rename-saved-collection` - `save-post` - `unsave-post` - `own-stories` - `own-stories-archive` - `stories-tray` - `story-media` - `location-search` - `media-understanding` - `account-insights` - `recently-liked-posts` - `recently-commented-posts` - `update-interests` - `post-feed` - `post-story` - `set-profile-picture` - `update-bio` - `profile-banner` ### Accounts List the Instagram accounts linked to the user. ```sh instagram-cli accounts ``` ### Profile Fetch the Instagram profile bio and follower/following counts. Omit `--username` and `--profile-url` to fetch the user's own profile. Otherwise, provide a username or profile URL to fetch another user's profile. When only counts are needed, use this command instead of fetching the follower or following lists. When using `--username`, pass one username per call. Read the result from `profiles[]`, including `bio` and `website`. For `profile` and `user-profile`, an empty `profiles` list alone does not establish that a handle is available or reserved, or that the tool failed. ```sh instagram-cli profile --account-id <user_own_fbid> instagram-cli profile --account-id <user_own_fbid> --username <username> instagram-cli profile --account-id <user_own_fbid> --username @<username> instagram-cli profile --account-id <user_own_fbid> --profile-url https://instagram.com/<username> ``` ### Update bio Update the user's Instagram profile bio. `--bio` is required and may contain at most 150 characters. Pass an empty string to clear the bio. ```sh instagram-cli update-bio --account-id <user_own_fbid> --bio "<bio>" ``` ### Muse profile banner Add or remove the user's Muse banner on their Instagram profile. This shows as a pill on the user's profile beneath their bio. This does not change their profile picture or bio. ```sh instagram-cli profile-banner --account-id <user_own_fbid> --action add instagram-cli profile-banner --account-id <user_own_fbid> --action remove ``` Do not supply media or a profile URL. Report completion only when the result contains `success: true`; `success: false` is not a completed update. Automatic retries are disabled; after an ambiguous failure, do not claim success or silently repeat the mutation. ### Current interests Fetch topics the user is interested in or uninterested in. Show the topic and its type without distinguishing inferred from explicit interests. ```sh instagram-cli current-interests --account-id <user_own_fbid> ``` ### Update interests Mark a topic as "interested" so the user sees more of it on Instagram, or as "not interested" so the user sees less of it. ```sh instagram-cli update-interests --account-id <user_own_fbid> --text "<topic>" --interested true instagram-cli update-interests --account-id <user_own_fbid> --text "<topic>" --interested false ``` ### Posts Omit `--username` and `--user-id` to fetch the user's own posts. Otherwise, provide one or more usernames or one or more user IDs to fetch other users' posts. Do not mix usernames and user IDs in the same command. Pass the previous response's `next_cursor` as `--after`. Omit `--after` on the first request. Narrow results with `--since`, `--until`, `--sort-order asc|desc`, `--limit`, and repeated or comma-separated `--post-types` values such as `POST`, `REEL`, `STORY`, or `HIGHLIGHT`. The response can contain more posts than `--limit` requests. Attribute each post to its returned `username`, which can differ from the requested account. When the request is for posts and reels only, pass `--post-types POST,REEL`. Do not infer profile-grid order or pin status from the order of returned posts. ```sh instagram-cli posts --account-id <user_own_fbid> instagram-cli posts --account-id <user_own_fbid> --after <cursor> instagram-cli posts --account-id <user_own_fbid> --username <username> instagram-cli posts --account-id <user_own_fbid> --username <username>,<username> instagram-cli posts --account-id <user_own_fbid> --user-id <FBID> instagram-cli posts --account-id <user_own_fbid> --user-id <FBID>,<FBID> instagram-cli posts --account-id <user_own_fbid> --username <username> --since 2026-01-01 --until 2026-02-01 --sort-order asc --limit 25 --post-types POST,REEL ``` ### Followers Fetch the user's own follower list. `--count` is optional and defaults to `200`. Read the returned `users[]` list. To fetch another page when `has_more` is true, pass the previous response's `next_max_id` as `--after`. Omit `--after` on the first request. For `followers` and `following`, `users[]` entries include `id`, `username`, `full_name`, and `profile_pic_url`. Compare list membership by `id` without per-account profile lookups. ```sh instagram-cli followers --account-id <user_own_fbid> instagram-cli followers --account-id <user_own_fbid> --count 25 instagram-cli followers --account-id <user_own_fbid> --after <cursor> ``` ### Following Fetch the user's own following list. Other users' following lists are not supported. `--count` is optional and defaults to `200`. Read the returned `users[]` list. To fetch another page when `page_info.has_next_page` is true, pass the previous response's `page_info.end_cursor` as `--after`. Omit `--after` on the first request. ```sh instagram-cli following --account-id <user_own_fbid> instagram-cli following --account-id <user_own_fbid> --count 25 instagram-cli following --account-id <user_own_fbid> --after <cursor> ``` ### Close friends Fetch the user's current Instagram close friends list. This is the user's own curated Close Friends list on Instagram. It is not ranked or inferred. To get an inferred list of people the user interacts with most, use the `top-recipients` command from the `instagram_messages` skill instead. ```sh instagram-cli close-friends --account-id <user_own_fbid> ``` ### Feed Following feed: ```sh instagram-cli feed --account-id <user_own_fbid> --variant following ``` Close-friends feed: ```sh instagram-cli feed --account-id <user_own_fbid> --variant favorites ``` `--variant` is required. Its supported values are `following` and `favorites`. The ranked home timeline is not readable through this surface. Omitting `--variant` returns an error. For all feed variants, pass the previous response's `next_cursor` as `--after`. Omit `--after` on the first request. ```sh instagram-cli feed --account-id <user_own_fbid> --variant following --after <cursor> ``` ### Activity notifications Fetch `notifications` and `priority_notifications` without marking them seen. Paginate with `page_info.end_cursor` as `--after`. ```sh