⚠️ Note that this is the first release of tgt. Please consider to open an issue if you find any bug or if you have any suggestion. ⚠️

A simple TUI for Telegram

About

tgt is a terminal user interface for Telegram, written in Rust.

Usage

From crates.io

cargo install tgt

From source downloading the tdlib

cargo build --release --features download-tdlib

After the installation, you can run tgt with the following command:

tgt --help

Features

Build features can be combined (e.g. cargo build --release --features download-tdlib,chafa-dyn).

Feature	Description
default	Enables download-tdlib and voice-message.
download-tdlib	Download and use TDLib automatically (recommended for most users).
local-tdlib	Use TDLib from path in LOCAL_TDLIB_PATH.
pkg-config	Find TDLib via pkg-config.
voice-message	Play Telegram voice notes (OGG Opus) and other audio (e.g. MP3). Requires CMake to build the Opus dependency. Enabled by default; use --no-default-features and then add back only the features you need (e.g. --features download-tdlib) to disable voice.
chafa-dyn	Enable chafa-based image rendering in the photo viewer (dynamic linking). Requires the chafa library installed on the system. Not supported on Windows ARM.
chafa-static	Same as chafa-dyn but links chafa statically. Not supported on Windows ARM.

Voice messages
If you build with the default features (or with voice-message enabled), you must have CMake installed so the Opus library can be built. Other audio formats (e.g. MP3) use rodio only; only Telegram voice notes (Opus) need this. If you build with --no-default-features and do not enable voice-message, voice playback is disabled and the app will show a message when you try to play a voice note.

Installation methods for CMake (when using voice-message)

• macOS — Homebrew: brew install cmake
• Linux — use your package manager, e.g. sudo apt install cmake (Debian/Ubuntu), sudo dnf install cmake (Fedora), sudo pacman -S cmake (Arch)
• Windows — CMake installer or e.g. winget install Kitware.CMake

Chafa (image rendering)
The chafa-dyn and chafa-static features use the chafa library to display images in the terminal. You must have chafa installed to use these features.

Installation methods for chafa

• Linux (Debian/Ubuntu/Kali, Fedora, Arch, openSUSE, etc.) — use your package manager:
  • sudo apt install chafa (Debian/Ubuntu/Kali)
  • sudo dnf install chafa (Fedora)
  • sudo pacman -S chafa (Arch Linux)
  • sudo zypper in chafa (openSUSE)
  • sudo emerge media-gfx/chafa (Gentoo)
• macOS — Homebrew or MacPorts:
  • brew install chafa
  • sudo port install chafa
• Windows — Scoop or Windows Package Manager (winget):
  • scoop install chafa
  • winget install hpjansson.Chafa

Arch Linux

Thanks to x-leehe for creating the AUR package. You can install tgt from the AUR:

yay -S tgt-client-git

NixOS

From flake.nix

First, create the required TOML configuration files in ~/.tgt/config using these commands:

git clone https://github.com/FedericoBruzzone/tgt ~/tgt
mkdir -p ~/.tgt/config
cp -r ~/tgt/config/* ~/.tgt/config

After setting up the configuration files, you have two installation options:

1. Run directly with nix run:

nix run github:FedericoBruzzone/tgt

2. Add tgt to your system packages:

Add the following to your flake.nix:

{
  inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable"
    tgt.url = "github:FedericoBruzzone/tgt";
    tgt.inputs.nixpkgs.follows = "nixpkgs";
  };

  outputs = { nixpkgs, tgt, ... }: { /* ... */ }
}

Then add it to your environment.systemPackages:

{pkgs, tgt, ...}: {
  environment = {
    systemPackages = [
        (tgt.packages.${pkgs.system}.default)
    ];
  };
}

To use a specific version of the program, override the src attribute:

{pkgs, tgt, ...}: {
  environment = {
    systemPackages = [
      (tgt.packages.${pkgs.system}.default.overrideAttrs (old: {
        src = pkgs.fetchFromGitHub {
          owner = old.src.owner;
          repo = old.src.repo;
          rev = "00000000000000000000000000000000000000";
          sha256 = "sha256-AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=";
        };
        cargoHash = "sha256-AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=";
      }))
    ];
  };
}

Docker build

• The Docker image is built using rust:1.91-trixie as the base.

• Run Docker image in interactive mode to open a bash shell. Specify a container name to reuse when required.

docker run -it --name <container_name> ghcr.io/FedericoBruzzone/tgt:<version>

• Run tgt command from bash shell.

tgt

• for reusing the same container for next boot cycles, start the container

docker container start <container_name>

• run tgt by opening interactive shell from the container

docker exec -it <container_name> bash

Configuration

Note that tgt is fully customizable. For more information about the configuration, please look at here. The configuration files are manyfold.

1. app.toml: contains general configurations about the application (see app.toml.md for explanations about each field). Message status icons (edited, reply, sent, seen) can be shown as ASCII-style (default) or emoji: set use_emoji_icons = true in app.toml to use emoji (✏️ ↩️ 📤 👀); when false (default), the app uses [mod] edited, <-- Reply to reply, [✓] sent, [o o] seen.
2. keymap.toml: contains the keybindings used in the application (see keymap.toml.md for explanations about each field).
3. logger.toml: contains the logging configurations (see logger.toml.md for explanations about each field).
4. telegram.toml: contains the Telegram API and TDLib configurations (see telegram.toml.md for explanations about each field).
5. theme.toml: contains the color theme configurations (see theme.toml.md for explanations about each field).

Note

The theme switcher only persists the selected theme in release mode. In debug mode, the chosen theme is not saved between sessions.

Warning

Generally, end-users are expected to supply their own api_id and api_hash. While some open-source clients, including tgt, may provide "default" credentials to make the "out-of-the-box" experience smoother, shipping shared credentials carries risks. The telegram.toml.md file contains more information about this topic.

Default keybindings:

None state:

esc:               to the "None" state
alt+1 | alt+left:  Focus on the chat list
alt+2 | alt+right: Focus on the chat
alt+3 | alt+down:  Focus on the prompt
alt+h | alt+l:     Resize the chat list
alt+j | alt+k:     Resize the prompt
alt+n:             Toggle chat list
alt+r:             Start chat list search (when nothing is selected)
alt+c:             Restore the default ordering of the chat list
alt+f1:            Show command guide with all keybindings
alt+t:             Show theme selector
q | ctrl+c:        Quit

Chat List

up | down:     Move selection
enter | right: Open the chat
left:          Unselect chat
alt+r:         Focus on prompt to start searching
alt+c:         Restore the default ordering of the chat list

esc:               Return to the "None" state
alt+1 | alt+left:  Focus on the chat list
alt+2 | alt+right: Focus on the chat
alt+3 | alt+down:  Focus on the prompt

Chat

up | down: Scroll the messages
left:      Unselect message
y:         Copy the message
e:         Edit the message
r:         Reply to the message
d:         Delete the message for everyone
D:         Delete the message for me
alt+v:     View photo from selected message (opens photo viewer)
alt+r:     Focus on prompt to search messages in the chat window
alt+c:     Restore the default ordering of messages

esc:               Return to the "None" state
alt+1 | alt+left:  Focus on the chat list
alt+2 | alt+right: Focus on the chat
alt+3 | alt+down:  Focus on the prompt

Photo Viewer
Open from the chat by selecting a photo message and pressing alt+v. When the photo viewer is focused:

esc :   Close the photo viewer
up | k:    View previous message
down | j:  View next message

esc:               Return to the "None" state
alt+1 | alt+left:  Focus on the chat list
alt+2 | alt+right: Focus on the chat
alt+3 | alt+down:  Focus on the prompt

Prompt

Note that when the prompt is focused, you can NOT use q or ctrl+c to quit the application, you need to press esc to return to the "None" state.

alt+enter:                        Send the message

left | right | up | down:         Move the cursor
ctrl+left | ctrl+b:               Move the cursor to the previous word
ctrl+right | ctrl+f:              Move the cursor to the next word
ctrl+alt+left | ctrl+a | home:    Move the cursor to the beginning of the line (also ctrl+left+b | shift+super+left | shift+super+b)
ctrl+alt+right | ctrl+e | end:    Move the cursor to the end of the line (also ctrl+right+f | shift+super+right | shift+super+f)

shift+left:                       Move the cursor left and select the text
shift+right:                      Move the cursor right and select the text
shift+up:                         Move the cursor up and select the text
shift+down:                        Move the cursor down and select the text
shift+ctrl+left:                  Select the text before the cursor
shift+ctrl+right:                 Select the text after the cursor

ctrl+c:                           Copy the selected text
ctrl+v:                           Paste the copied text

ctrl+w | ctrl+backspace | ctrl+h: Delete the word before the cursor

esc:               Return to the "None" state
alt+1 | alt+left:  Focus on the chat list
alt+2 | alt+right: Focus on the chat
alt+3 | alt+down:  Focus on the prompt

Mouse

Scroll:   In chat list or chat to move selection or messages
Chat list: First click focuses the list, second click on an item opens that chat

Contributing

Contributions to this project are welcome! If you have any suggestions, improvements, or bug fixes, feel free to submit a pull request. For more information, do not hesitate to contact us (see the Contact section).

Build instructions

There are three ways to build tgt:

1. Using the download-tdlib feature of tdlib-rs you do not need to set any environment variable. Then you can compile tgt using cargo build --features download-tdlib.
2. By default, tgt assumes that you have the tdlib built and the LOCAL_TDLIB_PATH environment variable set to the path of the tdlib directory. You can set the environment variable with the following command: export LOCAL_TDLIB_PATH="/path/to/tdlib". Then you can compile tgt using cargo build or cargo build --feature default.
3. You can use pkg-config to find the path of the library. In this case see the CONTRIBUTING.md file for more information. Then you can compile tgt using cargo build --features pkg-config.

The CONTRIBUTING.md file contains information for building tgt and the steps to configure the tdlib in your local environment, starting from the compilation to the configuration of the environment variables.

Road Map

You can find the road map of the project here (in the pinned issues).

Commands

You can use make or cargo, as build tools. If you want to use cargo, please make sure to read the the Makefile to understand the flags used for each command. Here are the available commands:

make COMMAND

COMMAND:
  all            # Run fmt, clippy and test
  build          # Build the project
  run            # Run the project
  test           # Run the tests
  clippy         # Run clippy
  fmt            # Run rustfmt
  clean          # Clean the project

License

This repository is licensed under either of

• Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)

• MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.

Please review the license file provided in the repository for more information regarding the terms and conditions of the license.

Contact

If you have any questions, suggestions, or feedback, do not hesitate to contact me.

Maintainers:

• FedericoBruzzone
• Andreal2000