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 signal-cli is a commandline interface for libsignal-service-java.
  19 It supports registering, verifying, sending and receiving messages.
  20 For registering you need a phone number where you can receive SMS or incoming calls.
  21 signal-cli was primarily developed to be used on servers to notify admins of important events.
  22 For this use-case, it has a dbus interface, that can be used to send messages from any programming language that has dbus bindings.
  23
  24 For some functionality the Signal protocol requires that all messages have been received from the server.
  25 The `receive` command should be regularly executed. In daemon mode messages are continuously received.
  26
  27 == Options
  28
  29 *-h*, *--help*::
  30 Show help message and quit.
  31
  32 *-v*, *--version*::
  33 Print the version and quit.
  34
  35 *--verbose*::
  36 Raise log level and include lib signal logs.
  37
  38 *--config* CONFIG::
  39 Set the path, where to store the config.
  40 Make sure you have full read/write access to the given directory.
  41 (Default: `$XDG_DATA_HOME/signal-cli` (`$HOME/.local/share/signal-cli`))
  42
  43 *-u* USERNAME, *--username* USERNAME::
  44 Specify your phone number, that will be your identifier.
  45 The phone number must include the country calling code, i.e. the number must start with a "+" sign.
  46
  47 This flag must not be given for the `link` command.
  48 It is optional for the `daemon` command.
  49 For all other commands it is only optional if there is exactly one local user in the
  50 config directory.
  51
  52 *--dbus*::
  53 Make request via user dbus.
  54
  55 *--dbus-system*::
  56 Make request via system dbus.
  57
  58 *-o* OUTPUT-MODE, *--output* OUTPUT-MODE::
  59 Specify if you want commands to output in either "plain-text" mode or in "json". Defaults to "plain-text"
  60
  61 *--trust-new-identities* TRUST-MODE::
  62 Choose when to trust new identities:
  63 - `on-first-use` (default): Trust the first seen identity key from new users,
  64   changed keys must be verified manually
  65 - `always`: Trust any new identity key without verification
  66 - `never`: Don't trust any unknown identity key, every key must be verified manually
  67
  68 == Commands
  69
  70 === register
  71
  72 Register a phone number with SMS or voice verification.
  73 Use the verify command to complete the verification.
  74
  75 *-v*, *--voice*::
  76 The verification should be done over voice, not SMS.
  77
  78 *--captcha*::
  79 The captcha token, required if registration failed with a captcha required error.
  80 To get the token, go to https://signalcaptchas.org/registration/generate.html
  81 Check the developer tools for a redirect starting with signalcaptcha://
  82 Everything after signalcaptcha:// is the captcha token.
  83
  84 === verify
  85
  86 Verify the number using the code received via SMS or voice.
  87
  88 VERIFICATIONCODE::
  89 The verification code.
  90
  91 *-p* PIN, *--pin* PIN::
  92 The registration lock PIN, that was set by the user.
  93 Only required if a PIN was set.
  94
  95 === unregister
  96
  97 Disable push support for this device, i.e. this device won't receive any more messages.
  98 If this is the master device, other users can't send messages to this number anymore.
  99 Use "updateAccount" to undo this.
 100 To remove a linked device, use "removeDevice" from the master device.
 101
 102 *--delete-account*::
 103 Delete account completely from server. Cannot be undone without loss. You will
 104 have to be readded to each group.
 105
 106 CAUTION: Only delete your account if you won't use this number again!
 107
 108 === updateAccount
 109
 110 Update the account attributes on the signal server.
 111 Can fix problems with receiving messages.
 112
 113 *-n* NAME, *--device-name* NAME::
 114 Set a new device name for the main or linked device
 115
 116 === updateConfiguration
 117
 118 Update signal configs and sync them to linked devices.
 119 This command only works on the main devices.
 120
 121 *--read-receipts* {true,false}::
 122 Indicates if Signal should send read receipts.
 123
 124 *--unidentified-delivery-indicators* {true,false}::
 125 Indicates if Signal should show unidentified delivery indicators.
 126
 127 *--typing-indicators* {true,false}::
 128 Indicates if Signal should send/show typing indicators.
 129
 130 *--link-previews* {true,false}::
 131 Indicates if Signal should generate link previews.
 132
 133 === setPin
 134
 135 Set a registration lock pin, to prevent others from registering this number.
 136
 137 REGISTRATION_LOCK_PIN::
 138 The registration lock PIN, that will be required for new registrations (resets after 7 days of inactivity)
 139
 140 === removePin
 141
 142 Remove the registration lock pin.
 143
 144 === link
 145
 146 Link to an existing device, instead of registering a new number.
 147 This shows a "tsdevice:/…" URI. If you want to connect to another signal-cli instance, you can just use this URI.
 148 If you want to link to an Android/iOS device, create a QR code with the URI (e.g. with qrencode) and scan that in the Signal app.
 149
 150 *-n* NAME, *--name* NAME::
 151 Optionally specify a name to describe this new device.
 152 By default "cli" will be used.
 153
 154 === addDevice
 155
 156 Link another device to this device.
 157 Only works, if this is the master device.
 158
 159 *--uri* URI::
 160 Specify the uri contained in the QR code shown by the new device.
 161 You will need the full uri enclosed in quotation marks, such as "tsdevice:/?uuid=....."
 162
 163 === listDevices
 164
 165 Show a list of linked devices.
 166
 167 === removeDevice
 168
 169 Remove a linked device.
 170 Only works, if this is the master device.
 171
 172 *-d* DEVICE_ID, *--device-id* DEVICE_ID::
 173 Specify the device you want to remove.
 174 Use listDevices to see the deviceIds.
 175
 176 === getUserStatus
 177
 178 Uses a list of phone numbers to determine the statuses of those users.
 179 Shows if they are registered on the Signal Servers or not.
 180 In json mode this is outputted as a list of objects.
 181
 182 [NUMBER [NUMBER ...]]::
 183 One or more numbers to check.
 184
 185 === send
 186
 187 Send a message to another user or group.
 188
 189 RECIPIENT::
 190 Specify the recipients’ phone number.
 191
 192 *-g* GROUP, *--group-id* GROUP::
 193 Specify the recipient group ID in base64 encoding.
 194
 195 *-m* MESSAGE, *--message* MESSAGE::
 196 Specify the message, if missing, standard input is used.
 197
 198 *-a* [ATTACHMENT [ATTACHMENT ...]], *--attachment* [ATTACHMENT [ATTACHMENT ...]]::
 199 Add one or more files as attachment.
 200
 201 *--note-to-self*::
 202 Send the message to self without notification.
 203
 204 *-e*, *--end-session*::
 205 Clear session state and send end session message.
 206
 207 === sendReaction
 208
 209 Send reaction to a previously received or sent message.
 210
 211 RECIPIENT::
 212 Specify the recipients’ phone number.
 213
 214 *-g* GROUP, *--group-id* GROUP::
 215 Specify the recipient group ID in base64 encoding.
 216
 217 *-e* EMOJI, *--emoji* EMOJI::
 218 Specify the emoji, should be a single unicode grapheme cluster.
 219
 220 *-a* NUMBER, *--target-author* NUMBER::
 221 Specify the number of the author of the message to which to react.
 222
 223 *-t* TIMESTAMP, *--target-timestamp* TIMESTAMP::
 224 Specify the timestamp of the message to which to react.
 225
 226 *-r*, *--remove*::
 227 Remove a reaction.
 228
 229 === sendReceipt
 230
 231 Send a read or viewed receipt to a previously received message.
 232
 233 RECIPIENT::
 234 Specify the sender’s phone number.
 235
 236 *-t* TIMESTAMP, *--target-timestamp* TIMESTAMP::
 237 Specify the timestamp of the message to which to react.
 238
 239 *--type* TYPE::
 240 Specify the receipt type, either `read` (the default) or `viewed`.
 241
 242 === sendTyping
 243
 244 Send typing message to trigger a typing indicator for the recipient.
 245 Indicator will be shown for 15seconds unless a typing STOP message is sent first.
 246
 247 RECIPIENT::
 248 Specify the recipients’ phone number.
 249
 250 *-g* GROUP, *--group-id* GROUP::
 251 Specify the recipient group ID in base64 encoding.
 252
 253 *-s*, *--stop*::
 254 Send a typing STOP message.
 255
 256 === remoteDelete
 257
 258 Remotely delete a previously sent message.
 259
 260 RECIPIENT::
 261 Specify the recipients’ phone number.
 262
 263 *-g* GROUP, *--group-id* GROUP::
 264 Specify the recipient group ID in base64 encoding.
 265
 266 *-t* TIMESTAMP, *--target-timestamp* TIMESTAMP::
 267 Specify the timestamp of the message to delete.
 268
 269 === receive
 270
 271 Query the server for new messages.
 272 New messages are printed on standard output and attachments are downloaded to the config directory.
 273 In json mode this is outputted as one json object per line.
 274
 275 *-t* TIMEOUT, *--timeout* TIMEOUT::
 276 Number of seconds to wait for new messages (negative values disable timeout).
 277 Default is 5 seconds.
 278 *--ignore-attachments*::
 279 Don’t download attachments of received messages.
 280
 281 === joinGroup
 282
 283 Join a group via an invitation link.
 284
 285 *--uri*::
 286 The invitation link URI (starts with `https://signal.group/#`)
 287
 288 === updateGroup
 289
 290 Create or update a group.
 291 If the user is a pending member, this command will accept the group invitation.
 292
 293 *-g* GROUP, *--group-id* GROUP::
 294 Specify the recipient group ID in base64 encoding.
 295 If not specified, a new group with a new random ID is generated.
 296
 297 *-n* NAME, *--name* NAME::
 298 Specify the new group name.
 299
 300 *-d* DESCRIPTION, *--description* DESCRIPTION::
 301 Specify the new group description.
 302
 303 *-a* AVATAR, *--avatar* AVATAR::
 304 Specify a new group avatar image file.
 305
 306 *-m* [MEMBER [MEMBER ...]], *--member* [MEMBER [MEMBER ...]]::
 307 Specify one or more members to add to the group.
 308
 309 *-r* [MEMBER [MEMBER ...]], *--remove-member* [MEMBER [MEMBER ...]]::
 310 Specify one or more members to remove from the group
 311
 312 *--admin* [MEMBER [MEMBER ...]]::
 313 Specify one or more members to make a group admin
 314
 315 *--remove-admin* [MEMBER [MEMBER ...]]::
 316 Specify one or more members to remove group admin privileges
 317
 318 *--reset-link*::
 319 Reset group link and create new link password
 320
 321 *--link* LINK_STATE::
 322 Set group link state: `enabled`, `enabled-with-approval`, `disabled`
 323
 324 *--set-permission-add-member* PERMISSION::
 325 Set permission to add new group members: `every-member`, `only-admins`
 326
 327 *--set-permission-edit-details* PERMISSION::
 328 Set permission to edit group details: `every-member`, `only-admins`
 329
 330 *--set-permission-send-messages* PERMISSION::
 331 Set permission to send messages in group: `every-member`, `only-admins`
 332 Groups where only admins can send messages are also called announcement groups
 333
 334 *-e* EXPIRATION_SECONDS, *--expiration* EXPIRATION_SECONDS::
 335 Set expiration time of messages (seconds).
 336 To disable expiration set expiration time to 0.
 337
 338 === quitGroup
 339
 340 Send a quit group message to all group members and remove self from member list.
 341 If the user is a pending member, this command will decline the group invitation.
 342
 343 *-g* GROUP, *--group-id* GROUP::
 344 Specify the recipient group ID in base64 encoding.
 345
 346 *--delete*::
 347 Delete local group data completely after quitting group.
 348
 349 === listGroups
 350
 351 Show a list of known groups and related information.
 352 In json mode this is outputted as an list of objects and is always in detailed mode.
 353
 354 *-d*, *--detailed*::
 355 Include the list of members of each group and the group invite link.
 356
 357 === listContacts
 358
 359 Show a list of known contacts with names.
 360
 361 === listIdentities
 362
 363 List all known identity keys and their trust status, fingerprint and safety number.
 364
 365 *-n* NUMBER, *--number* NUMBER::
 366 Only show identity keys for the given phone number.
 367
 368 === trust
 369
 370 Set the trust level of a given number.
 371 The first time a key for a number is seen, it is trusted by default (TOFU).
 372 If the key changes, the new key must be trusted manually.
 373
 374 number::
 375 Specify the phone number, for which to set the trust.
 376
 377 *-a*, *--trust-all-known-keys*::
 378 Trust all known keys of this user, only use this for testing.
 379
 380 *-v* VERIFIED_SAFETY_NUMBER, *--verified-safety-number* VERIFIED_SAFETY_NUMBER::
 381 Specify the safety number of the key, only use this option if you have verified the safety number.
 382 Can be either the plain text numbers shown in the app or the bytes from the QR-code,
 383 encoded as base64.
 384
 385 === updateProfile
 386
 387 Update the profile information shown to message recipients.
 388 The profile is stored encrypted on the Signal servers.
 389 The decryption key is sent with every outgoing messages to contacts and included
 390 in every group.
 391
 392 *--given-name* NAME, *--name* NAME::
 393 New (given) name.
 394
 395 *--family-name* FAMILY_NAME::
 396 New family name.
 397
 398 *--about* ABOUT_TEXT::
 399 New profile status text.
 400
 401 *--about-emoji* EMOJI::
 402 New profile status emoji.
 403
 404 *--avatar* AVATAR_FILE::
 405 Path to the new avatar image file.
 406
 407 *--remove-avatar*::
 408 Remove the avatar
 409
 410 === updateContact
 411
 412 Update the info associated to a number on our contact list.
 413 This change is only local but can be synchronized to other devices by using `sendContacts` (see below).
 414 If the contact doesn't exist yet, it will be added.
 415
 416 NUMBER::
 417 Specify the contact phone number.
 418
 419 *-n*, *--name*::
 420 Specify the new name for this contact.
 421
 422 *-e*, *--expiration* EXPIRATION_SECONDS::
 423 Set expiration time of messages (seconds).
 424 To disable expiration set expiration time to 0.
 425
 426 === block
 427
 428 Block the given contacts or groups (no messages will be received).
 429 This change is only local but can be synchronized to other devices by using `sendContacts` (see below).
 430
 431 [CONTACT [CONTACT ...]]::
 432 Specify the phone numbers of contacts that should be blocked.
 433
 434 *-g* [GROUP [GROUP ...]], *--group-id* [GROUP [GROUP ...]]::
 435 Specify the group IDs that should be blocked in base64 encoding.
 436
 437 === unblock
 438
 439 Unblock the given contacts or groups (messages will be received again).
 440 This change is only local but can be synchronized to other devices by using `sendContacts` (see below).
 441
 442 [CONTACT [CONTACT ...]]::
 443 Specify the phone numbers of contacts that should be unblocked.
 444
 445 *-g* [GROUP [GROUP ...]], *--group-id* [GROUP [GROUP ...]]::
 446 Specify the group IDs that should be unblocked in base64 encoding.
 447
 448 === sendContacts
 449
 450 Send a synchronization message with the local contacts list to all linked devices.
 451 This command should only be used if this is the master device.
 452
 453 === sendSyncRequest
 454
 455 Send a synchronization request message to the master device (for group, contacts, ...).
 456 The master device will respond with synchronization messages with full contact and
 457 group lists.
 458
 459 === uploadStickerPack
 460
 461 Upload a new sticker pack, consisting of a manifest file and the sticker images.
 462 Images must conform to the following specification: (see https://support.signal.org/hc/en-us/articles/360031836512-Stickers#sticker_reqs )
 463 - Static stickers in PNG or WebP format
 464 - Animated stickers in APNG format,
 465 - Maximum file size for a sticker file is 300KiB
 466 - Image resolution of 512 x 512 px
 467
 468 The required manifest.json has the following format:
 469
 470 [source,json]
 471 ----
 472 {
 473   "title": "<STICKER_PACK_TITLE>",
 474   "author": "<STICKER_PACK_AUTHOR>",
 475   "cover": { // Optional cover, by default the first sticker is used as cover
 476     "file": "<name of image file, mandatory>",
 477     "contentType": "<optional>",
 478     "emoji": "<optional>"
 479   },
 480   "stickers": [
 481     {
 482       "file": "<name of image file, mandatory>",
 483       "contentType": "<optional>",
 484       "emoji": "<optional>"
 485     }
 486     ...
 487   ]
 488 }
 489 ----
 490
 491 PATH::
 492 The path of the manifest.json or a zip file containing the sticker pack you wish to upload.
 493
 494 === daemon
 495
 496 signal-cli can run in daemon mode and provides an experimental dbus interface.
 497 If no `-u` username is given, all local users will be exported as separate dbus
 498 objects under the same bus name.
 499
 500 *--system*::
 501 Use DBus system bus instead of user bus.
 502 *--ignore-attachments*::
 503 Don’t download attachments of received messages.
 504
 505 == Examples
 506
 507 Register a number (with SMS verification)::
 508 signal-cli -u USERNAME register
 509
 510 Verify the number using the code received via SMS or voice::
 511 signal-cli -u USERNAME verify CODE
 512
 513 Send a message to one or more recipients::
 514 signal-cli -u USERNAME send -m "This is a message" [RECIPIENT [RECIPIENT ...]] [-a [ATTACHMENT [ATTACHMENT ...]]]
 515
 516 Pipe the message content from another process::
 517 uname -a | signal-cli -u USERNAME send [RECIPIENT [RECIPIENT ...]]
 518
 519 Create a group::
 520 signal-cli -u USERNAME updateGroup -n "Group name" -m [MEMBER [MEMBER ...]]
 521
 522 Add member to a group::
 523 signal-cli -u USERNAME updateGroup -g GROUP_ID -m "NEW_MEMBER"
 524
 525 Accept a group invitation::
 526 signal-cli -u USERNAME updateGroup -g GROUP_ID
 527
 528 Leave a group::
 529 signal-cli -u USERNAME quitGroup -g GROUP_ID
 530
 531 Send a message to a group::
 532 signal-cli -u USERNAME send -m "This is a message" -g GROUP_ID
 533
 534 Trust new key, after having verified it::
 535 signal-cli -u USERNAME trust -v SAFETY_NUMBER NUMBER
 536
 537 Trust new key, without having verified it. Only use this if you don't care about security::
 538 signal-cli -u USERNAME trust -a NUMBER
 539
 540 == Exit codes
 541 * *1*: Error is probably caused and fixable by the user
 542 * *2*: Some unexpected error
 543 * *3*: Server or IO error
 544 * *4*: Sending failed due to untrusted key
 545
 546 == Files
 547
 548 The password and cryptographic keys are created when registering and stored in the current users home directory, the directory can be changed with *--config*:
 549
 550 `$XDG_DATA_HOME/signal-cli/` (`$HOME/.local/share/signal-cli/`)
 551
 552 == Authors
 553
 554 Maintained by AsamK <asamk@gmx.de>, who is assisted by other open source contributors.
 555 For more information about signal-cli development, see
 556 <https://github.com/AsamK/signal-cli>.