Tyrtulia TUI

Terminal client for Tyrtulia, the headless forum for small multi-user servers (tildes, pubnixes, club servers). Built with Textual.

The server, its API and how to run an instance are in the Tyrtulia repository (also on PyPI as tyrtulia).

• On the server itself it talks to Tyrtulia through its Unix socket: the operating system tells the forum who you are, so there is nothing to log in to.
• From anywhere else it logs in with your SSH key (a signed challenge) and keeps the session token in a private file. Before signing, it checks that the login message names the server it is talking to, so a malicious server cannot reuse your signature on another instance.
• It only knows GET / and follows the links the forum returns: an action appears in the footer only when the forum offers it to you (reply, edit, pin, hide...).
• Notifications arrive in real time over Server-Sent Events.

Requirements

• Python 3.14.
• OpenSSH client (ssh-keygen), to sign the login challenge when you connect from outside the server.
• A Tyrtulia instance, 1.0 or later (1.2 adds login messages bound to the instance). To set one up, follow its getting started guide for administrators.

Installation

With uv:

uv tool install tyrtulia-tui

With pip:

python3.14 -m venv ~/.local/share/tyrtulia-tui
~/.local/share/tyrtulia-tui/bin/pip install tyrtulia-tui
ln -s ~/.local/share/tyrtulia-tui/bin/tyrtulia-tui ~/.local/bin/tyrtulia-tui

Administrators can install it once for every user of the server, for example in /opt/tyrtulia-tui with a link in /usr/local/bin.

Usage

On the server, just run it. It finds the socket in /run/tyrtulia/tyrtulia.sock (or /var/run/tyrtulia/tyrtulia.sock on BSD):

tyrtulia-tui

From another machine, point it to the forum and give your username and SSH key. Your first SSH key is registered from the server itself (profile, k) or by the operator:

tyrtulia-tui --url https://forum.example.org --user alice --key ~/.ssh/id_ed25519

The key can also be the .pub file, to sign with ssh-agent. Without --user, you read as a guest and can log in later with l.

Configuration

Every key is optional; command line options win:

# ~/.config/tyrtulia-tui/config.toml
url = "https://forum.example.org"
username = "alice"
key = "~/.ssh/id_ed25519"
editor = "nvim"            # for Ctrl+O; also "emacs -nw", "nano", "code --wait"...
# socket = "/run/tyrtulia/tyrtulia.sock"

Session tokens are kept in ~/.local/state/tyrtulia-tui/tokens.json (mode 0600), and the last post you read in each thread in read.json next to it, to show how many posts are new. Both follow XDG_STATE_HOME.

Keys

Only the actions the forum allows you appear in the footer.

Writing in your own editor

You can write posts in your usual terminal editor instead of the built-in one:

1. Open the editor of the TUI as usual: n for a new thread, r to reply, a to answer a post or e to edit one. For a new thread, type the title first.
2. Press Ctrl+O. The TUI steps aside and your editor opens with the draft.
3. Write, save and quit (:wq in vim, C-x C-s and C-x C-c in Emacs, Ctrl+O and Ctrl+X in nano).
4. You are back in the TUI with the text. Check it and press Ctrl+S to send, or Ctrl+O again to keep editing.

The editor is, in this order: --editor on the command line, editor in the configuration, $VISUAL, $EDITOR and finally vi. Arguments are allowed:

# ~/.config/tyrtulia-tui/config.toml
editor = "nvim"
# editor = "emacs -nw"
# editor = "nano"
# editor = "hx"
# editor = "code --wait"     # graphical editors need their "wait" option

tyrtulia-tui --editor "emacs -nw"

• The draft is a temporary .md file only you can read, removed when you come back.
• If the editor exits with an error or cannot be found, the text in the TUI stays as it was and the reason is shown.
• The rules of the forum (lengths, too many mentions...) are checked when you send, as with the built-in editor; if the forum rejects the post, the editor opens again with your text.
• Notifications keep arriving while you write; you see them when you come back.

Development

Everything runs in Docker:

docker compose run --rm dev sh -c 'ruff format src tests && ruff check src tests && mypy && pytest'

The tests drive the client and the interface (Textual's Pilot) against a real Tyrtulia instance running in-process, plus a real tyrtulia serve with Unix users inside the container.

e2e/run.sh runs the end-to-end test: on Debian with systemd, ten people use the real TUI in tmux against one Tyrtulia instance installed from PyPI. Five Unix users go through the socket and five SSH key accounts log in over HTTP; they post, answer, mention, edit, moderate, report and search, and see each other's notifications in real time.

Contributing

Contributions are welcome! Please see the contribution guidelines for instructions on how to submit issues or pull requests. Changes to the forum itself (the API, the server) belong in the Tyrtulia repository.

License

Tyrtulia TUI is free software, released under the GNU General Public License v3.0 or later.