telerust

Telegram in your terminal.

A full-screen Telegram client for your terminal, written in Rust. Scroll through your chats, search as you type and read conversations in bubbles, with smooth animations all the way. Read-only: telerust never sends messages.

telerust tui

Download for macOS How to install

Version 0.1.0 for Apple Silicon, macOS 11 or later. 4.4 MiB archive.

tty1 telerust tui
Recording of telerust tui: the chat list, opening the chat with John, which marks his three new messages as read, then searching for Night Shift and opening the group.

Your chats, full-screen

Run telerust tui: chats on the left, the conversation on the right. No browser, no Electron, no setup beyond the QR login.

  • Chats at a glance

    Avatars, unread counters and a search that filters as you type, then checks every chat on the server.

  • Conversations, not logs

    Bubbles, day separators, an unread divider, replies, albums, voice notes, links and @mentions.

  • Smooth, then silent

    Fades and glides at 30 fps while something moves. At rest it draws nothing and uses no CPU.

  • Keyboard first

    Arrows or j k, Enter to open, / to search, Tab between panes. Click and scroll with the mouse, too.

  • Any terminal

    True color where your terminal has it, a 256-color palette where it doesn't. Over SSH, in tmux, resized on the fly.

  • Honest read receipts

    Scrolling the list marks nothing as read. Opening a chat does, just like in Telegram.

↑ ↓
pick a chat, scroll a chat
Enter
open the chat
/
search by name or @username
Tab
switch between list and chat
PgUp PgDn
page through history
r
refresh
?
all keys
q
quit

Commands

Prefer scripts? Every command except tui prints JSON to stdout, so you can pipe the result straight into jq or your own scripts. Add --pretty when you want to read it yourself.

tty1 telerust login

~ $ telerust login

Open Telegram on your phone → Settings → Devices → Link Desktop Device.

Scan the QR code below. It refreshes automatically; Ctrl-C cancels.

Telegram two-step verification password:

{"authorized":true,"user_id":"5120334771","name":"Jane","session_file":"/Users/jane/Library/Application Support/telerust/telegram.session"}

~ $ telerust read 'John' --unread | jq -c '.messages[] | {date, text}'

{"date":"2026-10-10T19:41:07Z","text":"where are you?"}

{"date":"2026-10-10T19:38:52Z","text":"grab a charger, signal only works near the neon sign"}

{"date":"2026-10-10T19:30:15Z","text":"11pm at the old depot, don't be late"}

~ $

Example session: QR login with a two-step verification password, then unread messages piped through jq.
tui

Opens a full-screen view in the terminal: your chats on the left, the open chat on the right. Press / to search, scroll up for older messages, ? for keys. Opening a chat marks it as read, just like in Telegram.

$ telerust tui
login

Log in with a QR code: scan it with Telegram on your phone and the session is saved on this computer. Two-step verification is supported.

--qr-file login.svg
also save the QR code as an image
$ telerust login
status

Shows whether the session is alive and which account is logged in.

$ telerust status --pretty
chats

Finds chats by name or @username. Case-insensitive, works with any alphabet.

$ telerust chats -q 'john'
read

Reads chat history, newest messages first. Pick the chat by its ID from chats, by @username or by name.

-n, --count 100
the last 100 messages
--unread
unread incoming messages only
--days 7
the last 7 days
--since 2026-09-01
from a date on
--until 2026-10-01
up to a date, not including it

Filters combine. Large results come in pages: pass next_cursor back with --cursor until you get "complete": true.

$ telerust read 'John' --unread --count 50
media

Downloads one attachment by its asset_id from the history: a photo, voice message, video or document. The file streams into a local cache with a 100 MiB limit; raise it to 2 GiB with --max-bytes.

$ telerust media 'asset.eyJ2IjoxLCJjaGF0Ijoi…'

For every command: --pretty prints indented JSON, --data-dir sets your own directory for the session and cache.

Read-only

telerust reads your chats. It never sends messages.

  • 0

    messages sent

  • 0

    files downloaded unasked

  • Messages are never sent: there is no command for it.
  • Browsing the chat list marks nothing as read; opening a chat in tui does, as in Telegram.
  • Attachments never download on their own: history carries metadata, files come only with media.
  • No background sync of your history and no indexing of your chats.
  • The session lives in a private directory with 0700/0600 permissions; only one process can use it at a time.
  • Outside the tui screen, stdout carries only JSON, errors included. QR codes and logs go to stderr.
  • Revoke access anytime in Telegram: Settings → Devices.

Install

You need a Mac with Apple Silicon and Telegram on your phone.

  1. [1/4]Download and unpack

    Download for macOS
    Archive
    telerust-0.1.0-aarch64-apple-darwin.tar.gz, 4.4 MiB
    SHA-256
    7c0abcdd00030e23abfde02d9ed3c357c8118997facc30b6aad4b57373156bec

    Downloaded it in a browser and macOS won't run it? Clear the quarantine flag: xattr -d com.apple.quarantine telerust.

    On Linux or an Intel Mac, build from source with Rust 1.88+: cargo build --release --locked.

    curl -fsSL downloads/telerust-0.1.0-aarch64-apple-darwin.tar.gz | tar -xz
cd telerust-0.1.0-aarch64-apple-darwin
./telerust --version
telerust 0.1.0

  2. [2/4]Get API keys

    telerust signs in to your regular account, not a bot, so it needs an api_id and api_hash. Get them at my.telegram.org under API development tools.

    Instead of export, you can put these lines in a .env file in the directory you run telerust from, and lock it down with chmod 600 .env.

    export TELEGRAM_API_ID=123456
export TELEGRAM_API_HASH=your_api_hash

  3. [3/4]Log in with QR

    A QR code appears in your terminal. On your phone, open Telegram → Settings → Devices → Link Desktop Device and point the camera at it. If two-step verification is on, telerust asks for your password; what you type stays hidden.

    The session is stored in ~/Library/Application Support/telerust. Don't share that directory.

    ./telerust login

  4. [4/4]Open your chats

    Start the full-screen client. To script instead, find a chat and read it by count, unread status or date range.

    ./telerust tui
./telerust chats -q 'john' --pretty
./telerust read 'John' --unread --pretty
./telerust read 'John' --since 2026-10-01 | jq -r '.messages[].text'