tuigram-cli 0.9.0

Telegram in your terminal: a fast, vim-style Telegram client built on TDLib
tuigram-cli-0.9.0 is not a library.

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.

Release crates.io License: MIT

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.
  • Send stickers. Tab while writing opens your recent and favorite stickers and the sets you added, and / finds more by emoji or word.
  • 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, ✓ / ✓✓ when yours are sent and read, 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. Catppuccin, Tokyo Night, Dracula, Gruvbox, Nord and Rosé Pine themes or your own, 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:

Computer File
Mac with Apple silicon (M1 or later) tuigram-aarch64-apple-darwin.tar.gz
Mac with Intel tuigram-x86_64-apple-darwin.tar.gz
Linux, x86_64 tuigram-x86_64-unknown-linux-gnu.tar.gz
Linux, ARM64 tuigram-aarch64-unknown-linux-gnu.tar.gz
Windows, x86_64 tuigram-x86_64-pc-windows-msvc.zip
Windows, ARM64 tuigram-aarch64-pc-windows-msvc.zip
  • 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:

Key Action
j / k Move down / up
gg / G Jump to top / bottom
Ctrl-d / Ctrl-u Half a page down / up
Enter / l Open a chat, or the file or link in a message (files that could run code, and links that hide their address, ask first: y opens)
h / Esc Back to the chat list. To have the list on the right, tick On the right side of the window in ? > Settings; h and l then swap, to follow the screen
i Write a message: Enter sends, Alt-Enter or Ctrl-j starts a new line. You stay in Insert mode to write the next one, unless you tick Back to Normal mode after sending in ? > Settings
Tab While writing: stickers. h/j/k/l pick one, H / L switch between Recent, Favorites and your sets, / finds stickers by emoji or word, Enter sends
y Copy the selected message: its text, a link, or the photo or file
r Reply to the selected message (Esc twice cancels the reply)
e Edit your message: Enter saves, Esc twice cancels
R React to the selected message: pick an emoji, or type / and its name (heart, +1); Enter on one of yours takes it back
X Take back all your reactions to the selected message, without the popup
gd / Ctrl-o Go to the message a reply answers / back to the reply
d Delete the selected message, for everyone or just you (asks first)
/ Search chat names, or messages in the open chat
n / N Next older / newer match
H Highlight a chat
Ctrl-r Resize the panes: h / l move the line between them left / right, = puts it back as at first, Enter keeps it (also next time), Esc cancels
: Run a command, typed in full: :logout logs out of Telegram on this computer
? Every shortcut, plus settings and themes
q Quit

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. Where the terminal can't say when you switch away (tmux without focus-events, GNU screen), tuigram counts you as away after a minute without a key press: new messages then notify, and aren't marked as read until you're back. Where it can, messages stop being marked as read after five minutes without a key press, in case the screen was left on. Time the computer spent asleep counts as time away.

To turn them off or on, press ?, go to Settings, and press Space or Enter on Notifications; it's saved at once. 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.

Themes

Press ?, go to Settings, and pick a theme at the bottom of the list: Catppuccin (Latte, Frappé, Macchiato, Mocha), Tokyo Night, Dracula, Gruvbox, Nord or Rosé Pine. It's saved at once.

To make your own, put a .toml file in the themes folder inside your data folder, then pick it in the same list. tuigram reads the folder again each time ? opens, so you can edit a theme and see the change by pressing ?. A theme can start from another one and change only a few colors:

# themes/my-mocha.toml
name = "My Mocha"    # what the list shows; the file name otherwise
inherits = "mocha"   # a built-in theme's file name, or one of yours

[palette]
blue = "#7aa2f7"     # your bubbles, unread counts and the rest follow

[colors]
bg = "reset"         # let the terminal's own background show through
search = "orange"

Sixteen [palette] colors make a whole theme: bg, bg_alt, surface, overlay, comment, subtext, fg, red, orange, yellow, green, cyan, blue, purple, pink and accent. To start one, copy a built-in theme; mocha.toml says what each color paints. A file named like a built-in theme, such as mocha.toml, replaces it, and inherits = "mocha" in it then means the original.

[colors] sets single things, to a palette color, "#rrggbb", or "reset" for the terminal's own color:

Name What it paints Unless set
bg, fg Background and text bg, fg
subtle Chat previews, photo placeholders subtext
muted Key hints, dates, placeholders comment
border Borders of the pane not in use overlay
accent The pane in use, cursors, popups accent
selection The selected row surface
popup_bg Popups bg_alt
primary Unread counts, NORMAL, Saved Messages blue
highlighted Chats you highlighted with H orange
insert, command, search INSERT, COMMAND and SEARCH; search matches green, purple, yellow
error Errors, messages that failed to send, deleting red
warning "Are you sure" popups, things still in progress yellow
success Notes that something worked green
reply, edit The bar over the composer, and the message it's about cyan, orange
activity "typing…" blue
attach Files waiting to be sent blue
own_bubble, other_bubble Your messages, and other people's bg tinted blue, surface
own_meta, other_meta The time and ✓ on them fg mixed with blue, subtext
own_reaction, other_reaction Reactions on them A shade off the bubble
your_reaction Reactions you added blue
names Seven colors for people's names in groups red, orange, purple, green, cyan, blue, pink
qr_dark, qr_light The QR code for logging in Near black, near white

If a theme can't be used, tuigram says why in the status bar and uses Catppuccin Mocha until the file is fixed.

Your data

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

OS Location
macOS ~/Library/Application Support/tuigram
Linux ~/.local/share/tuigram
Windows %LOCALAPPDATA%\tuigram

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

Environment variables:

Variable Use
TG_DATA_DIR Keep the data folder somewhere else
TG_API_ID, TG_API_HASH Use your own API key instead of the saved or built-in one

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). Only development builds (cargo run) read .env: an installed tuigram ignores it, so a .env in a folder you cloned can't choose where your session is kept.

Built with

License

MIT