Instagram (web session)

Run every command from this skill directory:

cd <skill-dir>        # the folder containing this SKILL.md
npx -y bun scripts/main.ts <command> [options]     # add --json for a machine envelope

No install step: Bun runs the TypeScript directly and the scripts have zero npm dependencies. ffmpeg is optional (PNG/WebP to JPEG conversion and reel cover frames).

Ground rules (follow every time)

1. Writes are dry runs by default. post, edit-caption, comment and reply print the exact requests and validation result and send nothing. Show the user the media, caption and warnings, get an explicit yes for that post, then re-run the same command with --confirm --account <username>. Approval for one post never covers the next one. The dry run shows signedInAs: say which account the post will go to, and if it is not the account the user means, stop and have them login --force as the right one. --account is required with --confirm, and the write refuses if the session is another account.
2. Unverified writes need a second opt-in. A write runs with --confirm alone only once its contract is verified-live (status lists them). Photos, carousels, reels, stories, comments and replies are verified (reels through the "comet async" form instagram.com requires since 2026-11-12; verified 2026-11-13). Reel tags (--tag) and the AI label (--ai-label) are verified too (2026-11-13). Collaborator invites (--collab), the story AI label and edit-caption still need --experimental. Story mentions (--mention) were tried live and did NOT take: tell the user to add the mention in the app. Tell the user the endpoint has not been proven on a real account and may fail, and suggest a test account for the first try.
3. Stop on account signals. On rate_limited (HTTP 429), checkpoint, feedback_required or not_logged_in, stop all Instagram calls and report the error's hint. Never retry in a loop, never switch endpoints to get around it.
4. Never retry an unclear publish. If a publish ends without a clear answer, the CLI records it as pending and refuses new posts. Run pending check <id>, ask the user to look at the profile, and resolve with pending resolve <id> --posted|--not-posted. Only one publish runs at a time; a second one is refused while the first is running. A crashed run's lock is ignored automatically. pending unlock only tidies up those files.
5. No engagement automation. There are no follow, like or DM commands, by design. Comments and replies are one at a time, with the user approving each text. Instagram restricts accounts that automate engagement.
6. Never print or paste cookie values. status shows redacted lengths only.

Authentication

npx -y bun scripts/main.ts login                 # opens Chrome (dedicated profile); sign in, 2FA is fine
npx -y bun scripts/main.ts login --force         # always re-open Chrome (--timeout <sec>, default 300)
npx -y bun scripts/main.ts import-cookies cookies.json   # Cookie-Editor JSON, cookies.txt, or "Cookie:" header
npx -y bun scripts/main.ts whoami                # confirms the session against Instagram
npx -y bun scripts/main.ts status                # offline: saved cookies (redacted), pending publishes
npx -y bun scripts/main.ts logout                # deletes cookies, caches and the Chrome profile (--keep-profile keeps it)

The session needs sessionid, csrftoken and ds_user_id for .instagram.com. sessionid is HttpOnly, so login reads cookies over the Chrome DevTools protocol. The data directory (%APPDATA%\instagram-ai, ~/Library/Application Support/instagram-ai, or $XDG_DATA_HOME/instagram-ai) is locked to the current user before anything is written (icacls on Windows, 0700/0600 elsewhere). If that fails, nothing is saved. INSTAGRAM_COOKIES can carry a session for one process without touching disk.

Reading

npx -y bun scripts/main.ts profile [username]                 # default: own account
npx -y bun scripts/main.ts posts [username] --limit 30     # default: own account; newest first
npx -y bun scripts/main.ts media <url|shortcode|id>
npx -y bun scripts/main.ts comments <url|shortcode|id> --limit 50
npx -y bun scripts/main.ts hashtag <tag> --limit 24
npx -y bun scripts/main.ts search <query>
npx -y bun scripts/main.ts audit [username] --limit 30 --tz America/Bogota
npx -y bun scripts/main.ts swipe user1,user2,user3 --limit 24 --min 3

Every read reports via, meaning which endpoint answered. Reads try the REST endpoints first, then a GraphQL persisted query whose doc_id is discovered from the live web bundles. The last resort is the 12 posts embedded in the profile response. When via says "embedded, max 12", tell the user the sample is small. Counters can be null when the owner hid like counts. Reach, saves, shares and profile visits are Insights-only and never available here.

audit returns the metric set used by the instagram-audit skill. swipe scores each post against its own account's median, and is used by instagram-research. Keep research small: at most 12 accounts per run, and the CLI spaces requests at least 1.5 s apart.

Publishing

# 1. Dry run: show this output to the user
npx -y bun scripts/main.ts post photo ./img.jpg --caption-file caption.txt --alt "Alt text"
npx -y bun scripts/main.ts post carousel ./1.jpg ./2.jpg ./3.mp4 --caption "..."
npx -y bun scripts/main.ts post reel ./reel.mp4 --caption "..." --cover ./cover.jpg   # or --cover-at 1.5
npx -y bun scripts/main.ts post story ./story.jpg

# 2. After explicit approval of that exact post
npx -y bun scripts/main.ts post photo ./img.jpg --caption-file caption.txt --alt "Alt text" --confirm --account <username>

--experimental stays required until that write type is marked verified-live.

Options: --disable-comments, --hide-likes, --no-feed (reel only on the Reels tab), --max-hashtags N (default 5, Instagram's current cap), --ignore-pending (only after the user resolved pending publishes by looking at the profile).

Validation before anything is uploaded:

Prefer a caption file (--caption-file) for anything with line breaks or quotes, to avoid shell quoting problems on Windows. Lint captions first with the instagram-content skill's caption-lint.ts.

Managing

npx -y bun scripts/main.ts edit-caption <ref> --caption-file new.txt [--confirm --account <username> --experimental]
npx -y bun scripts/main.ts comment <ref> --text "..." [--confirm --account <username>]
npx -y bun scripts/main.ts reply <ref> <commentId> --text "..." [--confirm --account <username>]

Every confirmed write appends a line (ids, urls, never cookies) to actions.jsonl in the data directory. Use it to find what the CLI posted, or to finish a failed cleanup by hand.

Errors

probe [--refresh-config] [--graphql] checks the main endpoints with a handful of GETs and stops at the first 429. Run it only when diagnosing, not routinely.

Additional resources

• references/endpoints.md: every endpoint, request contract and evidence status, how to re-verify them from the live web client, and what to edit when Instagram changes something.
• scripts/endpoints.ts (the endpoint table), scripts/publish.ts (write contracts and CONTRACTS status), scripts/graphql.ts (doc_id discovery).

Environment variables

Bun auto-loads a .env file from the working directory, which could set any of these. Always run from this skill directory (it ships no .env), or add --no-env-file after bun. Origin overrides (INSTAGRAM_BASE_URL and friends) are ignored unless they are https on instagram.com.