gem-hunter
Language: TypeScript
Instagram's CLI and TUI client -- The ultimate weapon against brainrot
The ultimate weapon against brainrot. The distraction-free, lightweight, portable Instagram client in your terminal.
Warning
This project is not affiliated with, authorized, or endorsed by Instagram. This is an independent and unofficial project. Using it might violate Meta's Terms of Service. Use at your own risk.
Empower yourself to become a 10x Instagrammer by minimizing distractions, enabling 100% keyboard control, and accessing it from any terminal — whether in your VSCode editor or your Linux server.
Instagram CLI allows you to use social media more intentionally -- to stay connected with people you care about rather than being exploited for your attention.
Requires Node.js v22 or higher.
npm install -g @i7m/instagram-cli
brew tap supreme-gg-gg/tap brew install instagram-cli
The formula is available here.
For installation from source, please refer to the TypeScript Client Documentation.
The following commands will be available after installing the package:
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 <username> # switch to another saved account instagram-cli auth whoami # display current default user # Launches TUI interfaces instagram-cli chat -u <username> -t <title> # start chat interface instagram-cli feed # view posts from people you follow instagram-cli stories # view stories from people you follow (BETA) instagram-cli notify # view notifications (inbox, followers, mentions) # Modify configuration # The configuration file is located at `~/.instagram-cli/config.ts.yaml`. instagram-cli config # lists all config instagram-cli config <key> <value> # set config key to value instagram-cli config edit # open config file in editor
If you want to use Instagram CLI with AI agents, see one-turn commands that are non-interactive and designed for agents.
Tip
You can easily manage multiple accounts with Instagram CLI!
Your login for each account will be saved locally and you can switch between them using the instagram-cli auth switch <username> command or run a certain command with a specific account using the --username flag.
Inside the chat interface and after selecting a thread, you can navigate all interface with 100% keyboard support. When messaging, the following commands are available:
# 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
Tip
You can quickly include text files or images in a message by using # followed by the file path. For example, #path/to/file.txt or #path/to/image.png.
Use tab and enter to autocomplete file paths. You can include emojis in messages with :emoji_name: e.g. :thumbsup: = 👍 (with fuzzy matching).
Instagram CLI supports mouse interactions as well, so you can click on messages to select them, scroll through the chat, and click to reposition the cursor when typing messages. We're gradually rolling out more mouse support in our TUI!
These commands are non-interactive (no TUI) — they run once, print to stdout, and exit. They're designed for scripting, piping, and AI agent tool-use. All commands accept -o json for structured JSON output. Example usage includes:
# 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>
<thread> accepts a thread ID, username, or fuzzy thread title. Prefer passing thread IDs (from inbox -o json) directly to avoid redundant lookups.
Tip
Building an AI agent that uses Instagram? Load ./skills/instagram-skill/SKILL.md
into your agent's workspace (or point your agent framework at it). It covers all commands, JSON
output format, thread resolution, multi-account usage, and a recommended workflow.
npx skills add supreme-gg-gg/instagram-cli
When rendering images in the terminal, we automatically select the best image protocol based on your terminal emulator. If you experience issues with image rendering or wish to customize the image protocol, you can change the config setting with instagram-cli config image.protocol <option>. The available options are "ascii", "halfBlock", "braille", "kitty", "iterm2", "sixel".
Note
Make sure the configured protocol is supported by your terminal (e.g. sixel and iterm2 protocols won't work in Kitty).
We use Ink Picture, our own open-source Ink <Image> component, for displaying images in the terminal. Any related issues or pull requests should be filed on the upstream repository.
We welcome contributors! Please see the comprehensive CONTRIBUTING.md file for details on how to get started, create issues, and submit pull requests. It is very important that you follow these instructions because we manage two different clients in the same repository. Instagram CLI is NOT meant to be used for bot-behaviours, we will not accept contributions that add such features.
Occasionally, Instagram may update their API or protocols which can cause certain features to break. If you encounter any issues, please report them on our GitHub Issues page. Make sure to attach the relevant log files located at ~/.instagram-cli/logs/ to help us diagnose and fix the problem quickly. You may want to redact sensitive data like your username for privacy.
We contributed the following extensions to the Ink open-source ecosystem for building Terminal UI apps: