Telegram terminal client.
- view mediafiles: photo, video, voice/video notes, documents
- ability to send pictures, documents, audio, video
- reply, edit, forward, delete, send messages
- stickers
- notifications
- record and send voice msgs
- auto download files
- toggle chats: pin/unpin, mark as read/unread, mute/unmute
- message history
- list contacts
- show user status
- secret chats
- search
- bots (bot keyboard)
To use tg, you'll need to have the following installed:
- terminal-notifier - for Mac (used by default). You can change it to dunst for Linux or any other notifications program (see
NOTIFY_CMD
in configuration) - ffmpeg - to record voice msgs and upload videos.
- tdlib - in case of incompatibility with built in package.
For example, macOS:
and then set in config
brew install tdlib
TDLIB_PATH
urlview
to choose urls when there is multiple in message, useURL_VIEW
in config file to use another app (it should accept urls in stdin)- to open
stickers
andanimated
ones (thumbnail preview) you need to set in mailcap appropriate handler and have app which will openwebp
file:image/webp; mpv %s
- ranger, nnn - can be used to choose file when sending, customizable with
FILE_PICKER_CMD
- fzf - to create groups and secret chats (used for single and multiple user selection)
This option is recommended for production:
pip3 install tg
tg
This option is recommended for development:
git clone https://github.com/paul-nameless/tg.git
cd tg
pip install python-telegram
pip install .
tg
Please note that voice recordings and notifications won't work when using Docker.
docker run -it --rm tg
If you're using Arch Linux, you can install tg through its AUR package:
If you're using the yay
AUR helper, you can install the package with:
yay -S telegram-tg
If you want to use the latest developement version via the AUR you can find it here
Config file should be stored at ~/.config/tg/conf.py
. This is simple python file.
# should start with + (plus) and contain country code
PHONE = "[phone number in international format]"
All configurable variables can be found here
import os
# You can write anything you want here, file will be executed at start time
# You can keep you sensitive information in password managers or gpg
# encrypted files for example
def get_pass(key):
# retrieves key from password store
return os.popen("pass show {} | head -n 1".format(key)).read().strip()
PHONE = get_pass("i/telegram-phone")
# encrypt you local tdlib database with the key
ENC_KEY = get_pass("i/telegram-enc-key")
# log level for debugging, info by default
LOG_LEVEL = "DEBUG"
# path where logs will be stored (all.log and error.log)
LOG_PATH = os.path.expanduser("~/.local/share/tg/")
# If you have problems with tdlib shipped with the client, you can install and
# use your own, for example:
TDLIB_PATH = "/usr/local/Cellar/tdlib/1.6.0/lib/libtdjson.dylib"
# you can use any other notification cmd, it is simple python string which
# can format title, msg, subtitle and icon_path paramters
# In these exapmle, kitty terminal is used and when notification is pressed
# it will focus on the tab of running tg
NOTIFY_CMD = "/usr/local/bin/terminal-notifier -title {title} -subtitle {subtitle} -message {msg} -appIcon {icon_path} -sound default -execute '/Applications/kitty.app/Contents/MacOS/kitty @ --to unix:/tmp/kitty focus-tab --no-response -m title:tg'"
# You can use your own voice recording cmd but it's better to use default one.
# The voice note must be encoded with the Opus codec, and stored inside an OGG
# container. Voice notes can have only a single audio channel.
VOICE_RECORD_CMD = "ffmpeg -f avfoundation -i ':0' -c:a libopus -b:a 32k {file_path}"
# You can customize chat and msg flags however you want.
# By default words will be used for readability, but you can make
# it as simple as one letter flags like in mutt or add emojies
CHAT_FLAGS = {
"online": "โ",
"pinned": "P",
"muted": "M",
# chat is marked as unread
"unread": "U",
# last msg haven't been seen by recipient
"unseen": "โ",
"secret": "๐",
"seen": "โโ", # leave empty if you don't want to see it
}
MSG_FLAGS = {
"selected": "*",
"forwarded": "F",
"new": "N",
"unseen": "U",
"edited": "E",
"pending": "...",
"failed": "๐ฉ",
"seen": "โโ", # leave empty if you don't want to see it
}
# use this app to open url when there are multiple
URL_VIEW = 'urlview'
# Specifies range of colors to use for drawing users with
# different colors
# this one uses base 16 colors which should look good by default
USERS_COLORS = tuple(range(2, 16))
# to use 256 colors, set range appropriately
# though 233 looks better, because last colors are black and gray
# USERS_COLORS = tuple(range(233))
# to make one color for all users
# USERS_COLORS = (4,)
# cleanup cache
# Values: N days, None (never)
KEEP_MEDIA = 7
FILE_PICKER_CMD = "ranger --choosefile={file_path}"
# FILE_PICKER_CMD = "nnn -p {file_path}"
MAILCAP_FILE = os.path.expanduser("~/.config/mailcap")
DOWNLOAD_DIR = os.path.expanduser("~/Downloads/") # copy file to this dir
Mailcap file is used for deciding how to open telegram files (docs, pics, voice notes, etc.). Path to the file can be overriden with MAILCAP_FILE
in config file.
Example: ~/.mailcap
# media
video/*; mpv "%s"
audio/ogg; mpv --speed 1.33 "%s"
audio/mpeg; mpv --no-video "%s"
image/*; qView "%s"
# text
text/html; w3m "%s"
text/html; open -a Firefox "%s"
text/plain; less "%s"
# fallback to vim
text/*; vim "%s"
vi like keybindings are used in the project. Can be used commands like 4j
- 4 lines down.
For navigation arrow keys also can be used.
j,k
: move up/downJ,K
: move 10 chats up/downg
: go to top chatl
: open msgs of the chatm
: mute/unmute current chatp
: pin/unpin current chatu
: mark read/unreadr
: read current chatc
: show list of contactsdd
: delete chat or remove historyng
: create new group chatns
: create new secret chat/
: search in chats?
: show help
j,k
: move up/downJ,K
: move 10 msgs up/downG
: move to the last msg (at the bottom)D
: download filel
: if video, pics or audio then open app specified in mailcap file, for example:if text, open in# Images image/png; qView "%s" audio/*; mpv "%s"
less
(to view multiline msgs)e
: edit current msg<space>
: select msg and jump one msg down (use for deletion or forwarding)<ctrl+space>
: same as space but jumps one msg upy
: yank (copy) selected msgs with to internal buffer (for forwarding) and copy current msg text or path to file to clipboardp
: forward (paste) yanked (copied) msgs to current chatdd
: delete msg for everybody (multiple messages will be deleted if selected)i or a
: insert mode, type new messageI or A
: open vim to write long msg and sendv
: record and send voice messager,R
: reply to a current msgsv
: send videosa
: send audiosp
: send picturesd
: send documento
: open url present in message (if multiple urls,urlview
will be opened)]
: next chat[
: prev chatu
: show user info (username, bio, phone, etc.)c
: show chat info (e.g. secret chat encryption key, chat id, state, etc.)?
: show help!
: open msg with custom cmd
# increase version in tg/__init__.py
git commit -m 'Release 0.7.0'
git tag v0.7.0
flit publish
git log --pretty=format:"%cn: %s" v0.6.0...v0.7.0 | grep -v -e "Merge pull request" | grep -v "Release"
git push origin master --tags