gem-hunter
Language: Java
signal-cli provides an unofficial commandline, JSON-RPC and dbus interface for the Signal messenger.
signal-cli is a commandline interface for the Signal messenger. It supports registering, verifying, sending and receiving messages. signal-cli uses a patched libsignal-service-java, extracted from the Signal-Android source code. For registering you need a phone number where you can receive SMS or incoming calls. Existing accounts without a phone number can be linked from a compatible Signal mobile app.
signal-cli is primarily intended to be used on servers to notify admins of important events. For this use-case, it has a daemon mode with JSON-RPC interface (man page) and D-BUS interface (man page). For the JSON-RPC interface there's also a simple example client, written in Rust.
signal-cli needs to be kept up-to-date to keep up with Signal-Server changes. The official Signal clients expire after three months and then the Signal-Server can make incompatible changes. So signal-cli releases older than three months may not work correctly.
You can build signal-cli yourself or use the provided binary files, which should work on Linux, macOS and Windows. There's also a docker image and some Linux packages provided by the community.
System requirements:
at least Java Runtime Environment (JRE) 25
native library: libsignal-client
The native libs are bundled for x86_64 Linux (with recent enough glibc), Windows and MacOS. For other systems/architectures see: Provide native lib for libsignal
See latest version.
VERSION=$(curl -Ls -o /dev/null -w %{url_effective} https://github.com/AsamK/signal-cli/releases/latest | sed -e 's/^.*\/v//') curl -L -O https://github.com/AsamK/signal-cli/releases/download/v"${VERSION}"/signal-cli-"${VERSION}".tar.gz sudo tar xf signal-cli-"${VERSION}".tar.gz -C /opt sudo ln -sf /opt/signal-cli-"${VERSION}"/bin/signal-cli /usr/local/bin/
VERSION=$(curl -Ls -o /dev/null -w %{url_effective} https://github.com/AsamK/signal-cli/releases/latest | sed -e 's/^.*\/v//') curl -L -O https://github.com/AsamK/signal-cli/releases/download/v"${VERSION}"/signal-cli-"${VERSION}"-Linux-native.tar.gz sudo tar xf signal-cli-"${VERSION}"-Linux-native.tar.gz -C /opt sudo ln -sf /opt/signal-cli /usr/local/bin/
You can find further instructions on the Wiki:
For a complete usage overview please read the man page and the wiki.
For a numbered account, ACCOUNT is your phone number in international format and must include the country calling code. Hence it should start with a "+" sign. (See Wikipedia for a list of all country codes.) For a linked account without a phone number, use its ACI (Account ID) instead. See the wiki for further documentation.
Link to an existing account
If you have an existing Signal account, with or without a phone number, you can link signal-cli to it with:
signal-cli link
Register a number (with SMS verification)
Alternatively, if you don't have an existing Signal account, you can register one from signal-cli. Note that this will unregister any existing client associated with the same number.
signal-cli -a ACCOUNT register
You can register Signal using a landline number. In this case, you need to follow the procedure below:
Attempt a SMS verification process first (signal-cli -a ACCOUNT register)
400 (InvalidTransportModeException), this is normalWait 60 seconds
Attempt a voice call verification by adding the --voice switch and wait for the call:
signal-cli -a ACCOUNT register --voice
Registering may require solving a CAPTCHA challenge: Registration with captcha
Verify the number using the code received via SMS or voice, optionally add --pin PIN_CODE if you've added a pin code
to your account
signal-cli -a ACCOUNT verify CODE
Send a message
signal-cli -a ACCOUNT send -m "This is a message" RECIPIENTSend a message to a username, usernames need to be prefixed with u:
signal-cli -a ACCOUNT send -m "This is a message" u:USERNAME.000Pipe the message content from another process.
uname -a | signal-cli -a ACCOUNT send --message-from-stdin RECIPIENT
Receive messages
signal-cli -a ACCOUNT receive
Hint: The Signal protocol expects that incoming messages are regularly received (using daemon or receive
command). This is required for the encryption to work efficiently and for getting updates to groups, expiration timer
and other features.
The password and cryptographic keys are created when registering and stored in the current users home directory:
$XDG_DATA_HOME/signal-cli/data/
$HOME/.local/share/signal-cli/data/
This project uses Gradle for building and maintaining dependencies. If you have a recent gradle
version installed, you can replace ./gradlew with gradle in the following steps.
Checkout the source somewhere on your filesystem with
git clone https://github.com/AsamK/signal-cli.git
Execute Gradle:
./gradlew build
2a. Create shell wrapper in build/install/signal-cli/bin:
./gradlew installDist
2b. Create tar file in build/distributions:
./gradlew distTar
2c. Create a fat tar file in build/libs/signal-cli-fat:
./gradlew fatJar
2d. Compile and run signal-cli:
./gradlew run --args="--help"Generate JSON Schema files for all the JSON-RPC data classes (src/main/java/org/asamk/signal/json):
./gradlew jsonSchemas
The generated files can be found in the build/generated/META-INF/schemas folder.
It is possible to build a native binary with GraalVM. This is still experimental and will not work in all situations.
Execute Gradle:
./gradlew nativeCompile
The binary is available at build/native/nativeCompile/signal-cli
For frequently asked questions and issues have a look at the wiki.
This project uses libsignal-service-java from Open Whisper Systems:
https://github.com/WhisperSystems/libsignal-service-java
Licensed under the GPLv3: http://www.gnu.org/licenses/gpl-3.0.html