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 installed
  • Ubuntu/Debian: sudo apt-get install default-jre
  • Arch Linux: pacman -S jre-openjdk
• signal-cli requires unlimited strength crypto in Java Runtime Environment to be turned on. Newer versions of Java have this feature already turned on by default. But for Java versions older then Java 8u161, Java 7u171 or Java 6u181 see this StackOverflow answer how to enable it. You can check your current installed Java Runtime Environment with command: java -version
• 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.

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):

Your TextSecure verification code: 123-456 25 Feb. 2017 10:52

Note: You can register Signal using a land line number. In this case you can skip SMS verification process and jump directly to the voice call verification by adding the --voice switch at the end of above register command.

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

Resolving DBus issues on FreeBSD

If using the dbus functionality on FreeBSD throws errors, you might need to set the DBUS_SESSION_BUS_ADDRESS variable. Detailed instructions in a blog post.