stig 0.8.1a0

stig
====

stig is a TUI (text user interface) and CLI (command line interface)
client for the `BitTorrent client
Transmission <http://www.transmissionbt.com/>`__.

|image0|

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

.. code:: bash

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

Connect to non-default host and present the TUI

.. code:: bash

$ stig set srv.url torrents.local:1234

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

.. code:: bash

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

List torrents with more than 50 seeds, then remove them

.. code:: bash

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

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

.. code:: bash

$ 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)

.. code:: bash

$ 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

You can have different rc files and run them 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 <https://aur.archlinux.org/packages/stig>`__ and the latest
development version as
`stig-git <https://aur.archlinux.org/packages/stig-git>`__.

The `latest release <https://pypi.python.org/pypi/stig>`__ can be
installed from PyPI.

.. code:: bash

$ 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.

.. code:: bash

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

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.

Requirements
------------

- Python >=3.5
- `urwid <http://www.urwid.org/>`__ >=1.3.0
- `urwidtrees <https://github.com/pazz/urwidtrees>`__ >=1.0.3dev0
- `aiohttp <https://pypi.python.org/pypi/aiohttp>`__
- `pyxdg <https://pypi.python.org/pypi/pyxdg>`__
- `blinker <https://pypi.python.org/pypi/blinker>`__
- `natsort <https://pypi.python.org/pypi/natsort>`__
- `GeoIP <https://pypi.python.org/pypi/GeoIP>`__ (optional; shows
country codes in peer lists)
- `asynctest <https://pypi.python.org/pypi/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.

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 <https://www.gnu.org/licenses/gpl-3.0.txt>`__ for
more details.

.. |image0| image:: https://raw.githubusercontent.com/rndusr/stig/master/screenshot.png