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 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. For those commands, use the user's user_fbid from an instagram-cli accounts result available in your context. If none is available, run instagram-cli accounts first. Run accounts again after an auth or account error, or when the user says they connected, disconnected, or switched accounts.

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.

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:

{
  "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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

instagram-cli close-friends --account-id <user_own_fbid>

Feed

Following feed:

instagram-cli feed --account-id <user_own_fbid> --variant following

Close-friends feed:

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.

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.

instagram-cli activity-notifications --account-id <user_own_fbid> [--after <cursor>]

Other user's profile

Fetch another user's profile by user ID, username, or profile URL. Prefer --user-id when you already have a user FBID from prior tool output.
When using --username, pass one username per call. Read the result from profiles[], including bio and website.

instagram-cli user-profile --account-id <user_own_fbid> --user-id <user_fbid>
instagram-cli user-profile --account-id <user_own_fbid> --username @<username>
instagram-cli user-profile --account-id <user_own_fbid> --profile-url https://instagram.com/<username>

Tagged posts

Fetch posts a user has been tagged in. Omit --user-id to fetch the user's own tagged posts. Otherwise, pass the target user's FBID as --user-id.
Narrow results with --since, --until, --sort-order, and --limit.

instagram-cli tagged-posts --account-id <user_own_fbid>
instagram-cli tagged-posts --account-id <user_own_fbid> --after <cursor>
instagram-cli tagged-posts --account-id <user_own_fbid> --user-id <user_fbid>
instagram-cli tagged-posts --account-id <user_own_fbid> --user-id <user_fbid>,<user_fbid> --since 2026-01-01 --until 2026-02-01 --sort-order asc --limit 25

Post by ID or URL

Fetch a single post by its media ID or full Instagram post/reel URL. Provide exactly one of --id or --url.

instagram-cli post --account-id <user_own_fbid> --id <media_id>_<owner_id>
instagram-cli post --account-id <user_own_fbid> --id <media_id>
instagram-cli post --account-id <user_own_fbid> --url https://www.instagram.com/p/<shortcode>/
instagram-cli post --account-id <user_own_fbid> --url https://www.instagram.com/reels/<shortcode>

Post comments

Fetch comments for one or more posts by media ID. Batch IDs in a comma-separated --post-ids list. Narrow results with --since, --until, --sort-order, --limit, and repeated or comma-separated --author-ids.
Read comment text from post_groups[].comments[].comment_text.

instagram-cli fetch-post-comments --account-id <user_own_fbid> --post-ids <media_id>
instagram-cli fetch-post-comments --account-id <user_own_fbid> --post-ids <media_id>,<media_id>
instagram-cli fetch-post-comments --account-id <user_own_fbid> --post-ids <media_id> --limit 25 --after <cursor>
instagram-cli fetch-post-comments --account-id <user_own_fbid> --post-ids <media_id> --since 2026-01-01 --until 2026-02-01 --author-ids <user_fbid>

Post likers

Fetch likers for one or more posts by media ID. Batch IDs in a comma-separated --post-ids list. Narrow results with --since, --until, --sort-order, --limit, and repeated or comma-separated --reactor-ids.
Read the likers from post_groups[].reactors[].

instagram-cli fetch-post-likers --account-id <user_own_fbid> --post-ids <media_id>
instagram-cli fetch-post-likers --account-id <user_own_fbid> --post-ids <media_id>,<media_id>
instagram-cli fetch-post-likers --account-id <user_own_fbid> --post-ids <media_id> --limit 25 --after <cursor>
instagram-cli fetch-post-likers --account-id <user_own_fbid> --post-ids <media_id> --since 2026-01-01 --until 2026-02-01 --reactor-ids <user_fbid>