scli
is a simple terminal user interface for Signal. It uses signal-cli and urwid.
- vim-like navigation (
j
,k
,g
,G
, etc), command entry with:
- optional emacs-like
readline
bindings for input - external
$EDITOR
support
- "View once" or "expiring" message properties are not honored.
- Sending read receipts for received messages (#231, #305)
- Quoting a message (#213)
- Adding @-mentions in sent messages (#584)
- Voice calls (#80)
- Sending a "view once" or "expiring" messages.
Clone the repo
git clone https://github.com/isamert/scli
or download a release.
-
signal-cli
>=v0.6.8
. (Latest testedv0.8.1
)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. -
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.
-
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
The following methods are supported by community and may be outdated.
- Arch Linux: AUR
- FreeBSD: FreshPorts
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 also be done with scli link
, see below.
See also: signal-cli
usage, man page, and wiki.
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
.
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)
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.
- 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. (needsxclip
) 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
opens next / previous conversation.
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-typeimage/png
orimage/jpg
, simply attaches the image to message. If clipboard containstext/uri-list
it attaches all the files in that URI list to your message. This command needsxclip
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: For linked accounts (e.g. with a master signal app on the phone) the local changes to contacts will be overwritten on periodic syncs with the master device; see #119.:renameContact [ID] NEW_NAME
renames contactID
toNEW_NAME
.ID
can be either contact's phone number or contact's name. IfID
is skipped, the contact from the currently opened conversation is used. IfID
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 in:addContact
above).:reload
re-reads thesignal-cli
s 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.
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.
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).
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
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).
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
.
See TUI clients on signal-cli wiki.