# instagram-cli: an unofficial terminal client built on instagram-private-api, whose login has to be patched whenever Instagram changes its auth flow > supreme-gg-gg/instagram-cli is a TypeScript chat and feed client for Instagram that runs in a terminal and ships as @i7m/instagram-cli on npm. This review covers install, the TUI and one-turn commands, image protocols, and the fragility that comes from an unofficial API. **supreme-gg-gg/instagram-cli** — Instagram's CLI and TUI client -- The ultimate weapon against brainrot - Repository: https://github.com/supreme-gg-gg/instagram-cli - Website: https://www.npmjs.com/package/@i7m/instagram-cli - Stars: 2,203 · Forks: 152 - Language: TypeScript - License: MIT - Published: 2026-10-14 · Updated: 2026-10-30 · Language: en - Canonical page: https://hysenlabs.com/projects/supreme-gg-gg-instagram-cli ## The README opens with a warning that using it might violate Meta's Terms of Service Before any feature description, the README states that the project is not affiliated with, authorized or endorsed by Instagram. It calls itself independent and unofficial, says using it might violate Meta's Terms of Service, and tells you to use it at your own risk. That is the main fact for anyone deciding whether to log in. Your Instagram credentials go to a third-party program that talks to Instagram through unofficial means. The dependency list names instagram-private-api at ^1.46.1 and instagram_mqtt at ^1.2.3, which are the pieces that reach Instagram's private endpoints. The pitch is attention control. The README calls it the ultimate weapon against brainrot, and lists chatting with friends without endless scrolling, 100% keyboard navigation and no mouse or touchscreen. Its one explicit boundary is that Instagram CLI is not meant for bot behaviours, and contributions that add such features will not be accepted. ## Installation needs Node.js 22 or higher through npm, or a Homebrew tap on macOS and Linux There are two install paths. The npm route requires Node.js v22 or higher, and package.json agrees with engines set to node >=22: ```bash npm install -g @i7m/instagram-cli ``` The Homebrew route taps the author's own repository: ```bash brew tap supreme-gg-gg/tap brew install instagram-cli ``` The formula lives at supreme-gg-gg/homebrew-tap, in Formula/instagram-cli.rb. Installing from source is described in DEVELOPMENT.md, not in the README. The installed binary is named instagram-cli, set in the bin field to dist/cli.js. The package is ESM, built with esbuild, and runs a postinstall step of patch-package, which applies the files in the patches folder shipped with the package. The repository also contains a snap folder. ## Login saves each account locally and auth switch moves between them The CLI commands start with authentication: ```bash instagram-cli # display title art instagram-cli --help # view available commands # Authentication instagram-cli auth login --username # login with username and password instagram-cli auth logout # logout and removes session instagram-cli auth switch # switch to another saved account instagram-cli auth whoami # display current default user # Launches TUI interfaces instagram-cli chat -u -t # start chat interface instagram-cli feed ``` Login is by username and password. The README says the login for each account is saved locally, and you can switch accounts with auth switch or run one command as a given account with the --username flag. The latest release explains why this part matters. ts-v2.1.0 is titled as migrating auth to Instagram's new CAA flow, with the note that it should fix login again. The word again tells you login has broken before, and the README admits Instagram may update its API or protocols and break features. ## Chat mode is driven by colon commands and a hash prefix for attachments Once a thread is selected, the chat interface is keyboard-driven, and messaging commands start with a colon: ```bash # Select messages to perform actions :select :react <emoji | :emoji_name:> :reply <text> :unsend # Media Handling :upload <path-to-image-or-video> :download <path-to-save> # Requires :select first to select message # Navigation :k # go up :K # go to top :j # go down :J # go to bottom ``` One ordering rule is explicit: :download requires :select first, because it acts on the selected message. Navigation uses j and k in the vi style, with capitals jumping to the bottom or top. You can include a file in a message by typing # followed by its path, such as #path/to/file.txt or #path/to/image.png, and tab and enter autocomplete the path. Emojis use :emoji_name: with fuzzy matching, and :thumbsup: gives a thumbs up. Mouse support exists for selecting messages, scrolling and moving the cursor, and the README says more is being rolled out. ## One-turn commands print to stdout and take -o json, which is the route for scripts and agents A second set of commands skips the TUI. They run once, print to stdout and exit, and every one accepts -o json for structured output. The README gives examples and says to run -h for the full manual: ```bash # These are only example usages. Run -h / --help for full manual. instagram-cli inbox instagram-cli send <thread> --text "Hey, how are you?" instagram-cli read <thread> --limit 10 --mark-seen --output json instagram-cli read <thread> --message-id <id> --download "./photo.jpg" instagram-cli reply <thread> --message-id <id> --text "Hey, how are you?" instagram-cli unsend <thread> --message-id <id> ``` The thread argument accepts a thread ID, a username or a fuzzy thread title. The README advises passing thread IDs from inbox -o json directly, to avoid redundant lookups. For agent frameworks the repository ships skills/instagram-skill/SKILL.md, and the README gives npx skills add supreme-gg-gg/instagram-cli to load it. That file covers the commands, the JSON format, thread resolution and multi-account use, per the README. Note the tension with the no-bot policy: scripting your own inbox is in scope, bulk behaviour is not. ## Image rendering picks a terminal protocol automatically and image.protocol overrides it Images in the TUI are drawn with a protocol chosen to suit your terminal emulator. If rendering looks wrong, you can set it yourself with instagram-cli config image.protocol followed by one of the options. The available values are ascii, halfBlock, braille, kitty, iterm2 and sixel. The README adds a caution: the configured protocol must be supported by the terminal, and sixel and iterm2 will not work in Kitty. Rendering is done by Ink Picture, an Ink Image component the authors wrote and publish separately at endernoke/ink-picture. The README says issues and pull requests about image display belong in that upstream repository. The release history shows how much work this has taken: ts-v2.0.0 on 2026-07-06 was about Ink picture v2 and image and UI enhancements, and ts-v2.0.1 on 2026-07-09 was image display stability improvements. The package depends on ink-picture ^2.1.0 and ink ^7.0.0. ## Bug reports need log files from ~/.instagram-cli/logs, and the repository holds two clients When something breaks, the README asks you to file a GitHub issue and attach the files from ~/.instagram-cli/logs/. It suggests redacting sensitive data such as your username first. Instagram changing its API or protocols is named as the cause of occasional breakage. Contributors face a structural rule. The README says it is very important to follow CONTRIBUTING.md because two different clients are managed in the same repository, and the release tags start with ts-, which marks the TypeScript one. The root also holds AGENTS.md, DEVELOPMENT.md, skills/, tests/ and source/. Scripts include start:mock, which runs dist/mocks/cli.mock.js, so a mock client exists for development. The repository is not archived, MIT licensed, and the last push was on 2026-10-23, the same day as ts-v2.1.0. Tests run through ava after prettier and xo checks. Several libraries in package.json show what the client is made of. React ^19.2.0 and Ink ^7.0.0 draw the interface, with @inkjs/ui and pastel for components and routing. fuse.js ^7.1.0 supplies the fuzzy matching, which fits the fuzzy thread titles in the one-turn commands. node-notifier ^10.0.1 is listed for desktop notifications, zod ^4.1.0 for validation and meow ^14.0.0 for argument parsing. The README does not explain how notifications are triggered, so test that before depending on it. The build script runs tsc --noEmit and then esbuild in production mode, while the dev:watch script rebuilds on change. The files field publishes only dist and patches, so the npm package carries no source or tests. Installation from source therefore goes through DEVELOPMENT.md, and a contributor needs the full toolchain including husky hooks installed by the prepare script. Most of the project's value depends on whether the private API still accepts the login, and only the latest release speaks to that. ## Conclusion Use instagram-cli if you want Instagram direct messages and a feed in a terminal, with keyboard control, and you accept that it is unofficial and may break the Instagram terms of service. Skip it for anything that looks like automation at scale, because the README says bot behaviours are not welcome and the project warns about Meta's terms. Before relying on it, check that your account can still log in with the current release, since v2.1.0 exists specifically to repair authentication. ## FAQ ### What is instagram-cli? instagram-cli is an unofficial, independent Instagram client for the terminal, with chat and feed interfaces. It is published as @i7m/instagram-cli on npm under the MIT license. ### How do I install instagram-cli? Run npm install -g @i7m/instagram-cli with Node.js v22 or higher, or use brew tap supreme-gg-gg/tap followed by brew install instagram-cli on macOS or Linux. ### Can I use Instagram on Linux with instagram-cli? The README says you can run it from any terminal, including a Linux server, and it lists a Homebrew install for macOS and Linux. It is unofficial and might violate Meta's terms. ## Sources - [License: MIT](https://github.com/supreme-gg-gg/instagram-cli/blob/main/LICENSE) - [Project website](https://www.npmjs.com/package/@i7m/instagram-cli) - [README](https://github.com/supreme-gg-gg/instagram-cli/blob/main/README.md) - [Releases](https://github.com/supreme-gg-gg/instagram-cli/releases) - [supreme-gg-gg/instagram-cli on GitHub](https://github.com/supreme-gg-gg/instagram-cli) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/supreme-gg-gg-instagram-cli