Termgram

A keyboard-first Telegram client for the terminal, built with Rust, Grammers and Ratatui. Read direct messages and groups, navigate with Vim-style keys, and keep your configuration in Lua.

Termgram opens cached conversations immediately and synchronizes in the background. It supports Telegram folders, local regex search, per-chat colors, inline media previews, and file-manager reveal. This is an unofficial client; broadcast channels and secret chats are outside its current scope.

English guide · 简体中文指南

Documentation follows the source revision you are reading. Features on an open PR branch may not yet be in the latest release.

Get started

Homebrew (macOS / Linux):

brew tap iebb/termgram https://github.com/iebb/termgram.git
brew install iebb/termgram/termgram

This installs the prebuilt stable release for your platform as the tg command with SHA-256 verification. For the latest published prerelease instead:

brew install iebb/termgram/termgram-pre

On macOS, the prerelease is also available as the cask brew install iebb/termgram/termgram@pre, which installs the same tg executable and conflicts with the formulae.

The Homebrew formula lives in this repository. No separate tap repository or Rust compiler is needed. Update with brew update followed by brew upgrade iebb/termgram/termgram; uninstall with brew uninstall termgram. If you previously installed tg manually, check which tg: a copy in ~/bin or ~/.local/bin may take precedence in PATH. termgram and termgram-pre conflict because both install the tg executable. termgram-pre is regenerated automatically after each prerelease; upgrade it with brew upgrade termgram-pre instead of tg update.

Scoop (64-bit / ARM64 Windows):

scoop bucket add termgram https://github.com/iebb/termgram.git
scoop install termgram

The Scoop manifest lives in this repository and installs the prebuilt stable release for your Windows architecture as the tg command with SHA-256 verification. No separate bucket repository or Rust compiler is needed. Update with scoop update followed by scoop update termgram; uninstall with scoop uninstall termgram.

Standalone installer (Linux / macOS):

curl --proto '=https' --tlsv1.2 -sSfL \
  https://github.com/iebb/termgram/releases/latest/download/install.sh | bash

It verifies the release checksums and installs the tg executable into ~/.local/bin by default.

Windows PowerShell:

$installer = Invoke-RestMethod 'https://github.com/iebb/termgram/releases/latest/download/install.ps1'
& ([scriptblock]::Create([string]$installer))

It verifies the release checksums and installs the tg executable (tg.exe) under %LOCALAPPDATA%\Programs\Termgram\bin by default.

From source on any supported platform, with Rust 1.98.0 and native build tools:

cargo +1.98.0 install --locked --git https://github.com/iebb/termgram --bin tg termgram

Run tg, sign in with your phone or press Tab for QR login. Open a chat with Enter, press i to compose, and ? for help. Repeat the Cargo command to update a source install; use tg update for standalone release binaries. Use brew upgrade iebb/termgram/termgram (or termgram-pre for prereleases) for Homebrew installations and scoop update termgram for Scoop installations so the package manager can track the installed version.

Releases support Linux x86_64/ARM64, macOS Intel/Apple silicon, and Windows x64/ARM64. See installation and source builds for prerequisites, installer options, and Telegram API credentials.

Development

Rust 1.98 is pinned in rust-toolchain.toml. Create Telegram application credentials at my.telegram.org/apps, copy .env.example to .env, and fill in your API ID and hash.

cargo run --release
cargo fmt --all -- --check
cargo clippy --locked --all-targets --all-features -- -D warnings
cargo test --locked --all-targets --all-features

See development and architecture, engineering principles, and upstream provenance. The Wiki source is reviewed alongside code changes and provides English and Simplified Chinese pages. Local working plans live in the Git-ignored dev-notes/ directory.