# Instagram CLI
The ultimate weapon against brainrot. Shown experimentally to effectively reduce screentime.
[](https://pepy.tech/projects/instagram-cli)
[](https://github.com/supreme-gg-gg/instagram-cli/blob/main/LICENSE)
[](https://github.com/supreme-gg-gg/instagram-cli/issues)
<!--  -->
<!--  -->
https://github.com/user-attachments/assets/e9206e14-8141-49b2-8e2c-17c76402e3cb
> [!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.
## What does it do?
- We transform Instagram from a brainrot hell into productivity tool
- We allow you to focus on meaningful conversations
- We celebrate the art and simplicity of terminal UI
- We extend Instagram with powerful plugins like latex, chat summarisation
> [!TIP]
> Use Instagram with 100% keyboard control - no mouse clicks or touchscreen taps needed! Perfect for developers and Linux users who love staying on the keyboard 🤣
### Need a break and have some brainrot?
Want to watch Instagram Reels right from your terminal? Check out [reels-cli](https://github.com/notMarkMP1/reels-cli). It’s a great way to enjoy some light entertainment without leaving your keyboard. (Not affiliated and not maintained by us, but highly recommended for terminal fans.)
## Installation
The simplest way to get started is to install the package from PyPI if you have Python installed:
```bash
pip install instagram-cli
```
If you do not have Python installed, you can download and install it from the [official website](https://www.python.org/downloads/).
### Installation from Source
```bash
git clone https://github.com/supreme-gg-gg/instagram-cli.git
cd instagram-cli
pip install .
```
### Pre-built Executables
> [!CAUTION]
> This option is **not recommended** unless the other methods do not work for you.
We no longer provide pre-built executables. If you want to run the application in an environment without Python, you can build the executable yourself with `pyinstaller`. We recommend using the `instagram-cli.spec` file we provided.
```bash
pyinstaller --onedir instagram-cli.spec
```
This will generate the executable in the `dist/` directory.
```bash
./instagram-cli [OPTIONS] command [ARGS] # for macOS and Linux
instagram-cli.exe [OPTIONS] command [ARGS] # for Windows
```
> [!CAUTION]
> Starting from Version 1.3, Windows support will be discontinued due to incompatibilities between the `curses` and `windows-curses` libraries. While the application may still work on Windows, we will no longer be testing or maintaining Windows-specific functionality. We recommend using WSL (Windows Subsystem for Linux) or Docker for Windows users.
## Commands
The following commands will be available after installing the package:
```bash
instagram # display title art
instagram --help # view available commands
# Authentication
instagram auth login -u # login with username and password
instagram auth logout # logout and removes session
# Chat Features
instagram chat start # start chat interface
instagram chat search -u <username> # search and open chat by username
instagram chat search -t <text> # search and open chat by chat title
# Utility Commands
instagram notify # view notifications (inbox, followers, mentions)
instagram schedule ls # view scheduled messages
instagram schedule cancel <index> # cancel scheduled message
instagram stats --days <last_n_days> # view usage analytics (default: 14 days)
instagram config --get --set --edit # manage custom configuration
instagram cleanup -t # cleanup media and session cache files
```
## Chat
The chat interface is the main feature of this package. It allows you to interact with your Instagram chats in a terminal-based interface.
In the chat list page, use arrow keys (or 'j', 'k') + Enter to select a chat. You can also search for user by username using @user_name + Enter.
> [!NOTE]
> All searches in the package uses a custom fuzzy matching based on ratcliff/obershelp similarity algorithm. This means chat search and emoji search will be more flexible and forgiving.
After entering the chat page, you can type messages as usual and send them with Enter. You can also use chat commands to supercharge your chat experience.
> [!TIP]
> Press Enter in the middle of a message to insert a line break, and at the very end to send it.
### Chat Commands
All chat commands have the following syntax:
```bash
:command <args> <long-args>
```
> [!IMPORTANT]
> Long arguments should have special enclosures such as `"..."` for strings with spaces and `$...$` for LaTeX code.
- `:help`: view available commands
- `:quit`: quit the application
- `:back`: back to chat menu for selecting chat
- `:reply`: reply mode to select and reply to messages
- `:scrollup`or `:k`: scroll up in chat messages
- `:scrolldown` or `:j`: scroll down in chat messages
- `:schedule <time> "<message>"`: schedule a message, see [scheduling messages](#scheduling-messages)
- `:delay <seconds> "<message>"`: delay sending the message, similar as schedule
- `:cancel`: cancel the latest scheduled/delayed message
- `:upload`: upload media using the file navigator
- `:upload <path?>`: upload media (photo or video) directly from path
- `:config <key?>=<value?>`: an in-chat version of `instagram config`
- `:view <index>`: view and download media at index or open URL directly in browser
- `:latex $<expr>$`: render and send LaTeX code as image, see [latex](#latex)
- `:summarize <depth?>`: generate a summary of chat history using an LLM, see [chat summarization](#chat-summarization)
### Emoji
Text with emoji syntax will be rendered as emoji. For example,
`This is an emoji :thumbsup:`
will be rendered as
`This is an emoji 👍`
> [!TIP]
> This does not have to be an exact match with the emoji name. For example, `:thumbsup:` can also be written as `:thumbs_up:`.
### LaTeX
We support LaTeX rendering and sending as images in the chat. For example,
`:latex $\frac{a}{b} + c = d$`
```bash
:latex $\left( \begin{bmatrix} a & b \\ c & d \end{bmatrix} \cdot \begin{bmatrix} e & f \\ g & h \end{bmatrix} \right) + \begin{bmatrix} i & j \\ k & l \end{bmatrix}^{-1} \times \left( \int_0^1 x^2 \, dx \right) + \begin{bmatrix} \sin(\theta) & \cos(\theta) \\ \tan(\phi) & \ln(\psi) \end{bmatrix}$
```
Please note that the LaTeX code **_MUST_** be enclosed in `$` symbols.
You can choose to render with [online API](https://latex.codecogs.com) (default) or local LaTeX installation such as TeX Live, MiKTeX, etc. You can set the rendering method with `instagram config --set latex_rendering_method <online|local>`.
### Chat Summarization
You can generate a summary of the chat history using the `:summarize` command. This will create a concise summary of the conversation, highlighting key points and important information.
Local LLMs are first-class citizens here, allowing for maximum privacy and flexibility. All you need is a local LLM inferencing server like [Ollama](https://ollama.com/), [LM Studio](https://lmstudio.ai/). You will need to specify `llm.endpoint` (OpenAI-compatible) and `llm.model` in the config. For example, for Ollama, this would likely be `http://localhost:11434/v1/`.
> [!IMPORTANT]
> You are responsible for setting up the LLM server and ensuring that you have the right model pulled. You can configure the endpoint and model using the `instagram config` command, e.g. `instagram config --set llm.endpoint <URL>` and `instagram config --set llm.model <MODEL_NAME>`.
Once inside a chat conversation, you can summarize the chat history using:
```plaintext
:summarize
```
This will process all messages fetched in the current chat.
To limit (or expand) the summarization to the `n` most recent messages:
```plaintext
:summarize n
```
You can also turn on streaming mode with `instagram config --set llm.stream True` to see the summary being generated in real-time.
> [!TIP]
> If you don't mind giving your data to AI companies, you may set the `llama.endpoint` and `llm.model` configs to a remote endpoint, e.g. `https://api.openai.com/v1/`, `gpt-5`.
### Scheduling Messages
You can schedule messages to be sent at a later time. The syntax is as follows:
```bash
:schedule <Optional[Y-m-d] HH:MM> "<message>"
```
If the date is not provided, the message will be scheduled for the current day. Input format must be either YYYY-MM-DD HH:MM or HH:MM. **The time must be in 24-hour format, otherwise you might run into warnings for scheduling messages in the past.**
> [!IMPORTANT]
> If you exit the app, the scheduled messages will not be sent but will be restored when you open the app again. You will be prompted by a notification to decide whether to send the scheduled messages or not. We might include system background service in the future to send scheduled messages even when the app is closed.
## Contributing
We welcome contributors! Please see the comprehensive [CONTRIBUTING.md](CONTRIBUTING.md) file for details on how to get started, create issues, and submit pull requests.
Raw data
{
"_id": null,
"home_page": null,
"name": "instagram-cli",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "instagram, cli, terminal, social-media, tui, command-line, instagram-api",
"author": null,
"author_email": "Jet Chiang <jetjiang.ez@gmail.com>, James Zheng <endernoke@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/f2/bd/42f4a88b7b917d06bb8c34d17c929a71e12fcadcc04958d4c46717a96df6/instagram_cli-1.4.1.tar.gz",
"platform": null,
"description": "# Instagram CLI\n\nThe ultimate weapon against brainrot. Shown experimentally to effectively reduce screentime.\n\n\n[](https://pepy.tech/projects/instagram-cli)\n\n[](https://github.com/supreme-gg-gg/instagram-cli/blob/main/LICENSE)\n[](https://github.com/supreme-gg-gg/instagram-cli/issues)\n\n<!--  -->\n<!--  -->\n\nhttps://github.com/user-attachments/assets/e9206e14-8141-49b2-8e2c-17c76402e3cb\n\n> [!WARNING]\n> 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.\n\n## What does it do?\n\n- We transform Instagram from a brainrot hell into productivity tool\n- We allow you to focus on meaningful conversations\n- We celebrate the art and simplicity of terminal UI\n- We extend Instagram with powerful plugins like latex, chat summarisation\n\n> [!TIP]\n> Use Instagram with 100% keyboard control - no mouse clicks or touchscreen taps needed! Perfect for developers and Linux users who love staying on the keyboard \ud83e\udd23\n\n### Need a break and have some brainrot?\n\nWant to watch Instagram Reels right from your terminal? Check out [reels-cli](https://github.com/notMarkMP1/reels-cli). It\u2019s a great way to enjoy some light entertainment without leaving your keyboard. (Not affiliated and not maintained by us, but highly recommended for terminal fans.)\n\n## Installation\n\nThe simplest way to get started is to install the package from PyPI if you have Python installed:\n\n```bash\npip install instagram-cli\n```\n\nIf you do not have Python installed, you can download and install it from the [official website](https://www.python.org/downloads/).\n\n### Installation from Source\n\n```bash\ngit clone https://github.com/supreme-gg-gg/instagram-cli.git\ncd instagram-cli\npip install .\n```\n\n### Pre-built Executables\n\n> [!CAUTION]\n> This option is **not recommended** unless the other methods do not work for you.\n\nWe no longer provide pre-built executables. If you want to run the application in an environment without Python, you can build the executable yourself with `pyinstaller`. We recommend using the `instagram-cli.spec` file we provided.\n\n```bash\npyinstaller --onedir instagram-cli.spec\n```\n\nThis will generate the executable in the `dist/` directory.\n\n```bash\n./instagram-cli [OPTIONS] command [ARGS] # for macOS and Linux\ninstagram-cli.exe [OPTIONS] command [ARGS] # for Windows\n```\n\n> [!CAUTION]\n> Starting from Version 1.3, Windows support will be discontinued due to incompatibilities between the `curses` and `windows-curses` libraries. While the application may still work on Windows, we will no longer be testing or maintaining Windows-specific functionality. We recommend using WSL (Windows Subsystem for Linux) or Docker for Windows users.\n\n## Commands\n\nThe following commands will be available after installing the package:\n\n```bash\ninstagram # display title art\ninstagram --help # view available commands\n\n# Authentication\ninstagram auth login -u # login with username and password\ninstagram auth logout # logout and removes session\n\n# Chat Features\ninstagram chat start # start chat interface\ninstagram chat search -u <username> # search and open chat by username\ninstagram chat search -t <text> # search and open chat by chat title\n\n# Utility Commands\ninstagram notify # view notifications (inbox, followers, mentions)\ninstagram schedule ls # view scheduled messages\ninstagram schedule cancel <index> # cancel scheduled message\ninstagram stats --days <last_n_days> # view usage analytics (default: 14 days)\ninstagram config --get --set --edit # manage custom configuration\ninstagram cleanup -t # cleanup media and session cache files\n```\n\n## Chat\n\nThe chat interface is the main feature of this package. It allows you to interact with your Instagram chats in a terminal-based interface.\n\nIn the chat list page, use arrow keys (or 'j', 'k') + Enter to select a chat. You can also search for user by username using @user_name + Enter.\n\n> [!NOTE]\n> All searches in the package uses a custom fuzzy matching based on ratcliff/obershelp similarity algorithm. This means chat search and emoji search will be more flexible and forgiving.\n\nAfter entering the chat page, you can type messages as usual and send them with Enter. You can also use chat commands to supercharge your chat experience.\n\n> [!TIP]\n> Press Enter in the middle of a message to insert a line break, and at the very end to send it.\n\n### Chat Commands\n\nAll chat commands have the following syntax:\n\n```bash\n:command <args> <long-args>\n```\n\n> [!IMPORTANT]\n> Long arguments should have special enclosures such as `\"...\"` for strings with spaces and `$...$` for LaTeX code.\n\n- `:help`: view available commands\n- `:quit`: quit the application\n- `:back`: back to chat menu for selecting chat\n- `:reply`: reply mode to select and reply to messages\n- `:scrollup`or `:k`: scroll up in chat messages\n- `:scrolldown` or `:j`: scroll down in chat messages\n- `:schedule <time> \"<message>\"`: schedule a message, see [scheduling messages](#scheduling-messages)\n- `:delay <seconds> \"<message>\"`: delay sending the message, similar as schedule\n- `:cancel`: cancel the latest scheduled/delayed message\n- `:upload`: upload media using the file navigator\n- `:upload <path?>`: upload media (photo or video) directly from path\n- `:config <key?>=<value?>`: an in-chat version of `instagram config`\n- `:view <index>`: view and download media at index or open URL directly in browser\n- `:latex $<expr>$`: render and send LaTeX code as image, see [latex](#latex)\n- `:summarize <depth?>`: generate a summary of chat history using an LLM, see [chat summarization](#chat-summarization)\n\n### Emoji\n\nText with emoji syntax will be rendered as emoji. For example,\n\n`This is an emoji :thumbsup:`\n\nwill be rendered as\n\n`This is an emoji \ud83d\udc4d`\n\n> [!TIP]\n> This does not have to be an exact match with the emoji name. For example, `:thumbsup:` can also be written as `:thumbs_up:`.\n\n### LaTeX\n\nWe support LaTeX rendering and sending as images in the chat. For example,\n\n`:latex $\\frac{a}{b} + c = d$`\n\n\n\n```bash\n:latex $\\left( \\begin{bmatrix} a & b \\\\ c & d \\end{bmatrix} \\cdot \\begin{bmatrix} e & f \\\\ g & h \\end{bmatrix} \\right) + \\begin{bmatrix} i & j \\\\ k & l \\end{bmatrix}^{-1} \\times \\left( \\int_0^1 x^2 \\, dx \\right) + \\begin{bmatrix} \\sin(\\theta) & \\cos(\\theta) \\\\ \\tan(\\phi) & \\ln(\\psi) \\end{bmatrix}$\n```\n\n\n\nPlease note that the LaTeX code **_MUST_** be enclosed in `$` symbols.\n\nYou can choose to render with [online API](https://latex.codecogs.com) (default) or local LaTeX installation such as TeX Live, MiKTeX, etc. You can set the rendering method with `instagram config --set latex_rendering_method <online|local>`.\n\n### Chat Summarization\n\nYou can generate a summary of the chat history using the `:summarize` command. This will create a concise summary of the conversation, highlighting key points and important information.\n\nLocal LLMs are first-class citizens here, allowing for maximum privacy and flexibility. All you need is a local LLM inferencing server like [Ollama](https://ollama.com/), [LM Studio](https://lmstudio.ai/). You will need to specify `llm.endpoint` (OpenAI-compatible) and `llm.model` in the config. For example, for Ollama, this would likely be `http://localhost:11434/v1/`.\n\n> [!IMPORTANT]\n> You are responsible for setting up the LLM server and ensuring that you have the right model pulled. You can configure the endpoint and model using the `instagram config` command, e.g. `instagram config --set llm.endpoint <URL>` and `instagram config --set llm.model <MODEL_NAME>`.\n\nOnce inside a chat conversation, you can summarize the chat history using:\n\n```plaintext\n:summarize\n```\n\nThis will process all messages fetched in the current chat.\n\nTo limit (or expand) the summarization to the `n` most recent messages:\n\n```plaintext\n:summarize n\n```\n\nYou can also turn on streaming mode with `instagram config --set llm.stream True` to see the summary being generated in real-time.\n\n> [!TIP]\n> If you don't mind giving your data to AI companies, you may set the `llama.endpoint` and `llm.model` configs to a remote endpoint, e.g. `https://api.openai.com/v1/`, `gpt-5`.\n\n### Scheduling Messages\n\nYou can schedule messages to be sent at a later time. The syntax is as follows:\n\n```bash\n:schedule <Optional[Y-m-d] HH:MM> \"<message>\"\n```\n\nIf the date is not provided, the message will be scheduled for the current day. Input format must be either YYYY-MM-DD HH:MM or HH:MM. **The time must be in 24-hour format, otherwise you might run into warnings for scheduling messages in the past.**\n\n> [!IMPORTANT]\n> If you exit the app, the scheduled messages will not be sent but will be restored when you open the app again. You will be prompted by a notification to decide whether to send the scheduled messages or not. We might include system background service in the future to send scheduled messages even when the app is closed.\n\n## Contributing\n\nWe welcome contributors! Please see the comprehensive [CONTRIBUTING.md](CONTRIBUTING.md) file for details on how to get started, create issues, and submit pull requests.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Use Instagram in the terminal, the end of brainrot is here",
"version": "1.4.1",
"project_urls": {
"Homepage": "https://github.com/supreme-gg-gg/instagram-cli"
},
"split_keywords": [
"instagram",
" cli",
" terminal",
" social-media",
" tui",
" command-line",
" instagram-api"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "a309a1836366f8ad2b7bcff3ab688380408f5d553df54b159e0dc8ce9132b3b3",
"md5": "d2740dd7af57979fa1106fa72a035694",
"sha256": "49bc6f10053fb982d876bb918556578e9a6999c4c4407db6fca5e4e0a7fa9596"
},
"downloads": -1,
"filename": "instagram_cli-1.4.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "d2740dd7af57979fa1106fa72a035694",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 63353,
"upload_time": "2025-08-28T15:23:45",
"upload_time_iso_8601": "2025-08-28T15:23:45.195812Z",
"url": "https://files.pythonhosted.org/packages/a3/09/a1836366f8ad2b7bcff3ab688380408f5d553df54b159e0dc8ce9132b3b3/instagram_cli-1.4.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "f2bd42f4a88b7b917d06bb8c34d17c929a71e12fcadcc04958d4c46717a96df6",
"md5": "7d3a939f0413eee8554485b46ac4ba0a",
"sha256": "507c89cec497eb093e7d8908e88ac93f6db7a9f9e1974658e3959caf8f395a16"
},
"downloads": -1,
"filename": "instagram_cli-1.4.1.tar.gz",
"has_sig": false,
"md5_digest": "7d3a939f0413eee8554485b46ac4ba0a",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 59262,
"upload_time": "2025-08-28T15:23:47",
"upload_time_iso_8601": "2025-08-28T15:23:47.261351Z",
"url": "https://files.pythonhosted.org/packages/f2/bd/42f4a88b7b917d06bb8c34d17c929a71e12fcadcc04958d4c46717a96df6/instagram_cli-1.4.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-28 15:23:47",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "supreme-gg-gg",
"github_project": "instagram-cli",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "instagram-cli"
}
JSON
