TL;DR: I made a thing called signald

A while back I tried to write a bot for Signal. It turns out this wasn’t really possible. There is a tool called signal-cli that sorta kinda works for manual use on the command line, but is very difficult to scrape the output of, and almost seems designed to resist automated use, except over dbus. It’s very difficult to get dbus working in headless environments, as I discovered. Or maybe it’s easy but I couldn’t figure it out. Either way, I stopped persuing that when I discovered this pull request, which adds various interaction via JSON strings sent to signal-cli’s stdin and read out from signal-cli’s stdout. It has been open for over a year, won’t merge cleanly anymore, and most functionality isn’t available via the JSON interface. The signal-cli developer didn’t seem terribly interested in merging it or developing that functionality, and it became clear that I needed to seek other options.

So I built my own. or forked signal-cli. or something. I’m not sure. I kept a file called, which is used for interaction with the Signal library, and most of the classes related to disk storage, but replaced most of the rest of it. I call it signald for now, although I suspect that Signal may object to this name for trademark reasons, so I’m trying to think of a new name.

It works like this: When signald runs, it creates a unix socket file at /var/run/signald/signald.sock. Clients can connect to it, and send it JSON messages to do things like register a number with Signal, link to an existing device, add another device to accounts that are registered, send and receive messages, list/create/update/leave groups, sync and list contacts (there’s an open issue for creating, updating and deleting contacts), etc. When updates, such as inbound message or read receipts come in, they are encoded as JSON and send to all connected clients that subscribed to updates for that user.

What I don’t have, and I want to have before I show this off too much, is client tools. I would like a python library, and maybe some other languages too. I would also like a CLI client to interact with it. And of course, there are some outstanding issues that I feel really ned to be dealt with before it is more widely used, such as how attachments are delivered to clients.

I’ve been primarily developing signald on a private GitLab server, but since it doesn’t have open registration, file issues on the mirror on

If you use signald for anything, please get in touch! I’d love to hear about different use cases. A few of my IRL friends have been using it, and in chatting with them I’ve been able to refine the API and understand where the pain points were. I also have been assuming no one else is using signald, and making breaking changes to the API for minor version bumps, and intend to break more things before it hit’s 1.0 stable. I will endevor to notify clients, and if I get a couple of users I’ll figure out some way to get notified when the API changes.