Quickstart

Getting up and running

While the experienced developer will most likely delve into the source code and compile it, this is not necessary. For just using signal-cli, only a few steps are necessary. signal-cli should work on all platforms supported by the Java Runtime. It works the same way on Linux, macOS, Windows. Only the installation will be different and the dbus daemon might not work on other platforms than Linux.

Prerequisites

• Java Runtime Environment (signal-cli requires at least JRE 21)
  • Debian 11: sudo apt-get install openjdk-17-jre
  • Ubuntu 22.04: sudo apt install openjdk-21-jre
  • Arch Linux: pacman -S jre-openjdk
  • Older distributions: Use an alternative JRE17 binary build (e.g. from https://adoptium.net/)
• signal-cli requires enough random entropy for cryptography. This can be an issue on embedded or idle systems, which can be resolved by installing an entropy daemon, like haveged.

Installation

Unpack a release from https://github.com/AsamK/signal-cli/releases, e.g. to ~/signal-cli.

Open a command line and change to the subdirectory bin where the release has been unpacked into:

cd ~/signal-cli/bin

Set up an account

For linking with an existing (master) device, see Linking-other-devices-(Provisioning). For registering a new master device, follow the steps below. Usually registration requires to solve a CAPTCHA, see Registration with captcha for more details.

Note: In Signal/signal-cli the account is called "username", which is slightly misleading, since it is a phone number including the country code. The used phone number is required for one-time verification of the installation. In this example I will use two German cell phone numbers, thus they will start with +491515...

1. Register your phone number Enter

./signal-cli -u +4915151111111 register

on the command line. If all goes well, there is no reply. Execution takes a few seconds. +491515111111 is thus the phone number that will be used by the signal-cli installation.

After a few seconds, you will receive an SMS on the cell phone with phone number +4915151111111 that contains the verification code (123-456 in this example):

SIGNAL: Your code is: 123-456 25 Feb. 2017 10:52

Note: You can register Signal using a land line number. In this case, you must first follow the normal verification procedure (as if it were a cell phone), wait 60s, then register again with the --voice switch at the end of above register command in order to receive an automated voice call.

If you do not try to register by SMS first (without --voice) or if you did not wait long enough, you will get this error message : Failed to register: [429] Rate limit exceeded: 429 (RateLimitException)

2. Verify your phone number Enter

./signal-cli -u +4915151111111 verify 123-456

on the command line. Again, no reply if all is fine.

Send a first message from the command line

We assume that the receiver of the message has the phone number +4915152222222. Enter

./signal-cli -u +4915151111111 send -m "My first message from the CLI" +4915152222222

on the command line. Again, no reply if all is fine.

Within a few seconds, the Signal App on the cell phone +4915152222222 will receive the message.

Send a first reply to the command line

With the same setup, enter a message (e.g. "First reply to the CLI") on the cell phone +4915152222222.

Enter

./signal-cli -u +4915151111111 receive

on the command line. This gets more output after a few seconds:

Envelope from: +4915152222222 (device: 1) Timestamp: 1488016532387 (2017-02-25T09:55:32.387Z) Message timestamp: 1488016532387 (2017-02-25T09:55:32.387Z) Body: First reply to the CLI

Envelope from: +4915152222222 (device: 1) Timestamp: 1488017026720 (2017-02-25T10:03:46.720Z) Got receipt.

The message is contained in the line starting with

Body:

Extra links and guides

Automate the installation

A Python script to automate the installation of signal-cli for using with the DBus service. This scripts installs signal-cli, setup the DBus service and helps you add an account (either as master or slave device). Must be run with superuser rights ('sudo').

Use signal-cli to register an account without a phone and link with Signal-desktop

• A short guide for registering a new account with signal-cli on windows, and linking it with signal-desktop.
• Guide for old version of signal-desktop (pre-electron). To get to the html source described there in the current signal-desktop, go to View -> Toggle Developer Tools

Upgrades

Backup

It is advised to backup the account databases before upgrading to a newer version which might migrate the database and therefore prevents a downgrade in case of issues.

This little snippet will take care (requires squlite3).

find /folder/to/signal-cli/data -type f -name account.db | xargs -L1 -I{} sqlite3 {} ".backup {}.$(date +%Y%m%d%H%M)"