nmode's Git Repositories - signal-cli/blob - man/signal-cli.1.adoc

   1 /////
   2 vim:set ts=4 sw=4 tw=82 noet:
   3 /////
   4 :quotes.~:
   5
   6 = signal-cli (1)
   7
   8 Name
   9 ----
  10 signal-cli - A commandline and dbus interface for the Signal messenger
  11
  12 Synopsis
  13 --------
  14 *signal-cli* [--config CONFIG] [-h | -v | -u USERNAME | --dbus | --dbus-system] command [command-options]
  15
  16 Description
  17 -----------
  18
  19 signal-cli is a commandline interface for libsignal-service-java. It supports
  20 registering, verifying, sending and receiving messages. For registering you need a
  21 phone number where you can receive SMS or incoming calls.
  22 signal-cli was primarily developed to be used on servers to notify admins of
  23 important events. For this use-case, it has a dbus interface, that can be used to
  24 send messages from any programming language that has dbus bindings.
  25
  26 Options
  27 -------
  28
  29 *-h*, *--help*::
  30         Show help message and quit.
  31
  32 *-v*, *--version*::
  33         Print the version and quit.
  34
  35 *--config* CONFIG::
  36         Set the path, where to store the config.
  37         Make sure you have full read/write access to the given directory.
  38         (Default: `$XDG_DATA_HOME/signal-cli` (`$HOME/.local/share/signal-cli`))
  39
  40 *-u* USERNAME, *--username* USERNAME::
  41         Specify your phone number, that will be your identifier.
  42         The phone number must include the country calling code, i.e. the number must
  43         start with a "+" sign.
  44
  45 *--dbus*::
  46         Make request via user dbus.
  47
  48 *--dbus-system*::
  49         Make request via system dbus.
  50
  51 Commands
  52 --------
  53
  54 register
  55 ~~~~~~~~
  56 Register a phone number with SMS or voice verification. Use the verify command to
  57 complete the verification.
  58
  59 *-v*, *--voice*::
  60         The verification should be done over voice, not SMS.
  61
  62 verify
  63 ~~~~~~
  64 Verify the number using the code received via SMS or voice.
  65
  66 VERIFICATIONCODE::
  67         The verification code.
  68
  69 *-p* PIN, *--pin* PIN::
  70         The registration lock PIN, that was set by the user. Only required if a PIN was set.
  71
  72 unregister
  73 ~~~~~~~~~~
  74 Disable push support for this device, i.e. this device won't receive any more messages.
  75 If this is the master device, other users can't send messages to this number anymore.
  76 Use "updateAccount" to undo this.
  77 To remove a linked device, use "removeDevice" from the master device.
  78
  79 updateAccount
  80 ~~~~~~~~~~~~~
  81 Update the account attributes on the signal server.
  82 Can fix problems with receiving messages.
  83
  84 setPin
  85 ~~~~~~
  86 Set a registration lock pin, to prevent others from registering this number.
  87
  88 REGISTRATION_LOCK_PIN::
  89     The registration lock PIN, that will be required for new registrations (resets after 7 days of inactivity)
  90
  91 removePin
  92 ~~~~~~~~~
  93 Remove the registration lock pin.
  94
  95 link
  96 ~~~~
  97 Link to an existing device, instead of registering a new number.  This shows a
  98 "tsdevice:/…" URI. If you want to connect to another signal-cli instance, you can
  99 just use this URI. If you want to link to an Android/iOS device, create a QR code
 100 with the URI (e.g. with qrencode) and scan that in the Signal app.
 101
 102 *-n* NAME, *--name* NAME::
 103         Optionally specify a name to describe this new device. By default "cli" will
 104         be used.
 105
 106 addDevice
 107 ~~~~~~~~~
 108 Link another device to this device. Only works, if this is the master device.
 109
 110 *--uri* URI::
 111         Specify the uri contained in the QR code shown by the new device.
 112
 113 listDevices
 114 ~~~~~~~~~~~
 115 Show a list of connected devices.
 116
 117 removeDevice
 118 ~~~~~~~~~~~~
 119 Remove a connected device. Only works, if this is the master device.
 120
 121 *-d* DEVICEID, *--deviceId* DEVICEID::
 122         Specify the device you want to remove. Use listDevices to see the deviceIds.
 123
 124 send
 125 ~~~~
 126 Send a message to another user or group.
 127
 128 RECIPIENT::
 129         Specify the recipients’ phone number.
 130
 131 *-g* GROUP, *--group* GROUP::
 132         Specify the recipient group ID in base64 encoding.
 133
 134 *-m* MESSAGE, *--message* MESSAGE::
 135         Specify the message, if missing, standard input is used.
 136
 137 *-a* [ATTACHMENT [ATTACHMENT ...]], *--attachment* [ATTACHMENT [ATTACHMENT ...]]::
 138         Add one or more files as attachment.
 139
 140 *-e*, *--endsession*::
 141         Clear session state and send end session message.
 142
 143 sendReaction
 144 ~~~~~~~~~~~~
 145 Send reaction to a previously received or sent message.
 146
 147 RECIPIENT::
 148         Specify the recipients’ phone number.
 149
 150 *-g* GROUP, *--group* GROUP::
 151         Specify the recipient group ID in base64 encoding.
 152
 153 *-e* EMOJI, *--emoji* EMOJI::
 154         Specify the emoji, should be a single unicode grapheme cluster.
 155
 156 *-a* NUMBER, *--target-author* NUMBER::
 157         Specify the number of the author of the message to which to react.
 158
 159 *-t* TIMESTAMP, *--target-timestamp* TIMESTAMP::
 160         Specify the timestamp of the message to which to react.
 161
 162 *-r*, *--remove*::
 163         Remove a reaction.
 164
 165 receive
 166 ~~~~~~~
 167 Query the server for new messages. New messages are printed on standardoutput and
 168 attachments are downloaded to the config directory.
 169
 170 *-t* TIMEOUT, *--timeout* TIMEOUT::
 171         Number of seconds to wait for new messages (negative values disable timeout).
 172         Default is 5 seconds.
 173 *--ignore-attachments*::
 174         Don’t download attachments of received messages.
 175 *--json*::
 176         Output received messages in json format, one object per line.
 177
 178 updateGroup
 179 ~~~~~~~~~~~
 180 Create or update a group.
 181
 182 *-g* GROUP, *--group* GROUP::
 183         Specify the recipient group ID in base64 encoding. If not specified, a new
 184         group with a new random ID is generated.
 185
 186 *-n* NAME, *--name* NAME::
 187         Specify the new group name.
 188
 189 *-a* AVATAR, *--avatar* AVATAR::
 190         Specify a new group avatar image file.
 191
 192 *-m* [MEMBER [MEMBER ...]], *--member* [MEMBER [MEMBER ...]]::
 193         Specify one or more members to add to the group.
 194
 195 quitGroup
 196 ~~~~~~~~~
 197 Send a quit group message to all group members and remove self from member list.
 198
 199 *-g* GROUP, *--group* GROUP::
 200         Specify the recipient group ID in base64 encoding.
 201
 202 listGroups
 203 ~~~~~~~~~~~
 204 Show a list of known groups.
 205
 206 *-d*, *--detailed*::
 207         Include the list of members of each group.
 208
 209 listIdentities
 210 ~~~~~~~~~~~~~~
 211 List all known identity keys and their trust status, fingerprint and safety
 212 number.
 213
 214 *-n* NUMBER, *--number* NUMBER::
 215         Only show identity keys for the given phone number.
 216
 217 trust
 218 ~~~~~
 219 Set the trust level of a given number. The first time a key for a number is seen,
 220 it is trusted by default (TOFU). If the key changes, the new key must be trusted
 221 manually.
 222
 223 number::
 224         Specify the phone number, for which to set the trust.
 225
 226 *-a*, *--trust-all-known-keys*::
 227         Trust all known keys of this user, only use this for testing.
 228
 229 *-v* VERIFIED_FINGERPRINT, *--verified-fingerprint* VERIFIED_FINGERPRINT::
 230         Specify the safety number or fingerprint of the key, only use this option if you have verified
 231         the fingerprint.
 232
 233 updateProfile
 234 ~~~~~~~~~~~~~
 235 Update the name and/or avatar image visible by message recipients for the current users.
 236 The profile is stored encrypted on the Signal servers. The decryption key is sent
 237 with every outgoing messages (excluding group messages).
 238
 239 *--name*::
 240         New name visible by message recipients.
 241
 242 *--avatar*::
 243         Path to the new avatar visible by message recipients.
 244
 245 *--remove-avatar*::
 246         Remove the avatar visible by message recipients.
 247
 248 updateContact
 249 ~~~~~~~~~~~~~
 250 Update the info associated to a number on our contact list. This change is only
 251 local but can be synchronized to other devices by using `sendContacts` (see
 252 below).
 253 If the contact doesn't exist yet, it will be added.
 254
 255 NUMBER::
 256         Specify the contact phone number.
 257
 258 *-n*, *--name*::
 259         Specify the new name for this contact.
 260
 261 block
 262 ~~~~~
 263 Block the given contacts or groups (no messages will be received). This change is only
 264 local but can be synchronized to other devices by using `sendContacts` (see
 265 below).
 266
 267 [CONTACT [CONTACT ...]]::
 268         Specify the phone numbers of contacts that should be blocked.
 269
 270 *-g* [GROUP [GROUP ...]], *--group* [GROUP [GROUP ...]]::
 271         Specify the group IDs that should be blocked in base64 encoding.
 272
 273 unblock
 274 ~~~~~~~
 275 Unblock the given contacts or groups (messages will be received again). This change is only
 276 local but can be synchronized to other devices by using `sendContacts` (see
 277 below).
 278
 279 [CONTACT [CONTACT ...]]::
 280 Specify the phone numbers of contacts that should be unblocked.
 281
 282 *-g* [GROUP [GROUP ...]], *--group* [GROUP [GROUP ...]]::
 283 Specify the group IDs that should be unblocked in base64 encoding.
 284
 285 sendContacts
 286 ~~~~~~~~~~~~
 287 Send a synchronization message with the local contacts list to all linked devices.
 288 This command should only be used if this is the master device.
 289
 290 uploadStickerPack
 291 ~~~~~~~~~~~~~~~~~
 292 Upload a new sticker pack, consisting of a manifest file and the stickers in WebP
 293 format (maximum size for a sticker file is 100KiB).
 294 The required manifest.json has the following format:
 295
 296 ```json
 297 {
 298   "title": "<STICKER_PACK_TITLE>",
 299   "author": "<STICKER_PACK_AUTHOR>",
 300   "cover": { // Optional cover, by default the first sticker is used as cover
 301     "file": "<name of webp file, mandatory>",
 302     "emoji": "<optional>"
 303   },
 304   "stickers": [
 305     {
 306       "file": "<name of webp file, mandatory>",
 307       "emoji": "<optional>"
 308     }
 309     ...
 310   ]
 311 }
 312 ```
 313
 314 PATH::
 315         The path of the manifest.json or a zip file containing the sticker pack you
 316         wish to upload.
 317
 318 daemon
 319 ~~~~~~
 320 signal-cli can run in daemon mode and provides an experimental dbus interface. For
 321 dbus support you need jni/unix-java.so installed on your system (Debian:
 322 libunixsocket-java ArchLinux: libmatthew-unix-java (AUR)).
 323
 324 *--system*::
 325         Use DBus system bus instead of user bus.
 326 *--ignore-attachments*::
 327         Don’t download attachments of received messages.
 328
 329
 330 Examples
 331 --------
 332
 333 Register a number (with SMS verification)::
 334     signal-cli -u USERNAME register
 335
 336 Verify the number using the code received via SMS or voice::
 337     signal-cli -u USERNAME verify CODE
 338
 339 Send a message to one or more recipients::
 340     signal-cli -u USERNAME send -m "This is a message" [RECIPIENT [RECIPIENT ...]] [-a [ATTACHMENT [ATTACHMENT ...]]]
 341
 342 Pipe the message content from another process::
 343     uname -a | signal-cli -u USERNAME send [RECIPIENT [RECIPIENT ...]]
 344
 345 Create a group::
 346         signal-cli -u USERNAME updateGroup -n "Group name" -m [MEMBER [MEMBER ...]]
 347
 348 Add member to a group::
 349         signal-cli -u USERNAME updateGroup -g GROUP_ID -m "NEW_MEMBER"
 350
 351 Leave a group::
 352         signal-cli -u USERNAME quitGroup -g GROUP_ID
 353
 354 Send a message to a group::
 355         signal-cli -u USERNAME send -m "This is a message" -g GROUP_ID
 356
 357 Trust new key, after having verified it::
 358     signal-cli -u USERNAME trust -v FINGER_PRINT NUMBER
 359
 360 Trust new key, without having verified it. Only use this if you don't care about security::
 361     signal-cli -u USERNAME trust -a NUMBER
 362
 363 Files
 364 -----
 365 The password and cryptographic keys are created when registering and stored in the
 366 current users home directory, the directory can be changed with *--config*:
 367
 368 `$XDG_DATA_HOME/signal-cli/` (`$HOME/.local/share/signal-cli/`)
 369
 370 For legacy users, the old config directories are used as a fallback:
 371
 372     $HOME/.config/signal/
 373
 374     $HOME/.config/textsecure/
 375
 376
 377 Authors
 378 -------
 379
 380 Maintained by AsamK <asamk@gmx.de>, who is assisted by other open
 381 source contributors. For more information about signal-cli development, see
 382 <https://github.com/AsamK/signal-cli>.