README
¶
tele
_ _
| |_ ___ | | ___
| __| / _ \ | | / _ \
| |_ | __/ | | | __/
\__| \___| |_| \___|
A terminal-native Telegram client built for keyboard-driven workflows.
Features • Installation • Why tele? • Keybindings • Roadmap
Status: Active development — already usable for daily messaging (private chats, groups, replies, reactions). Some Telegram features are still in progress.
Why tele?
Telegram Desktop, the web client, and mobile apps are designed around mouse-first interaction.
If you live in the terminal — using tools like Neovim, yazi, k9s, or tmux — switching to a GUI messenger breaks your flow.
tele keeps you in the terminal.
It is built for:
- keyboard-driven navigation
- fast chat switching
- SSH / remote workflows
- distraction-free messaging
If tools like lazygit feel natural to you, tele will too.
It also runs lean — typically ~35MB RSS at idle vs several hundred MB for desktop clients.
| Feature | tele | Telegram Desktop | Web |
|---|---|---|---|
| Terminal-native | ✅ | ❌ | ❌ |
| Keyboard-first | ✅ | ⚠️ partial | ⚠️ partial |
| Works over SSH | ✅ | ❌ | ❌ |
| Single static binary | ✅ | ❌ | ❌ |
| Full media support | ⚠️ photos | ✅ | ✅ |
| Voice/video calls | ❌ planned | ✅ | ✅ |
Features
⚡ Keyboard-first UX
Vim-inspired navigation (j/k, gg/G, insert mode, etc.)
💬 Full Telegram support
Private chats, groups, channels, replies, reactions, edits.
🧠 Terminal-native design
Built specifically for terminal workflows — not adapted from a GUI client.
🚀 Lightweight by design
Single static Go binary with fast startup and low memory usage.
⚙ Simple configuration
YAML-based config with sensible defaults.
Installation
macOS / Linux — Homebrew
brew tap sorokin-vladimir/tele
brew install tele
Linux — binary
curl -sL https://github.com/sorokin-vladimir/tele/releases/latest/download/tele-linux-amd64 \
-o ~/.local/bin/tele && chmod +x ~/.local/bin/tele
For arm64: replace amd64 with arm64.
First launch
tele
On first run, tele creates:
~/.config/tele/config.yml
Then prompts for:
- phone number
- SMS code
- optional 2FA password
Flags
| Flag | Description |
|---|---|
--config <path> |
Path to config file (default ~/.config/tele/config.yml) |
-e |
Enable debug logging |
--trace |
Log sensitive metadata (peer IDs, message lengths). Never use on shared or synced file systems |
--version |
Print version and exit |
Keybindings
| Key | Action |
|---|---|
j / k |
Navigate chats or scroll messages |
i |
Compose message |
r |
Reply |
e / d |
Edit / delete message |
t |
React |
/ |
Search chats |
0 / 1 / 2 |
Focus panes |
q |
Quit |
Full reference: docs/keybindings.md
Configuration
telegram:
session_file: ~/.config/tele/session.json
ui:
date_format: "15:04"
history_limit: 50
theme: default
Customizing keybindings
Override default keys in the keybindings: section of ~/.config/tele/config.yml.
Bindings are grouped by context, then by action:
keybindings:
chat:
reply: "R" # a single key
go_top: ["g g", "gg"] # several keys for one action
chatlist:
confirm: "l"
- Replace semantics: the keys you list become the only keys for that action in that context. Actions you don't mention keep their defaults.
- Chords: a multi-key sequence is written as space-separated key tokens —
"g g"means pressgtheng. Tokens use the terminal key names (ctrl+d,enter,esc,space,up, ...). - Conflicts (an unknown action/context, an empty key, a key reused for two actions, or a single key that shadows a chord) are logged as warnings on startup and skipped or applied last-wins; a bad section never crashes the app.
Contexts: global, folders, chatlist, chat, composer, search,
context_menu, delete_submenu.
See docs/keybindings.md for the full list of action names and what each one does.
Roadmap
Tracked via GitHub milestones.
| Milestone | Focus |
|---|---|
| Security & Reliability | safer event handling, logging, cleanup |
| Architecture & Performance | caching, memory caps, optimization |
| Feature Completeness | forwarding, mentions, drafts, search |
| Power User & Polish | themes, vim motions, command palette |
Build from source
Requires Go 1.26+ and your own Telegram API credentials.
git clone https://github.com/sorokin-vladimir/tele
cd tele
go build \
-ldflags "-X main.buildAPIID=YOUR_API_ID -X main.buildAPIHash=YOUR_API_HASH" \
-o tele ./cmd/tele/
License
GPL-3.0 — free to use and fork; derivative works must remain open-source.
Built with:
Directories