stig

stig is a TUI (text user interface) and CLI (command line interface) client for the BitTorrent client Transmission.

stig being in alpha status does not mean you should expect bugs. It’s supposed to indicate that behaviour may change with a new release since I’m still experimenting with what works best. If you know how to make stig more flexible, convenient, intuitive or just better, feel free to open an issue.

Features

Filters are used to list/start/stop/remove/etc torrents matching any combination of criteria
Tabs with list of torrents/peers/files, documentation, etc
Commands or sub-commands (think git) do everything, and they can be invoked
- through single- or multi-key (think emacs) keybindings,
- by entering them in a command prompt (think vi),
- by providing them as CLI arguments in your interactive shell or in scripts,
- or by listing them in an rc file.
Color themes support 16 and 256 colors
Complete built-in documentation with help command or --help argument
Full API abstraction layer makes it possible to add support for other BitTorrent clients with RPC interfaces (contributors are welcome)

Examples

Add two torrents, one by file and one by hash, and exit

$ stig add /path/to/some.torrent d4d6b73851fe3288e40389a8e1fb98124a9b9ba5

Connect to non-default host and present the TUI

$ stig set srv.url torrents.local:1234

Print all uploading and/or downloading torrents on torrents.local and exit

$ stig set srv.url torrents.local \; ls active

List torrents with more than 50 seeds, then remove them

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

Stop/pause torrents with /foo/ in their download path and a ratio above 10

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

Open two tabs with different torrent lists:

slowly uploading torrents with /foo/ in their download path
small or well-seeded torrents, sorted by size (ascending) and number of seeds (descending)

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

Configuration and Scripting

All configuration is done in an rc file which contains a list of commands that are executed during startup. The default rc file is $XDG_CONFIG_HOME/stig/rc. XDG_CONFIG_HOME defaults to ~~/.config~ if not set.

See stig help rcfile for more information.

Example rc file

# Host that runs Transmission daemon
set srv.url otherhost:123

# Poll every 10 seconds
set tui.poll 10

# Default columns in torrent lists
set columns.torrents name ratio rate-up rate-down

# Open a few tabs on startup
tab ls active --sort !progress,path,!rate
tab ls paused --sort !progress --columns name,progress,ratio,size
tab ls isolated --sort tracker --columns name,path

Run different rc files either with stig -c path/to/file or with the rc command. You can even turn them into executables with the shebang #!/path/to/stig -Tc (-T disables the TUI, -c specifies the rc file).

Example maintenance script

#!/path/to/stig -Tc
rm path=/path/to/torrents/trash
pause seeds>100
start seeds<20&size>10G|seeds<50&size>20G

Installation

For Arch Linux stig is available on AUR as stig and the latest development version as stig-git.

The latest release can be installed from PyPI.

$ pip3 install stig         # Installs stig system-wide (/usr/local/)
$ pip3 install --user stig  # Installs stig in your home (~/.local/)

Install the latest development version from GitHub.

$ pip3 install [--user] git+https://github.com/rndusr/stig.git

To makes changes to the source code effective immediately, developers can either install stig with pip3 from a local path and pass the --editable option or run python3 -m stig in the project directory.

Extras

The following extras are available to enable optional features:

geoip: Display peers’ country codes

To automatically install depdencies for an extra, append [<EXTRA1>,<EXTRA2>,...] to the installation source.

$ pip3 install 'stig[geoip]'

Requirements

Python >=3.5
urwid >=1.3.0
urwidtrees >=1.0.3dev0
aiohttp
pyxdg
blinker
natsort
GeoIP (optional; shows country codes in peer lists)
setproctitle (optional; prettifies the process name)
asynctest (only needed to run tests)

Contributing

Pull requests, bug reports, features requests, ideas for improvement and all other constructive contributions are welcome.

If you want to contribute code and get stuck, don’t know where to even begin, or just to make sure you’re not duplicating someone else’s efforts, open an issue.

Please submit your custom themes if you would like them to be included in stig.

License

stig is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

fleischkatapult / stig