search

isamert / scli

a simple terminal user interface for signal messenger (using signal-cli)
GNU General Public License v3.0
432 stars 40 forks source link

readme

scli

scli is a simple terminal user interface for Signal. It uses signal-cli and urwid.

Features

Limitations

Installation

Automatic

The following methods are supported by community and may be outdated.

Packaging status

Manual

Clone the repo

git clone https://github.com/isamert/scli

or download a release.

Dependencies

Registering or linking your device

Before running scli, signal-cli needs to be registered with the signal servers. You can either register a new device, or link signal-cli with an already registered device (e.g. your phone).

Linking can be done interactively with scli link, see the next section.

For more information, see: signal-cli usage, man page, and wiki.

Linking with scli link

Linking with an existing account can be done interactively with

scli link [--name DEVICE_NAME]

and following instructions on the screen. The DEVICE_NAME is optional, scli is used by default.

This requires pyqrcode package (available on PyPI and other repositories)

Verifying setup

After registering or linking, verify that the following commands work:

signal-cli -u USERNAME receive

and

signal-cli -u USERNAME daemon

where USERNAME is the phone number you have used (starting with the "+" sign followed by the country calling code). Stop the latter process (Ctrl+C) after verifying that it starts successfully and does not throw any errors.

Now you can run

scli

(if you have put it on your system's $PATH; alternatively, specify the full /path/to/executable/scli).

Usage

Key bindings

For the full list of key bindings, press ? in scli.

If urwid_readline module is installed, all of its keybindings are available in the input widgets.

Modifying key bindings

Key bindings can be re-mapped with a --key-bind option. For example:

scli --key-bind show_message_info:s --key-bind reaction_emoji_picker:e,R,!,'ctrl r'

The syntax is

--key-bind ACTION:KEY[,KEY[,…]]

where ACTION is one of the action names (press ? in scli to show the full list of action names and their default key bindings), and KEY is the name of a key or key combo in urwid's syntax (see the table in Keyboard input section of urwid manual). Keys for several actions can be re-assigned by passing multiple --key-bind arguments to scli. Multiple keys can be assigned to a single action by separating KEYs with commas.

Commands

Commands are entered by typing : followed by a command name and arguments. For example:

:attach ~/photo.jpg Here is a picture
:read /etc/crontab

Some of the available commands are listed below; to see the full list, use :help commands in scli.

Command names are case insensitive, i.e. :edit and :eDiT do the same thing.

Modifying contacts

Modifying contacts from scli is possible if the account has been registered with signal-cli as a "primary device" (rather than linked with the phone app).

Searching

Filtering messages in a conversation is done by typing / followed by the search string. Pressing enter (or l) on a message when the search is on removes the filter (i.e. shows all the messages in a conversation) while keeping the focus on the message. Pressing Esc clears the search. Searching through contacts is analogous.

Configuration

Configuration options can be passed to scli as command-line arguments or added to the configuration file in ~/.config/sclirc. Run scli --help to show all available options.

Configuration file

Empty lines and lines starting with # are ignored. Config lines have the format OPTION = VALUE, where OPTIONs are the long forms of command-line arguments, with the leading -- omitted (e.g. enable-notifications). VALUEs for the optional arguments (a.k.a. "flags" or "switches") like --enable-notifications can be any of: true, t, yes, y (case insensitive, i.e. with any capitalization).

Example

scli --enable-notifications -w 80

Configuration file equivalent of the above command is:

enable-notifications = true
wrap-at = 80
### Short option forms (w = 80) are not valid in config file.

History

Conversations history can be enabled with --save-history or -s flag. The file will be saved in plain text (to ~/.local/share/scli/history by default). See the Security section regarding an encrypted storage.

Colors

Messages' text can be colorized using the --color option:

The list of available <signal_color> names is in the source code (first column). An <urwid_color> is one of urwid's 16 standard foreground colors (dark green, yellow, default, etc), or 256 foreground colors (#f8d, h123, etc). To see the available colors rendered in your terminal, run palette_test.py from urwid's examples. The single quotes in --color='...' above are just shell-escaping, and not needed in sclirc.

Security

This is an independent project not audited or endorsed by the Signal foundation. That is also true of signal-cli, which scli uses as a backend.

Data storage

Scli stores its history (if enabled with --save-history) in plain text. Likewise, signal-cli stores its data (received attachments, contacts info, encryption keys) unencrypted. To secure this data at rest, it is recommended to use full-disk encryption or dedicated tools like fscrypt.

To protect the data from potentially malicious programs running in user-space, one can run scli and signal-cli under a separate user.

For more detailed discussions, see: [1], [2].

Similar projects

Screenshots

scli scli scli