tuigram

Telegram at the speed of your keyboard.

A terminal Telegram client (TUI) with vim keys, inline photos, reactions and search across your whole history. Written in Rust on TDLib, the library behind Telegram's own apps.

Download for macOS, Linux or Windows and log in. Nothing to set up. With Rust: cargo binstall tuigram-cli gets the same ready-made app.

Why tuigram

• Your real account, not a bot. Log in by scanning a QR code with Telegram on your phone, or with your phone number and the code Telegram sends, plus your two-step password if you have one, just like the official apps.
• Vim all the way. Normal mode to move around (j/k, gg/G, Ctrl-d/Ctrl-u), i to write, Esc to stop. Your hands never leave the keyboard.
• Photos and stickers, inline. Real images in kitty, Ghostty, WezTerm and iTerm2, and block-character previews in any other terminal.
• React with emoji. R opens the emoji the chat allows, and / finds one by name (heart, fire, +1). X takes yours back.
• Search everything. / in the chat list filters chats as you type. / inside a chat searches its entire history, and n/N jump between matches, highlighted where they appear.
• Feels like Telegram. Message bubbles with yours on the right, sender names in color, reactions under them, date separators, "typing…" while someone writes to you, and unread chats on top.
• Open anything. Press Enter on a photo, video, file or link to open it in your default app.
• Send photos and files. Drop them on the window, paste a screenshot with p, or type a path with a (Tab completes it). What you write goes with them as the caption, and several photos go as one album.
• Notifications. New messages pop up as system notifications while you're in another window, and the window title counts your unread chats. Telegram's mute settings apply.
• Make it yours. Four Catppuccin themes with live preview, and highlights that make your important chats stand out.
• Private by design. tuigram talks only to Telegram. No telemetry, no accounts and no servers in between. Your session stays on your machine, and read receipts go out only for messages you've actually had in front of you.
• Careful with what others send. A file that could run a program, or a link whose text hides where it really goes, asks before opening.

Get started

There are two ways to install tuigram:

• Download it (or cargo binstall tuigram-cli). Ready-made apps come with tuigram's own Telegram API key, so you just log in.
• Build it from source with cargo install. You bring your own API key, which takes two minutes on Telegram's site.

To look around first, tuigram --demo shows made-up chats without logging in: 1–5 switch scenes, t changes the theme, q quits.

Download (recommended)

1. Install. If you have Rust and cargo-binstall, that's one command, on any system:

cargo binstall tuigram-cli

Otherwise, on macOS or Linux, paste this into a terminal. It puts tuigram in ~/.local/bin:

mkdir -p ~/.local/bin
curl -fsSL https://github.com/erictran308/tuigram/releases/latest/download/tuigram-aarch64-apple-darwin.tar.gz | tar xz -C ~/.local/bin tuigram

Swap the file name for your computer's:

• Windows: download the .zip, unzip it, and run tuigram.exe from Windows Terminal.
• Linux: needs Ubuntu 24.04, Debian 13, Fedora 40 or newer, plus libc++: sudo apt install libc++1 (Fedora: sudo dnf install libcxx).
• macOS: if you downloaded the file in a browser instead, macOS blocks the app. Run xattr -d com.apple.quarantine tuigram once to allow it.

If tuigram isn't found afterwards, add ~/.local/bin to your PATH. Each file comes with a signed record of the commit it was built from; to check one, run gh attestation verify <file> --repo erictran308/tuigram.

2. Run it.

tuigram

3. Log in. Type your phone number, or press Tab and scan the QR code with Telegram on your phone. That's it: next time, tuigram takes you straight to your chats.

Build from source

1. Install. You need Rust. cargo install always builds from source (unlike cargo binstall above). The first build downloads TDLib and takes a few minutes. On Linux, install libc++ first (sudo apt install libc++-dev libc++abi-dev).

cargo install tuigram-cli

Works on Linux, macOS and Windows, on x86_64 and ARM64.

2. Get your API key (once). Builds from source have no API key: their code is public, and a key published there would get blocked by Telegram for everyone. Sign in at my.telegram.org, open API development tools, and create an app with any name.

3. Run it. Type tuigram, paste your api_id and api_hash when asked, then log in with your phone number or a QR code. tuigram saves the key, so you only do this once.

Using your own API key

The downloaded app can use your own key too, so your access never depends on tuigram's. Set TG_API_ID and TG_API_HASH in your environment, or add the key to settings.toml in your data folder:

[api_keys]
id = 1234567
hash = "0123456789abcdef0123456789abcdef"

tuigram uses the first key it finds, in this order: the environment, settings.toml, then the built-in key. If Telegram ever stops accepting the built-in key, tuigram asks for your own instead.

Keys

The status bar always shows the keys for where you are. The essentials:

Notifications

While tuigram's window is in the background, new messages show as notifications from your terminal: messages that arrive together become one, and a busy chat stays quiet for half a minute after each. Chats you muted in Telegram stay silent.

They work in Ghostty, kitty, WezTerm, iTerm2, foot and Konsole, also over SSH. In Windows Terminal, turn on compatibility.allowOSC777 in its settings. Other terminals ring the bell instead. In tmux, add set -g allow-passthrough on and set -g focus-events on to ~/.tmux.conf.

To turn them off or on, press ?, go to Settings, and press Space on Notifications, then Enter to save. To pick how they're sent, set notifications in settings.toml (in your data folder) to "bell", "osc9", "osc777" or "osc99"; the default "auto" picks for your terminal.

Like Telegram Desktop, tuigram shows you as online while its window is focused and you've pressed a key in the last minute, so notifications arrive right away instead of waiting to see if you read them on your phone.

Your data

Everything lives in one folder on your machine (tuigram --help prints its path):

It holds your login session, API keys, downloaded files and settings. Deleting it removes your session from this computer. To end the session completely, go to Settings → Devices in another Telegram app.

Environment variables (they can also go in a .env file in the current directory):

Development

git clone https://github.com/erictran308/tuigram && cd tuigram
cargo run       # uses the same data folder as the installed app, or TG_DATA_DIR
cargo test

Copy .env.example to .env to keep a separate development session (for example TG_DATA_DIR=./.tdlib).

Built with

• TDLib through tdlib-rs
• ratatui and ratatui-image
• Catppuccin colors

License

MIT