stig: a TUI and CLI for the Transmission daemon

One command vocabulary, three ways to enter it

stig is a TUI and CLI client for the BitTorrent client Transmission, and the thing that makes it interesting is that the same command vocabulary is reachable four different ways.

Commands do almost everything, and they can be invoked through single-key or multi-key keybindings, in the style of emacs. They can be entered in a command prompt inside the TUI, in the style of vi, with tab completion. They can be provided as CLI arguments when invoking stig, in the style of git. And they can be listed in an rc file that is loaded automatically at startup.

The last of those is the design's centre of gravity. All configuration is done in an rc file, which is just a script containing a list of commands, in the style of vim and .vimrc, executed during startup. The default rc file lives at $XDG_CONFIG_HOME/stig/rc, and XDG_CONFIG_HOME defaults to $HOME/.config if it is not set. Because a default rc file is empty it is not created automatically, to avoid clutter.

That means stig is not configured through a settings file with key and value pairs, it is configured by writing commands. The example rc file in the documentation shows the shape: set connect.host and set connect.port for the daemon, set tui.poll to control how often lists refresh, set columns.torrents to pick default columns, and tab commands to open lists at startup.

You can also point stig at a different rc file with stig -c path/to/file, and the documentation notes you can turn an rc file into an executable with a shebang line, because -T disables the TUI and -c names the rc file.

Filters are the query language, and they are the real feature

Filters are used to select torrents for listing, starting and stopping, deleting and so on, and they are the part of stig that has no equivalent in a GUI torrent client.

A filter is a boolean expression over torrent attributes. The examples in the documentation give the flavour: list torrents with more than 50 seeds, then remove them, and stop torrents with a path matching a directory and a ratio above a threshold.

   $ stig ls 'seeds>50'
   $ stig rm 'seeds>50'

   $ stig stop 'path~/foo/&ratio>10'

The syntax uses the operators you would expect, greater-than for numeric comparisons, ampersand for conjunction, pipe for disjunction, and a prefix operator on attribute names for negation, so a leading exclamation mark or its spelling in the examples reverses a comparison. There is also a percentage-prefixed form for relative values, and attributes can be matched with a path prefix.

Combining filters is what makes them useful, because a compound expression can express a policy that a GUI would need several checkboxes and a script for. A single command can then act on the result, and the stig rm with the same filter expression is the clearest example of the design: the query and the action are the same string.

The same expression syntax appears in the tab example, where two tabs show different slices of the library with different sort orders, one listing slow uploads under a path with a rate threshold and the other small or well-seeded torrents sorted by size ascending and seeds descending.

Tabs, themes and the built-in documentation

Tabs let you open and switch between multiple lists, such as torrents, peers and files, and they are how stig handles the fact that a torrent client has several different views of the same data.

The tab example shows two tabs opened with different torrent lists and different sort orders in one command line:

   $ stig tab ls 'path~/foo/&rate-up<10k' \; tab ls 'size<500M|seeds>=1k' --sort 'size,!seeds'

The semicolon separates commands, which is the same escaping you see in the simpler example that sets a port and then lists active torrents:

   $ stig set connect.port 9092 \; ls active

The sort syntax takes a comma separated list of fields with a negation prefix for descending order, and there is a separate column syntax, since the rc example sets columns for torrent lists with set columns.torrents and passes --columns on individual tab commands.

The other two features are smaller. Color themes support 16 and 256 colors. And there is complete built-in documentation, reachable with the help command or the --help argument, which matters more than it sounds for a tool whose entire interface is a command language.

Tabs also connect back to the first feature. Because a tab is a list with a filter and a sort, a tab is a saved view, and the rc file can open several at startup, which turns the TUI into a dashboard of the views you actually care about rather than one list at a time.

Connecting to the daemon, and installing the client

stig talks to the Transmission daemon over its RPC interface, and the host and port are set with the same command language as everything else:

   $ stig set connect.host torrents.local

   $ stig set connect.port 9092 \; ls active

Installation is through PyPI, where the latest release always lives, and the documented recommendation is pipx, which installs applications in self-contained virtual environments under $HOME/.local/pipx/ with the executables symlinked into $HOME/.local/bin/:

    $ pipx install stig
    $ pipx upgrade stig
    $ pipx uninstall stig

Plain pip works too, installing into the system-wide or user-wide environment:

    $ pip3 install stig         # Installs in /usr/local/
    $ pip3 install --user stig  # Installs in $HOME/.local/

There are also distribution packages for Arch through the AUR with both a release and a git variant, for NixOS, and for Alpine Linux. The development version installs straight from the Git repository, and there are two extras. setproctitle strips arguments from the process title when running in a tmux session, which needs Python headers, and proxy tunnels the connection to the daemon through a SOCKS5, SOCKS4 or HTTP proxy.

The package metadata describes the shape of the thing. It is GPL-3.0-or-later, requires Python 3.10 or newer with classifiers through 3.15, and it is marked as an alpha development status, which for a tool in maintenance mode is a slightly odd label to carry. The dependencies are urwid for the terminal widgets, urwidtrees for the tree views, aiohttp for the async RPC, and a set of smaller ones: async_timeout, pyxdg for the XDG paths, blinker for signals, natsort and bidict for sorting and key ordering, and wcwidth for character width in the terminal. The console script is registered as stig, pointing at stig:run.

The optional extras map directly onto the two dependency additions, aiohttp-socks for the proxy extra and setproctitle for the process title one.

The API abstraction layer and what maintenance mode means for it

The feature list ends with a full API abstraction layer, which makes it possible to add support for other BitTorrent clients with RPC interfaces, with contributors welcome.

The repository topics tell you what sits underneath: asyncio, urwid for the terminal interface, transmission and transmission-daemon, bittorrent, and the tui and cli categories.

Then there is the notice at the top of the README, and it changes how you should read everything above. stig is in maintenance mode. The code needs to be split into multiple projects, and the current client does not really support more clients besides Transmission. The author asks that no feature pull requests be made, and explains why: the more time invested in reviewing and testing code that is going to be dead, the less time is left for future-proofing stig.

That is a candid statement of the situation, and it changes the practical reading of the abstraction layer. The layer exists, and the design intent was to support other clients through it, but the plan is now to split the code into separate projects rather than grow this one. So the abstraction is a foundation that was built in anticipation of an expansion that is not going to happen here.

For an adopter, the practical questions are therefore about the present rather than the future. Does the Transmission client cover the operations you need, including the filters you intend to write? Is the RPC version you run supported? And is the project going to keep working with new Transmission releases, given that the author is spending the time elsewhere?

The project metadata also shows the shape of the codebase and its tooling. The package is built with setuptools, the version is dynamic and read from stig.__version__, and there is a dev extra with pytest and tox. The repository carries a Makefile with a test target that builds a virtual environment in ./venv/, installs the package in editable mode with the dev extra, runs pytest with --exitfirst, and then checks that README.org converts correctly to reStructuredText for PyPI, which is a detail that only matters to a project that publishes its README from an org-mode file. There is a fulltest target that runs tox, flake8 and isort, and a release target that runs pyrelease against the CHANGELOG.

Where stig is the wrong tool

The first limitation is the one the author states: this client does not really support more than Transmission. If you run qBittorrent, Deluge or rtorrent, the abstraction layer is a promise rather than a feature, and you are choosing a client for one daemon in a world where most people run several.

The second limitation is the maintenance mode itself. No feature pull requests means the gap between what stig can do and what Transmission exposes will not close, and the plan to split the project into several repositories means the package you depend on today may not be the package you depend on in a year. That is a normal thing for a maintainer to do with their time, and it is a real risk for anyone whose scripts depend on stig.

The third limitation is the interface choice. A TUI is the right tool for a server you administer over SSH, and it is the wrong tool for a desktop user who wants a graphical queue with per-torrent buttons. stig is designed for the terminal, on a Unix-classified environment, and its scripting power is a substitute for a mouse rather than a preview of a richer interface.

The real alternatives divide cleanly by what you need. If you want a graphical client for the same daemon, Transmission's own GTK interface and alternatives for other daemons cover that, and they will always be a click away from the feature you want. If you want scripting against the daemon, then stig's competitor is not another torrent client but writing the RPC calls yourself, or using a small script against Transmission's RPC API, and the difference in effort is what stig saves you: the filter language, the sorting, the tab views, the rc file and the completion.

That last comparison is the honest one. stig's value is not that it can do things the daemon cannot, it is that it turns a set of RPC calls into a query language and a saved configuration, which is the difference between a script that works and a script that still works a year later. If you only need to start a torrent from cron, that value is close to zero, and the alternative of a two-line RPC call is simpler.

Editorial conclusion

Adopt stig if you run Transmission and want a terminal interface with filters and scripts over the same RPC API, and if you are willing to treat it as a finished tool rather than a platform. Do not adopt it if you need another Bitorrent client to work today, since the client abstraction is only designed for future clients and the current one does not really support more than Transmission. Before you rely on it, read the maintenance mode notice in the README, because the author is not taking feature pull requests, and check whether the Transmission RPC interface you depend on is covered by the built-in filters, since a filter you cannot express means falling back to a different client entirely.

Frequently asked questions

Official sources

1. Issues
2. License: GPL-3.0
3. README
4. rndusr/stig on GitHub