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 receive
 144 ~~~~~~~
 145 Query the server for new messages. New messages are printed on standardoutput and
 146 attachments are downloaded to the config directory.
 147
 148 *-t* TIMEOUT, *--timeout* TIMEOUT::
 149         Number of seconds to wait for new messages (negative values disable timeout).
 150         Default is 5 seconds.
 151 *--ignore-attachments*::
 152         Don’t download attachments of received messages.
 153 *--json*::
 154         Output received messages in json format, one object per line.
 155
 156 updateGroup
 157 ~~~~~~~~~~~
 158 Create or update a group.
 159
 160 *-g* GROUP, *--group* GROUP::
 161         Specify the recipient group ID in base64 encoding. If not specified, a new
 162         group with a new random ID is generated.
 163
 164 *-n* NAME, *--name* NAME::
 165         Specify the new group name.
 166
 167 *-a* AVATAR, *--avatar* AVATAR::
 168         Specify a new group avatar image file.
 169
 170 *-m* [MEMBER [MEMBER ...]], *--member* [MEMBER [MEMBER ...]]::
 171         Specify one or more members to add to the group.
 172
 173 quitGroup
 174 ~~~~~~~~~
 175 Send a quit group message to all group members and remove self from member list.
 176
 177 *-g* GROUP, *--group* GROUP::
 178         Specify the recipient group ID in base64 encoding.
 179
 180 listGroups
 181 ~~~~~~~~~~~
 182 Show a list of known groups.
 183
 184 *-d*, *--detailed*::
 185         Include the list of members of each group.
 186
 187 listIdentities
 188 ~~~~~~~~~~~~~~
 189 List all known identity keys and their trust status, fingerprint and safety
 190 number.
 191
 192 *-n* NUMBER, *--number* NUMBER::
 193         Only show identity keys for the given phone number.
 194
 195 trust
 196 ~~~~~
 197 Set the trust level of a given number. The first time a key for a number is seen,
 198 it is trusted by default (TOFU). If the key changes, the new key must be trusted
 199 manually.
 200
 201 number::
 202         Specify the phone number, for which to set the trust.
 203
 204 *-a*, *--trust-all-known-keys*::
 205         Trust all known keys of this user, only use this for testing.
 206
 207 *-v* VERIFIED_FINGERPRINT, *--verified-fingerprint* VERIFIED_FINGERPRINT::
 208         Specify the safety number or fingerprint of the key, only use this option if you have verified
 209         the fingerprint.
 210
 211 updateProfile
 212 ~~~~~~~~~~~~~
 213 Update the name and/or avatar image visible by message recipients for the current users.
 214 The profile is stored encrypted on the Signal servers. The decryption key is sent
 215 with every outgoing messages (excluding group messages).
 216
 217 *--name*::
 218         New name visible by message recipients.
 219
 220 *--avatar*::
 221         Path to the new avatar visible by message recipients.
 222
 223 *--remove-avatar*::
 224         Remove the avatar visible by message recipients.
 225
 226 updateContact
 227 ~~~~~~~~~~~~~
 228 Update the info associated to a number on our contact list. This change is only
 229 local but can be synchronized to other devices by using `sendContacts` (see
 230 below).
 231 If the contact doesn't exist yet, it will be added.
 232
 233 NUMBER::
 234         Specify the contact phone number.
 235
 236 *-n*, *--name*::
 237         Specify the new name for this contact.
 238
 239 block
 240 ~~~~~
 241 Block the given contacts or groups (no messages will be received). This change is only
 242 local but can be synchronized to other devices by using `sendContacts` (see
 243 below).
 244
 245 [CONTACT [CONTACT ...]]::
 246         Specify the phone numbers of contacts that should be blocked.
 247
 248 *-g* [GROUP [GROUP ...]], *--group* [GROUP [GROUP ...]]::
 249         Specify the group IDs that should be blocked in base64 encoding.
 250
 251 unblock
 252 ~~~~~~~
 253 Unblock the given contacts or groups (messages will be received again). This change is only
 254 local but can be synchronized to other devices by using `sendContacts` (see
 255 below).
 256
 257 [CONTACT [CONTACT ...]]::
 258 Specify the phone numbers of contacts that should be unblocked.
 259
 260 *-g* [GROUP [GROUP ...]], *--group* [GROUP [GROUP ...]]::
 261 Specify the group IDs that should be unblocked in base64 encoding.
 262
 263 sendContacts
 264 ~~~~~~~~~~~~
 265 Send a synchronization message with the local contacts list to all linked devices.
 266 This command should only be used if this is the master device.
 267
 268 daemon
 269 ~~~~~~
 270 signal-cli can run in daemon mode and provides an experimental dbus interface. For
 271 dbus support you need jni/unix-java.so installed on your system (Debian:
 272 libunixsocket-java ArchLinux: libmatthew-unix-java (AUR)).
 273
 274 *--system*::
 275         Use DBus system bus instead of user bus.
 276 *--ignore-attachments*::
 277         Don’t download attachments of received messages.
 278
 279
 280 Examples
 281 --------
 282
 283 Register a number (with SMS verification)::
 284     signal-cli -u USERNAME register
 285
 286 Verify the number using the code received via SMS or voice::
 287     signal-cli -u USERNAME verify CODE
 288
 289 Send a message to one or more recipients::
 290     signal-cli -u USERNAME send -m "This is a message" [RECIPIENT [RECIPIENT ...]] [-a [ATTACHMENT [ATTACHMENT ...]]]
 291
 292 Pipe the message content from another process::
 293     uname -a | signal-cli -u USERNAME send [RECIPIENT [RECIPIENT ...]]
 294
 295 Create a group::
 296         signal-cli -u USERNAME updateGroup -n "Group name" -m [MEMBER [MEMBER ...]]
 297
 298 Add member to a group::
 299         signal-cli -u USERNAME updateGroup -g GROUP_ID -m "NEW_MEMBER"
 300
 301 Leave a group::
 302         signal-cli -u USERNAME quitGroup -g GROUP_ID
 303
 304 Send a message to a group::
 305         signal-cli -u USERNAME send -m "This is a message" -g GROUP_ID
 306
 307 Trust new key, after having verified it::
 308     signal-cli -u USERNAME trust -v FINGER_PRINT NUMBER
 309
 310 Trust new key, without having verified it. Only use this if you don't care about security::
 311     signal-cli -u USERNAME trust -a NUMBER
 312
 313 Files
 314 -----
 315 The password and cryptographic keys are created when registering and stored in the
 316 current users home directory, the directory can be changed with *--config*:
 317
 318 `$XDG_DATA_HOME/signal-cli/` (`$HOME/.local/share/signal-cli/`)
 319
 320 For legacy users, the old config directories are used as a fallback:
 321
 322     $HOME/.config/signal/
 323
 324     $HOME/.config/textsecure/
 325
 326
 327 Authors
 328 -------
 329
 330 Maintained by AsamK <asamk@gmx.de>, who is assisted by other open
 331 source contributors. For more information about signal-cli development, see
 332 <https://github.com/AsamK/signal-cli>.