gurk: A Terminal Signal Client for Keyboard-Focused Messaging

gurk's Terminal Messaging Scope

gurk addresses a specific problem: using Signal Messenger without switching to a graphical desktop or mobile interface. The README describes it as a “Signal Messenger client for terminal,” while `Cargo.toml` categorizes it as a command-line utility with the `signal` and `tui` keywords. Its intended user is someone who wants Signal conversations, channels, reactions, attachments, and message navigation inside a terminal application.

The interface is not a basic command wrapper around a web service. The README documents navigation between messages and channels, a channel selection popup, message copying, URL opening, reactions, mute controls, and multiple input modes. It is closer to a focused terminal messenger with keyboard-oriented controls than a prompt for sending one message and exiting.

The project depends on official Signal libraries through `presage` and `presage-store-sqlite`, both pinned to the same Git revision in `Cargo.toml`. The README specifically says that the binary cannot be published on crates.io because several official Signal libraries are unavailable there. That constraint affects installation and upgrades even though the resulting application is a conventional terminal executable.

This design places gurk between a graphical Signal client and a small command-line sender. It offers a persistent messaging workspace, but the README does not document web access, group administration features beyond the listed controls, or compatibility guarantees for every Signal service capability.

presage, SQLite, and the gurk TUI

The repository layout contains a Rust application with terminal interface code, SQL migrations, an `xtask` workspace member, and distribution tooling. `Cargo.toml` lists `signal` and `tui` as keywords and `command-line-utilities` as its category. Its dependencies include `crossterm` for terminal event handling, `presage` for Signal operations, and `presage-store-sqlite` for persistence. The application also includes `libsqlite3-sys`, and the README identifies the data directory as the location for messages, the Signal database, and attachments.

The visible data flow begins when a user launches `gurk`. On first use, the client displays a QR code in an image viewer so the account can be linked as a new device. It also creates a configuration file at the default configuration location. After linking, the README documents selecting channels and messages, opening channel and message selection popups, sending text, reacting to selected messages, and uploading files. The selected data directory holds local message and attachment state.

The TUI is event-driven through keyboard input. `f1` toggles the help panel, `ctrl+c` quits, arrow and page keys move selections, and `enter` sends a message except when the single-line input is empty and the selected message contains a URL. Multi-line mode changes `enter` so it inserts another line instead of sending the message.

The repository also supports clipboard operations through `arboard`, URL and file actions, and platform-specific data paths. The README and top-level files do not expose the complete synchronization protocol, retry policy, encryption boundary, or database schema. Those areas need source-level review before selecting gurk for a particular security or data-retention policy.

Installing gurk Through Git and System Packages

The README offers pre-compiled release binaries and several package-manager routes. The shortest documented route for users with `cargo-binstall` is the following command. It installs `gurk` from the Git repository:

cargo binstall --git https://github.com/boxdot/gurk-rs gurk

Users building from source need the `protoc` compiler and Perl before running the documented Cargo installation command:

cargo install --git https://github.com/boxdot/gurk-rs gurk

The `Cargo.toml` declares Rust edition 2024 and a minimum Rust version of 1.94.0. A source build therefore also requires a compatible Rust toolchain. The README does not give operating-system commands for installing `protoc` or Perl, so those prerequisites must already be available or be installed separately.

Arch Linux users can install the tagged package from the official repository. The README says to run this command as root:

pacman -S gurk

It also lists `gurk-git` as an AUR source build from Git HEAD. Nix and NixOS have per-user and system-wide installation forms:

nix-env --install gurk-rs

environment.systemPackages = with pkgs; [ gurk-rs ];

FreeBSD provides `pkg` and ports-tree routes:

pkg install net-im/gurk-rs

cd /usr/ports/net-im/gurk-rs
make install clean

These routes have different upgrade semantics. A tagged Arch package follows that repository's packaged version, while `gurk-git` follows Git HEAD. The README does not document a rollback command or a migration procedure for relocating the data directory, so an upgrade should not be treated as risk-free merely because a package manager installed the executable.

First Launch, QR Linking, and Configuration

After installation, start the executable with:

gurk

On the first run, gurk opens a QR code in the system image viewer. The account-linking flow expects the user to scan that code with Signal so the terminal client can be added as a new device. The same run creates a configuration file at the default configuration location. The README points to `src/config.rs` for configuration directives, but it does not reproduce the complete configuration schema.

Without an explicit path, gurk searches for configuration in this order: `$XDG_CONFIG_HOME/gurk/gurk.toml`, `$XDG_CONFIG_HOME/gurk.toml`, the platform configuration directory, and `$HOME/.gurk.toml`. A different file can be selected with `-c`, `--config`, or `GURK_CONFIG`.

The data directory is selected by `--data-dir` or `GURK_DATA_DIR` first. It then considers the `data_dir` setting in the configuration file, `$XDG_DATA_HOME/gurk`, and the platform data directory. The README gives `~/Library/Application Support/gurk` as a macOS example. Separating configuration from message data makes it easier to control each path, but the README does not state whether moving an existing data directory is supported.

Keyboard Navigation, Reactions, and File Uploads

Keyboard behavior is gurk's central interaction model. In single-line input, `tab` sends an emoji from the input line as a reaction to the selected message. `alt+enter` switches between single-line and multi-line input. `alt+left` and `alt+right` move by word, while `ctrl+w`, `ctrl+backspace`, and `alt+backspace` delete the last word. `ctrl+u` removes text from the cursor to the start of the line.

Message selection uses `alt+Up`, `alt+k`, `PgUp`, `alt+Down`, `alt+j`, and `PgDown`. Channel selection uses `ctrl+j`, `Up`, `ctrl+k`, and `Down`, while `ctrl+p` opens or closes the channel selection popup. `alt+m` toggles mute for the selected channel, suppressing notifications and marking that channel with `[M]`.

File uploads use URI-style input rather than a separate file picker. The documented forms are:

file:///path/to/file
file://clip

The first form uploads the named file. The second uploads clipboard content. These inputs fit a keyboard-driven message editor, but users must remember the exact URI syntax. The README does not specify upload size limits, accepted attachment types, or what happens when the referenced file does not exist.

Clipboard access has a separate shortcut: `alt+y` copies the selected message. Other documented actions include opening a URL from an empty single-line input, opening a file, editing or deleting a message, and sending an emoji reaction. These details make gurk more capable than a minimal sender, although each action remains tied to terminal selection and editing behavior.

Custom gurk Bindings and Trace Logging

The example configuration shows how to replace selected defaults without replacing the entire interface. Bindings use the form `keybindings.<mode>.<keycombination> = "<command>"`. Setting an empty command removes an existing binding in that mode. Setting `default_keybindings = false` disables all defaults.

Supported modes include `anywhere`, `normal`, `message_selected`, `channel_modal`, `multiline`, and `help`. The command list includes `react`, `copy_message selected`, `edit_message`, `delete_message`, `open_file`, `toggle_mute_channel`, and movement or selection commands. The example assigns `ctrl-q` to quit, `ctrl-n` and `ctrl-p` to channel selection, and reaction commands to two message-selection shortcuts.

For troubleshooting, the project provides a trace command covering gurk and its Signal dependencies:

RUST_LOG=gurk=trace,presage=trace,libsignal=trace gurk --verbose

The resulting `gurk.log` is the documented file to inspect. This gives users a concrete diagnostic path when a binding fails, QR linking does not complete, or a Signal operation stops unexpectedly. The README does not document log rotation, retention, file permissions, or automatic removal.

Because TOML is plain text, keybindings can be checked into a configuration repository or generated through configuration management. Users should still verify that their terminal and input method deliver configured `alt` and `ctrl` combinations consistently, since gurk receives those actions through terminal events.

gurk's Distribution Limits and Alternative Clients

The clearest limitation is package distribution. gurk cannot be published on crates.io because its official Signal dependencies are unavailable there, so the documented source route is `cargo install --git`. Source builds also require `protoc`, Perl, and Rust 1.94.0 or later according to `Cargo.toml`. A deployment that requires only registry packages and no native build prerequisites may not fit this project.

The terminal design also creates a deliberate trade-off. Channel navigation, reactions, and uploads rely heavily on keyboard modes and selected messages. The first-run QR code opens in an external image viewer, so linking is not entirely text-only. The README does not document a mouse-oriented interface, browser mode, or alternate QR presentation method. Users who need the conventional graphical Signal workflow should keep that interface available.

A real alternative is Signal's graphical client experience on desktop or mobile. Those applications present Signal through graphical controls, whereas gurk uses Rust, `presage`, and a local SQLite-backed data directory. The repository does not claim feature parity with official clients, and the README does not document a formal compatibility comparison. The practical distinction is architectural: gurk is a configurable terminal application with local state, not a repackaged Signal desktop interface.

gurk Releases, Upgrades, and AGPL-3.0-only

The repository is not archived. Its last push was on 2026-10-12, and the release list includes v0.10.2 on 2026-10-12, v0.10.1 on 2026-07-26, and v0.10.0 on 2026-07-19. That release history shows recent project activity, although the README does not define a support window or guarantee compatibility with older Signal service versions.

Upgrade routes remain distribution-specific. A user can download a pre-compiled file from Releases, install from the Git repository, or use a platform package. Selecting `gurk-git` accepts a moving Git HEAD build, while `pacman -S gurk` installs the official tagged package. The README does not explain how to migrate or restore the Signal database after a failed upgrade, so protecting the documented data directory is a concrete pre-upgrade concern.

The project uses `AGPL-3.0-only`. The README also states that contributions are covered by the same license unless contributors explicitly state otherwise. This identifies the declared license without offering legal advice. Organizations modifying or distributing the application should review the `AGPL-3.0-only` terms and the Signal library dependencies before making a compliance decision.

Editorial conclusion

Adopt gurk if terminal-based Signal access and configurable keyboard controls are central to your workflow. Do not choose it if you need a published crates.io package, a fully documented rollback path, or installation without native build prerequisites. First verify that your platform can provide the Signal libraries, `protoc`, Perl, and a compatible Rust toolchain.

Frequently asked questions

Official sources

1. boxdot/gurk-rs on GitHub
2. Issues
3. License: AGPL-3.0
4. README
5. Releases