# telegram-tui

A minimal Telegram terminal client built with `ncurses` and TDLib.

## Features

- interactive login flow inside the TUI
- chat list in the left pane
- message view in the right pane
- send plain text messages
- scroll chats and message history with the keyboard

## Requirements

- CMake 3.21+
- a C++17 compiler
- `ncurses`
- TDLib build dependencies (`gperf`, `openssl`, `zlib`, `git`)

The project vendors TDLib automatically by default. If you already have TDLib installed with CMake package metadata, configure with `-DTELEGRAM_TUI_USE_SYSTEM_TDLIB=ON`.
If you have a prebuilt TDLib bundle with `include/` and `lib/`, configure with
`-DTELEGRAM_TUI_TDLIB_ROOT=/path/to/tdlib`.

## Build

```bash
cmake -S . -B build
cmake --build build -j
```

During configure, CMake also checks the app config at
`$XDG_DATA_HOME/telegram-tui/config.json` or `~/.local/share/telegram-tui/config.json`.
If that file contains `api_id` and `api_hash`, they are embedded into the build.
For CI or release builds, prefer setting `TELEGRAM_TUI_BUILD_API_ID` and
`TELEGRAM_TUI_BUILD_API_HASH` in the environment so credentials come from secrets instead of
local config.

## Run

Create a Telegram application at <https://my.telegram.org/apps>, then either rely on the
embedded credentials from the app config above, or export credentials:

```bash
export TELEGRAM_API_ID=123456
export TELEGRAM_API_HASH=0123456789abcdef0123456789abcdef
./build/telegram-tui
```

Or start the app without env vars and enter them interactively when prompted.
When entered in the TUI, the app now stores `api_id` and `api_hash` in
`~/.local/share/telegram-tui/config.json` and reuses them on later launches.

Clipboard image sending via `>paste` or `>clip` requires an external clipboard tool:
- `wl-clipboard` on Wayland or KDE Plasma Wayland
- `xclip` on X11

Klipper by itself is not a supported image backend for this feature.

To use Telegram test servers instead of production:

```bash
export TELEGRAM_USE_TEST_DC=1
./build/telegram-tui
```

The client stores TDLib state in `~/.local/share/telegram-tui/tdlib` for production and `~/.local/share/telegram-tui/test/tdlib` for test mode.

## Gitea Actions

The repository includes [`.gitea/workflows/build-tdlib.yaml`](.gitea/workflows/build-tdlib.yaml),
which builds the latest upstream TDLib tag on Gitea Actions and publishes a bundled TDLib
archive plus checksum to the Gitea Generic Package Registry under the `tdlib` package.
It also refreshes a `latest/tdlib-latest.json` manifest with the newest published version.

The repository also includes [`.gitea/workflows/release-app.yaml`](.gitea/workflows/release-app.yaml),
which downloads a prebuilt TDLib bundle from the `shinoa-tdlib` repository using a pinned
version tag such as `v1.8.63`, builds a
versioned app release tag such as `v0.1.0`, and publishes an archive containing `usr/bin/shinoa` plus the
bundled `usr/lib/libtdjson.so*`. The root `PKGBUILD` installs that prebuilt release as
`shinoa-bin`. The package disables debug splitting with `options=(!debug)`. That workflow expects Gitea secrets named `TELEGRAM_API_ID` and
`TELEGRAM_API_HASH`. Release builds are configured to fail if those secrets are missing.

To prepare the TDLib bundle on your own machine:

```bash
cmake -S td -B td-build -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX="$PWD/td-install"
cmake --build td-build -j"$(nproc)"
cmake --install td-build
./scripts/package-tdlib.sh td-install tdlib-linux-x86_64.tar.gz
```

Publish `tdlib-linux-x86_64.tar.gz` to the `shinoa-tdlib` repository under a versioned tag such
as `v1.8.63`. Then update `TDLIB_RELEASE_TAG` in
[`.gitea/workflows/release-app.yaml`](.gitea/workflows/release-app.yaml) and run the
`Release App` workflow.

## Keys

- `Up` / `Down`: move selection
- `Tab`: switch focus between chats and messages
- `Enter`: open the selected chat
- `i`: start composing a message
- `PgUp` / `PgDn`: scroll the current message view
- `r`: reload chats or history
- `Esc`: cancel current input
- `q`: quit