nchat

Linux	Mac

nchat is a multi-protocol terminal-based messaging client for Linux and macOS with support for Telegram, WhatsApp and Signal (opt-in).

Features

• Send and receive markdown formatted messages
• Reply, delete, edit and forward messages
• Mention users in group chats
• Send and display message reactions
• View and save media (documents, photos, videos)
• Show message read and edited indicators
• Show user status (online, away, typing)
• Jump to next unread chat
• Archive, pin and delete chats
• Search messages within a chat
• List dialogs for chats, contacts, emojis, files
• Message history cache with text export
• Desktop notifications for new messages
• Toggle textized vs. graphical emojis
• Customizable themes and key bindings

Optional Features

Signal support is disabled by default and requires enabling a feature flag.

Usage

Usage:

nchat [OPTION]

Command-line Options:

-d, --confdir <DIR>    use a different directory than ~/.config/nchat
-e, --verbose          enable verbose logging
-ee, --extra-verbose   enable extra verbose logging
-h, --help             display this help and exit
-k, --keydump          key code dump mode
-m, --devmode          developer mode
-r, --remove           remove chat protocol account
-s, --setup            set up chat protocol account
-v, --version          output version information and exit
-x, --export <DIR>     export message cache to specified dir

Interactive Commands:

PageDn      history next page
PageUp      history previous page
Tab         next chat
Sh-Tab      previous chat
Ctrl-f      jump to unread chat
Ctrl-g      toggle show help bar
Ctrl-l      toggle show contact list
Ctrl-n      goto chat
Ctrl-p      toggle show top bar
Ctrl-q      quit
Ctrl-s      insert emoji
Ctrl-t      send file
Ctrl-x      send message
Ctrl-y      toggle show emojis
KeyUp       select message
Alt-@       insert mention
Alt-a       archive current chat
Alt-d       delete/leave current chat
Alt-e       external editor compose
Alt-i       auto-compose reply
Alt-n       search contacts
Alt-p       pin/unpin current chat
Alt-t       external telephone call
Alt-/       find in chat
Alt-?       find next in chat
Alt-$       external spell check
Alt-,       decrease contact list width
Alt-.       increase contact list width

Interactive Commands for Selected Message:

Ctrl-d      delete selected message
Ctrl-r      download attached file
Ctrl-v      open/view attached file
Ctrl-w      open link
Ctrl-x      send reply to selected message
Ctrl-z      edit selected message
Alt-c       copy selected message to clipboard
Alt-q       jump to quoted/replied message
Alt-r       forward selected message
Alt-s       add/remove reaction on selected message
Alt-w       external message viewer

Interactive Commands for Text Input:

Ctrl-a      move cursor to start of line
Ctrl-c      clear input buffer
Ctrl-e      move cursor to end of line
Ctrl-k      delete from cursor to end of line
Ctrl-u      delete from cursor to start of line
Alt-Left    move cursor backward one word
Alt-Right   move cursor forward one word
Alt-Backsp  delete previous word
Alt-Delete  delete next word
Alt-Tab     insert tab (four spaces)
Alt-c       copy input buffer to clipboard (if no message selected)
Alt-v       paste into input buffer from clipboard
Alt-x       cut input buffer to clipboard

Supported Platforms

nchat is developed and tested on Linux and macOS. Current version has been tested on:

• macOS Sequoia 15.5
• Ubuntu 24.04 LTS

Install using Package Manager

macOS

Build / Install Stable Release using Brew

brew tap d99kris/nchat
brew install nchat

Optionally one can disable protocols using --without-whatsapp and --without-telegram, for example:

brew install nchat --without-telegram

Arch Linux

Build / Install Latest Git

yay -S nchat-git

Build / Install Stable Release

yay -S nchat

Build from Source

nchat consists of a large code-base (mainly the Telegram library tdlib), so be prepared for a relatively long first build time.

Get Source

git clone https://github.com/d99kris/nchat && cd nchat

Using make.sh script

If using macOS, Alpine, Arch, Fedora, Gentoo, Raspbian, Ubuntu or Void, one can use the make.sh script provided.

Dependencies

./make.sh deps

Build / Install

./make.sh build && ./make.sh install

Manually

Dependencies

macOS

brew install gperf cmake openssl ncurses ccache readline help2man sqlite libmagic go

Arch

sudo pacman -S ccache cmake file go gperf help2man ncurses openssl readline sqlite zlib base-devel

Debian-based (Ubuntu, Raspbian, etc)

sudo apt install ccache cmake build-essential gperf help2man libreadline-dev libssl-dev libncurses-dev libncursesw5-dev ncurses-doc zlib1g-dev libsqlite3-dev libmagic-dev golang

Fedora

sudo dnf install git cmake clang golang ccache file-devel file-libs gperf readline-devel openssl-devel ncurses-devel sqlite-devel zlib-devel

Gentoo

sudo emerge -n dev-util/cmake dev-util/ccache dev-util/gperf sys-apps/help2man sys-libs/readline dev-libs/openssl sys-libs/ncurses sys-libs/zlib dev-db/sqlite sys-apps/file dev-lang/go

Void

sudo xbps-install base-devel go ccache cmake gperf help2man libmagick-devel readline-devel sqlite-devel file-devel openssl-devel

Extra Dependencies

For Wayland-based systems install wl-clipboard to enable clipboard functionality.

To support pasting images directly from clipboard libpng-dev is needed. On X11 systems libxcb1-dev and libx11-dev are needed as well.

Build

mkdir -p build && cd build && cmake .. && make -s

Install

sudo make install

Advanced Build Options

By default nchat requires ~3.5GB RAM to build using G++ and ~1.5GB RAM with clang++, but it is possible to reduce the memory needed, see Building on Low Memory Systems.

All nchat features are enabled by default, but it's possible to control inclusion of some features using cmake flags, see Feature Flags.

Getting Started

In order to configure / setup an account one needs to run nchat in setup mode:

nchat --setup

The setup mode prompts for phone number, which shall be entered with country code. Example:

$ nchat --setup
Protocols:
0. Dummy
1. Telegram
2. WhatsAppMd
3. Signal
4. Exit setup
Select protocol (3): 1
Enter phone number (ex. +6511111111): +6511111111

Open Telegram on your phone, go to Settings -> Devices
and click Link Desktop Device and scan the QR code.
...
Succesfully set up profile Telegram_+6511111111

By default, nchat uses QR code authentication. The QR code should be scanned using the official app on the primary device. To use authentication code instead, set the USE_PAIRING_CODE environment variable (see FAQ below).

If unsure of what phone number to enter, open the official app on the phone and look for the phone number under Settings or Profile section, and use the number displayed there (omitting spaces, so for the below screenshot the number to enter is +6511111111).

Once the setup process is completed, the main UI of nchat will be loaded.

In order to set up multiple protocols/profiles, exit nchat and perform the setup step again. To remove a protocol account, use nchat --remove.

Troubleshooting

Refer to Debugging for details.

Telegram Group

A Telegram group https://t.me/nchatusers is available for users to discuss nchat usage and related topics.

Security

User data is stored locally in ~/.config/nchat. Default file permissions only allow user access, but anyone who can gain access to a user's private files can also access the user's personal nchat data. To protect against the most simple attack vectors it may be suitable to use disk encryption and to ensure ~/.config/nchat is not backed up unencrypted.

Configuration

The following configuration files (listed with current default values) can be used to configure nchat.

~/.config/nchat/app.conf

This configuration file holds general application settings. Default content:

assert_abort=0
attachment_prefetch=1
attachment_send_type=1
cache_enabled=1
cache_read_only=0
clipboard_copy_command=
clipboard_has_image_command=
clipboard_paste_command=
clipboard_paste_image_command=
coredump_enabled=0
downloads_dir=
emoji_list_all=0
link_send_preview=1
logdump_enabled=0
mentions_quoted=1
message_delete=1
proxy_host=
proxy_pass=
proxy_port=
proxy_user=
timestamp_iso=0
use_pairing_code=0
use_qr_terminal=0
version_used=

assert_abort

Specifies whether to abort execution (crash) if assertions fail. Primarily intended for debugging.

attachment_send_type

Specifies how attachments are sent:

0 = send all attachments as document type (typically preserves file content)
1 = detect file type (audio, video, image, document) and send as that type <- default
2 = like 1, but when sending just a file (no text or quote), webp files are
    sent as stickers and mp4/m4v files as borderless auto-playing "GIFs"

attachment_prefetch

Specifies level of attachment prefetching:

0 = no prefetch (download upon open/save)
1 = selected (download upon message selection) <- default
2 = all (download when message is received)

cache_enabled

Specifies whether to enable cache functionality.

cache_read_only

Specifies whether to access cache read-only. Primarily intended for debugging.

clipboard_*_command

Specifies custom clipboard commands to be used instead of system clipboard. Refer to Clipboard for details.

coredump_enabled

Specifies whether to enable core dumps on application crash.

downloads_dir

Specifies a custom downloads directory path to save attachments to. If not specified, the default dir is ~/Downloads if exists, otherwise ~.

emoji_list_all

Specifies whether the emoji dialog should list all emojis, it is otherwise restricted to listing emojis that renders properly in common terminals.

link_send_preview

Specifies whether to enable preview for links in messages sent (Telegram only).

logdump_enabled

Specifies whether to dump warning and error log messages to stdout upon exit.

mentions_quoted

Specifies whether to use bracket quoting for display-name mentions with spaces.

message_delete

Specifies handling of message deletion by other users (WhatsApp and Signal):

1 = erase message <- default
2 = replace message text with `[This message was deleted]`
3 = prefix message text with `[This message was deleted]`

Messages deleted by oneself are always erased locally regardless of this setting. Deleting messages already marked deleted erases them locally.

proxy_

SOCKS5 proxy server details. To enable proxy usage the parameters host and port are required, while user and pass are optional (depending on the SOCKS server). Note: In order to use a proxy while setting up nchat the first time, it is recommended to first run nchat without arguments (nchat) for its config dir to be created, and then edit proxy settings in ~/.config/nchat/app.conf as needed, before running nchat -s to setup an account.

timestamp_iso

Specifies whether to use ISO-style timestamps (YYYY-MM-DD HH:MM) in the UI and at export of chat history. By default nchat uses a dynamic "human-friendly" format:

• HH:MM for timestamps on same date as today, e.g. 19:00
• DAY HH:MM for timestamps in the last week, e.g. Mon 19:00
• DD MMM HH:MM for timestamps in the current year, e.g. 14 Nov 19:00
• DD MMM YYYY HH:MM for timestamps in non-current year, e.g. 14 Nov 2022 19:00
• DD MMM YYYY HH:MM for timestamps during export, e.g. 14 Nov 2022 19:00

use_pairing_code

Stores the environment variable flag USE_PAIRING_CODE if set during setup. It specifies whether to use pairing code / authentication code instead of QR code (Telegram/WhatsApp).

use_qr_terminal

Stores the environment variable flag USE_QR_TERMINAL if set during setup. It specifies whether to display QR code in the terminal, disabling detection of GUI capability for displaying images.

version_used

For internal use only. Stores version used for last successful execution. May be used for debugging startup crash / hang regressions.

~/.config/nchat/ui.conf

This configuration file holds general user interface settings. Default content:

attachment_indicator=📎
attachment_open_command=
away_status_indication=0
auto_compose_command=
auto_compose_enabled=0
auto_compose_history_count=25
auto_select_chat_timeout_sec=1
call_command=
chat_picker_sorted_alphabetically=0
confirm_archiving=1
confirm_deletion=1
confirm_send_pasted_image=1
desktop_notify_active_current=0
desktop_notify_active_noncurrent