Linking the Signal CLI with Signal on your mobile.

05 January 2017

20170107: It's not "group name" it's "Group ID."  I don't know how to find that yet.

The communications program Signal by Open Whisper Systems is unique in several respects.  Firstly, its barrier to entry is minimal.  You can search for it in the Google Play online store or Apple iOS appstore and it's waiting there for you at no cost.  Second, it's designed for security by default, i.e., you don't have to mess around with it to make it work, and it does does the right thing automatically and enforces strong encryption by default (unlike a lot of personal security software).  It interoperates seamlessly with people who don't use Signal but you have the option to invite them to install it with a single tap.  Its protocol is an open standard that multiple companies have implemented, so theoretically anyone can write their own implementation of the client (Android, iOS) or server, or compile it for themselves.  It's an SMS/MMS application, so you can use it as your default text messaging client on your mobile, plus it can do text message conferencing with multiple people automatically (it's a great way to keep in touch with friends if you're at the same con).  There's even a desktop Signal client that runs inside of Google Chrome or Chromium (source code for the interested and curious).

So, why, exactly am I posting about Signal?

There is a little-known command-line implementation of Signal that I've been experimenting with because I eventually plan on writing a bot for my exocortex.  In playing around with it, I've come to realize that it's not particularly friendly to use at all, and I might have to break down and use the dbus interface to do anything useful with it.  Which I don't look forward to, but that's not the point.  The point is, I've compiled some notes about how to use the command line version of Signal and I wanted to put them online in case somebody will find them helpful.

First, let's assume that you've installed the signal-cli utility.

As long as you have a phone number that can receive text messages you can register it as a Signal device.  You can even register a VoIP number as long as the SIP registrar has an SMS/MMS gateway.  For example, (the VoIP provider I use) lets you both send and receive SMS with numbers bought from them.  So, you don't technically need a mobile to use Signal.

For the moment, let's assume that you do have a mobile and its phone number is 212-555-4240.  Substitute your real number as appropriate.

To link a copy of signal-cli on your machine with the copy of Signal on your mobile: signal-cli --username 2125554240 link

signal-cli will print a long URL that looks something like this: tsdevice:/?uuid=...&pub_key=....

You'll want to copy and paste that entire URL into a QRcode generator so that your mobile can read it.  I used qrencode and an image viewer on Windbringer.  You can also use an online QRcode generator like  When you display the image, make sure it's as big as you can get it.  Now pop open Signal on your cellphone and tap Menu -> Settings -> Linked devices -> and then the plus (+) icon.  Signal will go into camera mode; photograph the QRcode with your phone, and be quick about it because that tsdevice:/ URL will only be good for a minute or two.  Signal will then authorize signal-cli on your workstation to participate in active chats, group conferences, and modify the account configuration on its behalf.

In the output from signal-cli you will see what Signal considers its canonical username, which you'll want to keep track of because you'll need it to do anything else with signal-cli.  It looks something like this:  +12125554240

You'd think this would be logical, but it's not.

Now let's download all of the latest messages sent to your phone. signal-cli -u +12125554240 receive

As it runs, your screen will be flooded with messages.  Some are for successful receipt of messages you sent, others will be group chat synchronization messages, and others will be the messages themselves (you can see them if you scroll back).  Messages also have optional expiration times, after which the message will automatically delete itself.

Listing the devices associated with your Signal account: signal-cli -u +12125554240 listDevices

The output of that command is largely meant to be machine readable, but what it amounts to is the name of each Signal device, the datestamp in which it was assocaited, and the datestamp at which it last contacted the network.

Send a message to someone (the destination's Signal uisername is given as +1NPANXXxxxx in the example; just pretend it's a phone number, no dashes, with a "+1" on the front) from the command line: signal-cli -u +12125554240 send +1NPANXXxxxx -m "This is the message I want to send."

In theory, you can send messages to group chats with the following command but I haven't figured out how to make it work yet because I haven't figured out what the Group ID actually is: signal-cli -u +12125554240 send -g "Group ID" -m "your message here"

It may not be helpful at first, but If you want to view your Signal public key fingerprint and safety number, which can be used to authenticate you:
signal-cli -u +12125554240 listIdentities

That's all I've worked out so far.  When I figure out more I'll update this post.