negative zero

Setting up Signal Desktop without a mobile device

2022 February 21

[messaging] [privacy] [signal] [tech] [tutorial]

I mentioned using signal-cli recently, but I didn't actually explain how, just linked to a guide.

Here's my own guide.


Download signal-cli

  1. Install Java 17+
  2. Depending on your distro, this might be something like openjdk-17-jre (Debian) or java-17-openjdk (Fedora) or jre-openjdk (Arch).

  3. cd into /opt
  4. You may need to become root first (e.g., sudo su).

    cd /opt

    We'll dump signal-cli here for convenience.

  5. Download signal-cli from GitHub
  6. On Linux, for instance,

    export VERSION=0.11.6

    Replace 0.11.6 with the current version.

    curl -LO${VERSION}/signal-cli-${VERSION}-Linux.tar.gz
  7. Verify the download
  8. Linux releases are signed with a key with fingerprint FA10826A74907F9EC6BBB7FC2BA2CD21B5B09570. To verify the download, first fetch this key:

    gpg --recv-keys FA10826A74907F9EC6BBB7FC2BA2CD21B5B09570
    gpg: key 2BA2CD21B5B09570: public key "AsamK <>" imported
    gpg: Total number processed: 1
    gpg:               imported: 1

    Download the signature:

    curl -LO${VERSION}/signal-cli-${VERSION}-Linux.tar.gz.asc

    Verify the signature:

    gpg --verify-files signal-cli-${VERSION}-Linux.tar.gz.asc
    gpg: assuming signed data in 'signal-cli-0.11.6-Linux.tar.gz'
    gpg: Signature made Sun Dec 18 14:24:42 2022 EST
    gpg:                using RSA key FA10826A74907F9EC6BBB7FC2BA2CD21B5B09570
    gpg: Good signature from "AsamK <>" [unknown]
    gpg: WARNING: This key is not certified with a trusted signature!
    gpg:          There is no indication that the signature belongs to the owner.
    Primary key fingerprint: FA10 826A 7490 7F9E C6BB  B7FC 2BA2 CD21 B5B0 9570

    (The important part is the "Good signature from [ID]" bit. It is normal that it says the key is not certified with a trusted signature. This is because we haven't verified the key and manually set it to trusted. It does not mean that the key is invalid.)

  9. Extract the archive
  10. tar xzf signal-cli-${VERSION}-Linux.tar.gz
  11. Symlink to the executable
  12. sudo ln -s /opt/signal-cli-${VERSION}/bin/signal-cli /usr/local/bin/signal-cli

Set up signal-cli

Here, signal-cli will act as your primary (mobile) device. In a later step, we will link with Signal Desktop.

  1. Become a regular user again
  2. Register your phone number
  3. signal-cli -u +12345556789 register

    Replace +12345556789 with your own phone number, formatted like that. Include the +<country code> and do not use spaces or hyphens.

    Most likely, you will need to fill out a CAPTCHA. In this case, complete one from You should be redirected to a page with an "Open Signal" link. Copy that link URL. The part of the URL you will need is everything after signalcaptcha://. Try to register again, using this long response:

    signal-cli -u +12345556789 register --captcha 'signal-recaptcha-v2.6<several lines of random-looking stuff>'
  4. If this works, you should receive a 6-digit verification code via SMS. Use this to verify your account
  5. signal-cli -u +12345556789 verify 123456
  6. Set a username
  7. signal-cli -u +12345556789 updateProfile --name MyUsername

    This is necessary for some things like v2 groups.

  8. (Optional) Run signal-cli as a systemd service
  9. You can run signal-cli as a daemon with signal-cli -u +12345556789 daemon. You may want to do this with systemd. I have a systemd service at ~/.config/systemd/user/signal-cli@.service that looks like this:

    Description=Signal cli for %I
    ExecStart=/usr/local/bin/signal-cli -u +%I daemon --ignore-attachments

    This lets me control the signal-cli@12345556789.service systemd service, e.g.:

    systemctl --user start signal-cli@12345556789

    Note: This setup runs this as a user service. You may need to install libunixsocket-java and dbus-user-session. See this issue.

You may wish to take additional steps, such as adding a registration PIN with setPin.

I'll assume you already have Signal Desktop installed.

  1. Open Signal Desktop
  2. On first launch, Signal Desktop should display a QR code to be scanned from the primary ("phone") device.

  3. Take a screenshot of the QR code
  4. Decode the QR code with zbarimg
  5. zbarimg my_qr_code.png

    This should output something like this:

    QR-Code:sgnl://linkdevice?uuid=<a UUID>&pub_key=<a public key>

    Copy the link starting with "sgnl://".

  6. Add the new device
  7. Using the link from the previous step, run this command:

    signal-cli -u 12345556789 addDevice --uri 'tsdevice:/<link from above>'

    Signal Desktop should now sync with your signal-cli account. From here on, you should be able to do most things from Signal Desktop and not have to deal with signal-cli (though you should still run signal-cli to keep it synced).

Updating signal-cli

When you need to update signal-cli, just download the new version:

  1. Remove the existing symlink
  2. sudo rm /usr/local/bin/signal-cli
  3. Follow the steps from above to download the new version of signal-cli and create a new symlink