@i7m/instagram-cli

Instagram CLI

Welcome to the TypeScript client of the Instagram CLI project. The Typescript client is a successor to the original Python client, built with a modern React-based UI using Ink, with features like image rendering in terminal, checking feed, and using Instagram's native MQTT protocol for messaging to significantly reduce latency and account flags.

Full documentation with demo video is on our GitHub.

[!NOTE] Typescript client is current in Public Beta. While we have tested it extensively, there may still be some bugs. Please report them on our issues page.

Key Features

• Full support for Windows, Linux, and macOS, with modern React-based UI
• Developer-friendly shortcuts, viewing feed and chatting, in-terminal image rendering
• Leverages realtime MQTT-based protocol used by Instagram app for instant notifications and chat
• Highly performant and much faster than your GUI browser or touchscreen app
• Works well in all terminal emulators, including VSCode Integrated Terminal

Usage

Install the package globally:

npm install -g @i7m/instagram-cli

Commands

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

# Core features
instagram-cli chat                             # start chat interface
instagram-cli feed                             # view posts from people you follow
instagram-cli notify                           # view notifications (inbox, followers, mentions)

# Modify configuration
instagram-cli config                           # view and modify configuration

Note that the parent command is instagram-cli instead of instagram to avoid conflict with the Python client if you have both installed.

Chat Commands

You can navigate all interface with 100% keyboard support. When messaging, the following commands are available:

:help
:select # select first before unsend or react
:react <emoji>
:unsend
:upload <path-to-image-or-video>
: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.

Configuration

You can view and modify configuration with instagram-cli config. The configuration file is located at ~/.instagram-cli/config.ts.yaml. The following are common configuration options:

Key	Type	Default	Description
image.protocol	string	"halfblock"	Protocol for rendering images. Options: "ascii", "halfblock", "braille", "kitty", "iterm2", "sixel", or "".
feed.feedType	string	"list"	Layout of feed display. Options: "timeline", "list", "".

[!NOTE] We automatically select the best image protocol based on your terminal. If you experience issues with image rendering, try changing the image.protocol setting. Make sure this is supported by your terminal (e.g. kitty protocol won't work in iTerm2).

Design philosophy

• Simplicity, a clean interface with minimal distractions

• Absolutely no brainrot, no ads, no attention traps

• Convenience, quick access to essential features, open anywhere even in VSCode Integrated Terminals, super fast startup (no browser)

• Developer-first, open source, extensible, and keyboard-first

Contributing

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.

Commitment to Open Source

Maintainers behind instagram-cli are committed to contributing to the open source community behind frameworks that empower terminal applications, such as ink. This includes direct contributions and our sister projects -- Ink Picture, Ink-native image component and Wax, Ink routing framework.