nmode's Git Repositories - signal-cli/blob - README.md

   1 # signal-cli
   2
   3 signal-cli is a commandline interface for the [Signal messenger](https://signal.org/).
   4 It supports registering, verifying, sending and receiving messages.
   5 signal-cli uses a [patched libsignal-service-java](https://github.com/Turasa/libsignal-service-java),
   6 extracted from the [Signal-Android source code](https://github.com/signalapp/Signal-Android/tree/main/libsignal/service).
   7 For registering you need a phone number where you can receive SMS or incoming calls.
   8
   9 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 D-BUS
  10 interface ([man page](https://github.com/AsamK/signal-cli/blob/master/man/signal-cli-dbus.5.adoc)) and JSON-RPC interface ([documentation](https://github.com/AsamK/signal-cli/wiki/JSON-RPC-service)).
  11 For the JSON-RPC interface there's also a simple [example client](https://github.com/AsamK/signal-cli/tree/master/client), written in Rust.
  12
  13 ## Installation
  14
  15 You can [build signal-cli](#building) yourself or use
  16 the [provided binary files](https://github.com/AsamK/signal-cli/releases/latest), which should work on Linux, macOS and
  17 Windows. There's also a [docker image and some Linux packages](https://github.com/AsamK/signal-cli/wiki/Binary-distributions) provided by the community.
  18
  19 System requirements:
  20
  21 - at least Java Runtime Environment (JRE) 17
  22 - native library: libsignal-client
  23
  24   The native libs are bundled for x86_64 Linux (with recent enough glibc), Windows and MacOS. For other
  25   systems/architectures
  26   see: [Provide native lib for libsignal](https://github.com/AsamK/signal-cli/wiki/Provide-native-lib-for-libsignal)
  27
  28 ### Install system-wide on Linux
  29
  30 See [latest version](https://github.com/AsamK/signal-cli/releases).
  31
  32 ```sh
  33 export VERSION=<latest version, format "x.y.z">
  34 wget https://github.com/AsamK/signal-cli/releases/download/v"${VERSION}"/signal-cli-"${VERSION}"-Linux.tar.gz
  35 sudo tar xf signal-cli-"${VERSION}"-Linux.tar.gz -C /opt
  36 sudo ln -sf /opt/signal-cli-"${VERSION}"/bin/signal-cli /usr/local/bin/
  37 ```
  38
  39 You can find further instructions on the Wiki:
  40
  41 - [Quickstart](https://github.com/AsamK/signal-cli/wiki/Quickstart)
  42 - [DBus Service](https://github.com/AsamK/signal-cli/wiki/DBus-service)
  43
  44 ## Usage
  45
  46 For a complete usage overview please read
  47 the [man page](https://github.com/AsamK/signal-cli/blob/master/man/signal-cli.1.adoc) and
  48 the [wiki](https://github.com/AsamK/signal-cli/wiki).
  49
  50 Important: The ACCOUNT is your phone number in international format and must include the country calling code. Hence it
  51 should start with a "+" sign. (See [Wikipedia](https://en.wikipedia.org/wiki/List_of_country_calling_codes) for a list
  52 of all country codes.)
  53
  54 * Register a number (with SMS verification)
  55
  56         signal-cli -a ACCOUNT register
  57
  58   You can register Signal using a landline number. In this case you can skip SMS verification process and jump directly
  59   to the voice call verification by adding the `--voice` switch at the end of above register command.
  60
  61   Registering may require solving a CAPTCHA
  62   challenge: [Registration with captcha](https://github.com/AsamK/signal-cli/wiki/Registration-with-captcha)
  63
  64 * Verify the number using the code received via SMS or voice, optionally add `--pin PIN_CODE` if you've added a pin code
  65   to your account
  66
  67         signal-cli -a ACCOUNT verify CODE
  68
  69 * Send a message
  70
  71         signal-cli -a ACCOUNT send -m "This is a message" RECIPIENT
  72
  73 * Pipe the message content from another process.
  74
  75         uname -a | signal-cli -a ACCOUNT send --message-from-stdin RECIPIENT
  76
  77 * Receive messages
  78
  79         signal-cli -a ACCOUNT receive
  80
  81 **Hint**: The Signal protocol expects that incoming messages are regularly received (using `daemon` or `receive`
  82 command). This is required for the encryption to work efficiently and for getting updates to groups, expiration timer
  83 and other features.
  84
  85 ## Storage
  86
  87 The password and cryptographic keys are created when registering and stored in the current users home directory:
  88
  89         $XDG_DATA_HOME/signal-cli/data/
  90         $HOME/.local/share/signal-cli/data/
  91
  92 ## Building
  93
  94 This project uses [Gradle](http://gradle.org) for building and maintaining dependencies. If you have a recent gradle
  95 version installed, you can replace `./gradlew` with `gradle` in the following steps.
  96
  97 1. Checkout the source somewhere on your filesystem with
  98
  99         git clone https://github.com/AsamK/signal-cli.git
 100
 101 2. Execute Gradle:
 102
 103         ./gradlew build
 104
 105    2a. Create shell wrapper in *build/install/signal-cli/bin*:
 106
 107         ./gradlew installDist
 108
 109    2b. Create tar file in *build/distributions*:
 110
 111         ./gradlew distTar
 112
 113    2c. Create a fat tar file in *build/libs/signal-cli-fat*:
 114
 115         ./gradlew fatJar
 116
 117    2d. Compile and run signal-cli:
 118
 119         ./gradlew run --args="--help"
 120
 121 ### Building a native binary with GraalVM (EXPERIMENTAL)
 122
 123 It is possible to build a native binary with [GraalVM](https://www.graalvm.org). This is still experimental and will not
 124 work in all situations.
 125
 126 1. [Install GraalVM and setup the enviroment](https://www.graalvm.org/docs/getting-started/#install-graalvm)
 127 2. [Install prerequisites](https://www.graalvm.org/reference-manual/native-image/#prerequisites)
 128 3. Execute Gradle:
 129
 130         ./gradlew nativeCompile
 131
 132    The binary is available at *build/native/nativeCompile/signal-cli*
 133
 134 ## FAQ and Troubleshooting
 135
 136 For frequently asked questions and issues have a look at the [wiki](https://github.com/AsamK/signal-cli/wiki/FAQ)
 137
 138 ## License
 139
 140 This project uses libsignal-service-java from Open Whisper Systems:
 141
 142 https://github.com/WhisperSystems/libsignal-service-java
 143
 144 Licensed under the GPLv3: http://www.gnu.org/licenses/gpl-3.0.html