scli

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

Features

• vim-like navigation (j, k, g, G, etc), command entry with :
• optional emacs-like readline bindings for input
• external $EDITOR support

Limitations

• Not yet supported by signal-cli:

  • Quoting a message (#213)
  • Adding @-mentions in sent messages (#584)
  • Voice calls (#80)

• Sending read receipts for received messages.

• "View once" and "expiring" messages.

• See also: open issues.

Installation

Automatic

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

Manual

Clone the repo

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

or download a release.

Dependencies

• signal-cli >=v0.6.8.

  Download and unpack a release, and place the signal-cli executable somewhere on the $PATH.

  Or compile from source: see install section of signal-cli readme for instructions.

• urwid

  Availble on PyPI:

  pip install urwid
  

  and in some distributions' package managers, see repology (1), (2).

• urwid_readline (optional)

  For GNU readline-like keybinds on the input line (emacs-like only).

  pip install urwid-readline
  

  Also in a few package managers.

• DBus

  Pre-installed on most linux distributions and BSDs with desktop environments. On macOS, the dbus package is available from homebrew, see signal-cli's wiki. See also, wiki's troubleshooting section.

• Python >=3.7

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 and including your country calling code). Kill the latter process after verifying that it starts successfully and does not throw any errors.

Now you can start

scli

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

Usage

A simple two-paned interface is provided. Left pane contains the contact list and right pane contains current conversation. You can switch focus between panes with Tab (or Shift + Tab). Hitting tab for the first time focuses the conversation, hitting it again focuses to input line. So the focus order is Contacts -> Conversation -> Input. You can use Shift + Tab for cycling backwards.

Keys

• Use j/k to go down/up in contacts list or in messages.
• Hitting enter on a contact opens the conversation and focuses to input line.
• Hitting l on a contact only opens the conversation.
• Hitting o on a message opens the URL if there is one, if not it opens the attachment if there is one.
• Hitting enter on a message opens the attachment if there is one, if not it opens the URL if there is one.
• Hitting y on a message puts it into system clipboard. (needs xclip)
• g focuses first contact/message.
• G focuses last contact/message.
• d deletes the message from your screen (and from your history, if history is enabled).
• i show a popup that contains detailed information about the message.
• Alt+Enter inserts a newline in message composing input field.
• Alt+J / Alt+K (and Alt+↓ / Alt+↑) open next / previous conversation.

Commands

There are some basic commands that you can use. Hit : to enter command mode (or simply focus the input line and type :).

• :edit or :e lets you edit your message in your $EDITOR.
• :attach FILE_PATH or :a FILE_PATH attaches given file to message.
• :attachClip or :c attaches clipboard content to message. This command tries to detect clipboard content. If clipboard contains something with the mime-type image/png or image/jpg, simply attaches the image to message. If clipboard contains text/uri-list it attaches all the files in that URI list to your message. This command needs xclip installed.
• :openUrl or :u opens last URL in messages, if there is one.
• :openAttach or :o opens last attachment in messages, if there is one.
• :toggleNotifications or :n toggles desktop notifications.
• :toggleContactsSort or :s toggles between sorting contacts alphabetically and by the most recent message.
• :toggleAutohide or :h hides the contacts pane when it's not in focus.
• :addContact NUMBER [NAME] adds a new contact to the contact list. Added contacts' names are local (not synced with signal servers).
  Note: This command works only with signal-cli accounts registered as "master" (not those linked with the phone app).
• :renameContact [ID] NEW_NAME renames contact ID to NEW_NAME. ID can be either contact's phone number or contact's name. If ID is skipped, the contact from the currently opened conversation is used. If ID is a name that contains spaces, they need to be escaped or the whole name put in quotes. NEW_NAME can contain spaces without quotes or escaping. 'Contact' can be a group as well as an individual. Individual contacts' renames are local (not synced with the signal servers).
  See Note for :addContact command above.
• :reload re-reads the signal-clis data file. (Updates contacts list etc.)
• :quit or :q quits the program.

Examples:

:attach ~/cute_dog.png check out this cute dog!
:attachclip here is another picture.

Note: Commands are case insensitive, :quit and :qUiT do the same thing.

Searching

There is a built-in search feature. Simply hit / while you are on the chat window (or focus the input line then type /) and start typing, the chat will be filtered out based on your input. You can focus any of the search results and hit enter (or l) to open that result in full conversation.

For searching through contacts, you need to hit / while you are on the contacts window and start typing, contacts will be filtered out while you are typing. Hit enter to focus the results. Hitting Esc will clear the search.

Configuration

There are some simple configuration options. You can either pass them as command-line arguments or add them to your configuration file ~/.config/sclirc. Run scli --help to see all options.

Configuration file syntax is also pretty easy. Lines starting with # and empty lines are ignored, other lines are key = value pairs. Optional arguments (flags) like --debug, can be enabled in config file with any of: true, t, yes, y (with any capitalization, case insensitive).

Example

scli -w 80 --enable-notifications

Configuration file equivalent of this command is:

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

History

Conversations history can be enabled with --save-history or -s flag. If enabled, the file is saved in plain text (to ~/.local/share/scli/history by default).

Colors

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

• --color (no additional value) Use contacts' colors from the master signal device.

• --color=high Same as above, but use 256 colors instead of the terminal's standard 8. Colors look closer to those on official clients, but not necessarily legible on all terminals' color schemes.

• --color='{"<signal_color>": "<urwid_color>", ..., "<phone_number>": "<urwid_color>", ...}' Override colors for particular contacts or redefine signal-assigned colors; use signal-assigned colors for the rest, as above. If any of the <urwid_color>s is specified as a 256-color, the "high-color mode" will be turned on (like --color=high).

• --color='["<urwid_color_sent>", "<urwid_color_recv>"]' Use one color for sent messages and another for received messages (from any contact).

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.

Similar projects

See TUI clients on signal-cli wiki.

Screenshots