sigtop: exporting your Signal Desktop messages and attachments

Two commands produce a directory of messages and a directory of attachments

sigtop is described as a utility to export messages, attachments and other data from Signal Desktop, and the README gives the two-command shape of it immediately.

	sigtop export-messages messages
	sigtop export-attachments attachments

So the interface is a set of subcommands, each taking a destination directory. The first command exports all messages into the `messages` directory, and the second exports all attachments into the `attachments` directory.

The reason this tool exists at all is that Signal Desktop is a local-first application. Its history is on your machine, in a database, and there is no supported export path for the conversation history. A tool that dumps it to files is the difference between a conversation that survives a reinstall and one that does not.

The documentation is a man page, `sigtop.1`, which the README says is available locally and also readable online. That is worth noting for a command line program: the manual page is the interface documentation, not an afterthought, and the README points at it as the place to look for details the two example commands do not cover.

The repository layout shows the program is split into focused packages. There is `cmd/` for the command entry point, `signal/` for the Signal-specific parts, `sqlcipher/` for the encrypted database layer, `safestorage/` for the keychain interaction, plus `at/`, `filename/`, `getopt/` and the module files `go.mod` and `go.sum`. The split between reading the database and obtaining the decryption key is the interesting architectural detail here.

libsecret is the dependency that decides whether it works on your system

The Unix installation instructions state the requirements precisely. You need Go, version 1.21 or later, and a C compiler, and on systems other than OpenBSD you also need `libsecret` and `pkg-config`.

That `libsecret` requirement is the crux of the whole program. Signal Desktop stores its database encrypted with SQLCipher, and the key that decrypts it lives in the desktop keychain rather than in a file you can copy. On Linux that keychain is libsecret, and reading it requires talking to the running secret service, which is why `pkg-config` is needed to find the library and why a C compiler is required at all for a Go program.

The README is explicit that you can build without it, by specifying the `no_libsecret` build tag:

	go install -tags no_libsecret github.com/tbvdm/sigtop/cmd/sigtop@master

Whether that build is useful to you depends on what you are trying to do. A build with no keychain support cannot read a Signal Desktop database that is encrypted, which is the normal case, so the tag exists mainly for systems where libsecret cannot be installed and for building on platforms where the key is obtained another way. The README does not describe what the no-libsecret build can and cannot read, which is a real documentation gap for anyone choosing a build variant deliberately.

The dependency list in the module file is consistent with this. `golang.org/x/crypto` is there for the SQLCipher side, `golang.org/x/sys` and `golang.org/x/text` for the platform and text handling, `github.com/godbus/dbus/v5` because the Secret Service on Linux is a D-Bus service, `github.com/tbvdm/go-cli` for the command line parsing, and `github.com/tbvdm/go-openbsd` for the OpenBSD-specific pieces, which lines up with the note that OpenBSD is the one system where libsecret is not required.

Install paths differ sharply across Linux, macOS and Windows

The README covers three platforms and the three paths are quite different, mostly because of how each platform stores the key.

On Ubuntu 24.04 or later, the packages come from apt:

	sudo apt install gcc golang libsecret-1-dev pkg-config

And then the install itself, which puts a `sigtop` binary in `~/go/bin`:

	go install github.com/tbvdm/sigtop/cmd/sigtop@master

The `GOBIN` environment variable changes the destination, so `GOBIN=~/bin go install github.com/tbvdm/sigtop/cmd/sigtop@master` puts it in `~/bin` instead. The README also flags that Ubuntu 18.04, 20.04 and 22.04 need a newer Go than the distribution ships, with a link to the Go wiki.

macOS is Homebrew, and it installs from the HEAD of a tap rather than a released version:

	brew install --HEAD tbvdm/tap/sigtop

with `brew upgrade --fetch-HEAD sigtop` to update later. The HEAD choice is consistent with the fact that the Unix install instructions also use `@master` rather than a version tag.

Windows has three routes. A pre-compiled binary is downloadable from the latest release, but the README attaches a substantial warning to that option: virus scanners may warn about the sigtop binary, and as pointed out in the Go FAQ, warnings from virus scanners about Go programs often are false positives. The author asks people not to open an issue only to report a scanner warning, and points to building from source as the alternative if you do not trust the binary.

Building from source on Windows needs Go and the C compiler from WinLibs, unpacked to `C:\winlibs`, with the compiler path set in the environment:

	$env:cc = 'c:\winlibs\mingw64\bin\gcc'
	go install github.com/tbvdm/sigtop/cmd/sigtop@master

And there is a WSL cross-compilation route for people who find it simpler, which installs a MinGW cross compiler and sets the target explicitly:

	GOOS=windows GOARCH=amd64 CGO_ENABLED=1 CC=x86_64-w64-mingw32-gcc-win32 go install github.com/tbvdm/sigtop/cmd/sigtop@master

which lands the executable in `~/go/bin/windows_amd64`, and it can be moved from there to a Windows location.

A command line program that has to be run where Signal Desktop is

There is a constraint in the Windows section that applies everywhere. The README notes that sigtop is a command-line program, and it should be run in a PowerShell or Command Prompt window.

More importantly, there is no network component and no service mode. This is a program that opens the local Signal Desktop database, gets the key from the local keychain, and writes files to a directory you name. It has to run on the machine where Signal Desktop has its data, with your user session, because the keychain access is a per-user, per-session operation.

That has a consequence for how you would use it in practice. It is not something you schedule on a server, and it is not something you run against a colleague's account on their laptop without them present. It is a local tool for the person who owns the machine.

The `export-messages` and `export-attachments` split reflects how Signal stores things. The conversation body is in the database, and the media is on disk as separate files, so getting a complete archive takes two commands rather than one. The README describes the tool as exporting messages, attachments and other data, and the two example commands cover the first two, with the manual page covering the rest.

The output is a directory of files rather than a single archive, which is convenient for grepping and for loading into another tool, and less convenient for transport. The manual page is the place to find out the exact file naming and layout.

Compared with a screenshot archive and with a scripted database read

Two other approaches cover the same need, and each trades something different.

A manual archive, which in practice means scrolling and screenshotting conversations, needs no tooling and no keychain access at all. The cost is that the result is not text. It cannot be searched, it cannot be reprocessed, and it takes a human being an unbounded amount of time. For a handful of important messages it is the right answer.

Reading the Signal Desktop SQLite database directly is the other approach, and it is what sigtop automates. Doing it by hand means finding the database, discovering that the schema is not what you expect, and then hitting the encryption. A SQLCipher-encrypted SQLite file will not open with the sqlite3 command line tool, and the key is not in a configuration file you can point at. Every one of those steps is a reason the program exists.

The difference in approach between sigtop and those two is that sigtop is a complete, supported path rather than a set of hints. It knows where the database is, it knows how to obtain the key from the keychain, and it produces a predictable directory layout. The cost is that it is coupled to how Signal Desktop happens to store things, which is a coupling that a format change would break.

A related consideration is the license. The repository metadata reports the licence as Other, a custom licence that GitHub cannot classify, with the terms in the LICENSE.md file at the root. For a personal backup tool that is not a practical obstacle, and this is not legal advice, but it is worth reading that file before redistributing the binary or folding it into a workflow that others depend on.

Editorial conclusion

Adopt sigtop if you need a durable copy of your own Signal Desktop messages or attachments, and you run it on the same machine where Signal Desktop stores its data. Do not adopt it for archiving conversations on a device you do not control, since it reads a local encrypted store through the keychain, and treat the export as sensitive data that needs the same handling as the messages themselves. Verify first that the build you install has keychain support, because the `no_libsecret` build tag exists precisely for systems where that is not possible, and check the `sigtop.1` manual page for the exact output layout.

Frequently asked questions

Official sources

1. Issues
2. README
3. Releases
4. tbvdm/sigtop on GitHub