termtorrent guide: a terminal torrent client from socket to keyboard
This terminal torrent client has no configuration file of its own. There are three things to get right: rtorrent must run, its SCGI socket must be reachable, and Python must be present.
1. Install the requirements
On Debian or Ubuntu:
sudo apt install python3 rtorrentncurses ships with Python, so there are no third-party Python packages to install. On other systems, install Python 3.6 or newer and rtorrent 0.9.x from your package manager or ports tree.
2. Enable the SCGI socket in rtorrent
Add one line to ~/.rtorrent.rc and restart rtorrent:
network.scgi.open_local = /home/YOURUSER/.rtorrent-scgi.sockA TCP socket also works, for example when termtorrent runs on another machine:
network.scgi.open_port = 127.0.0.1:5000termtorrent looks for ~/.rtorrent-scgi.sock by default. Point it somewhere else with the RTORRENT_SCGI environment variable:
RTORRENT_SCGI=/home/you/other.sock termtorrentIf you expose a TCP socket beyond localhost, put it behind a firewall or an SSH tunnel. The socket has no authentication of its own; anyone who can reach it can control the client.
3. Install termtorrent
sudo ./install.shThe installer copies the script to /usr/local/bin/termtorrent. Or skip it and copy the script anywhere on your PATH:
install -m 0755 termtorrent ~/.local/bin/termtorrent4. Run termtorrent
termtorrentKeyboard reference
| Key | Action |
|---|---|
| Tab | Switch between the torrent list and the buttons |
| Up / Down, PgUp / PgDn | Select a torrent |
| a | Add a URL, magnet link or .torrent file |
| s / S | Start / stop the selected torrent |
| d | Remove the selected torrent |
| Enter or o | Open details |
| l | Set download and upload limits |
| r | Refresh now |
| ? | Help |
| q | Quit |
Mouse and terminals
Mouse support depends on the terminal. It generally works in xterm-compatible emulators and in tmux with mouse mode enabled. On a plain Linux console you need gpm. The keyboard always works and is the more predictable path over SSH.
Removing data, safely
Removing a torrent without deleting data is the default and leaves files alone. The remove-and-delete action only deletes inside the download directory, ~/downloads by default, which can be overridden with RTORRENT_DOWNLOAD. Check the details dialog for the directory before deleting if you keep data elsewhere.
Troubleshooting
termtorrent shows an empty list
Check that rtorrent is running and that the socket path matches. The default is ~/.rtorrent-scgi.sock; set RTORRENT_SCGI if you use another path or a TCP port.
Permission denied on the socket
The socket is owned by the user running rtorrent. Run termtorrent as that user, or adjust the socket permissions deliberately. Do not make it world-writable on a shared host.
The interface looks broken
Use a UTF-8 locale and a terminal of at least 80x24. termtorrent uses ncurses, so TERM must be set correctly; tmux and screen are supported.
If the socket exists but the list stays empty, verify that rtorrent is actually running with the same configuration file and user. A socket left behind by a crashed client looks like a live one until a connection is attempted.
Uninstall
sudo rm /usr/local/bin/termtorrentThere is no state to clean up: termtorrent stores nothing of its own. rtorrent’s session and data files are untouched.