Note that the ! character has to be escaped in shell commands. For a current full list of all the field names and their meaning, see the output of the --help-fields option of rtcontrol which gives you a complete list for your installation.

The following rtcontrol Filter Conditions give you a hint on what you can do, and some building blocks for more complex conditions.

The ‘trick’ here is the -V ( --view-only ) option, which shows the selection result in a rTorrent view instead of on the console. You can add this to any query you execute on the command line, and then interactively work with the result. The above commands are just shortcuts for common use-cases, directly callable from the curses UI.

You can of course add as many commands as you like, and include sorting options and whatever else rtcontrol offers.

You already have the following configuration commands, if you followed the Configuration Guide .

Anyone who ever dreamt about a search box in their rtorrent UI, dream no more…

And finally, from version 0.4.1 onwards, you can use a full templating language instead of the simple field lists or string interpolation described above, more on that in Using Output Templates .

And with version 0.3.6 installed, you can create a full listing of all the files you have loaded into rTorrent using the predefined format “ files ”:

You can also append one or more format specifiers to a field name, separated by a . . These take the current value and transform it — in the above example .raw.delta means “take an unformatted time value and then convert it into a time delta relative to just now.” The option --help-fields lists the available format specifiers.

See PyFormat for a description how the formatting options work, and notice that $ is used instead of % here, because % has a special meaning in INI files. For the same reason, a single % in the final output becomes $(pc)s in the configuration ( pc is a system field that is simply a percent sign).

You need to define the custom output format used there, so also add this to your ~/.pyroscope/config.ini :

Starting with version 0.3.5, you can define custom output formats and print column headers, the rt2days example from the previous section becomes this:

Before describing the possible options for output formatting in more details below, here’s a short overview of the possible methods, each with an example:

See the rt-alias.sh file of the pimp-my-box project for these and some more aliases.

If you feed the list of paths into normal ls as shown, you have all the usual options available to you.

rt2days gives the completion history of the last 48 hours, and rtls lets you create lists of files just like ls :

You might want to add the following alias definitions to your ~/.bashrc :

You need to have Octave installed, on Debian/Ubuntu all you need is sudo aptitude install octave3.0 .

The following will create a normalized histogram of ratio distribution of your loaded torrents. Each bar indicates the percentage of items in a ratio class (i.e. the first bar shows ratios up to 1).

Starting with version 0.4.1, you can also request a statistical summary of your numerical output columns, like this:

You can easily modify this by using conditions other than * , e.g. show the count of fully seeded downloads using ratio=+1 . Or try the same command with traits instead of alias (version 0.3.7 only).

Create a list of all your trackers and how many torrents are loaded for each:

Note that you already have that command added if you followed the Configuration Guide .

As with --cull , a shortcut command to call this from the curses UI is useful:

For technical reasons, rTorrent has to create files that you have deselected from download to save data of chunks that border selected files, and this option can be a great time saver, especially on large torrents containing hundreds of files. So, unless you have filtered out incomplete items by the appropriate conditions, using --purge instead of --delete is always the better option.

Starting with version 0.3.10, the --purge option (a/k/a --delete-partial ) allows you to not only delete the selected items from the client, but at the same time delete any incomplete files contained in them (i.e. files that are part of an incomplete chunk).

Just select the item you want to annihilate and enter cull= into the command prompt ( Ctrl-X ). Note that you already have that command added if you followed the Configuration Guide .

If you define the following command shortcut, you can also delete the current item directly from ncurses (needs version 0.4.1 to work):

When you call rtcontrol --cull … from the shell, you will first be presented with the number of items found and then asked for each of them whether you want to delete it (interactive mode is on by default). Therefor, for automatic uses in cron, you should also specify the --yes option.

Using the option --cull of version 0.3.10, an item can be deleted including its data. You can do this either manually, or automatically as a part of Ratio Management . A full example of automatic space management is shown in the _cron_sweep script, and its sweep_rules include file with customizable rules.

The first command selects the broken items into a rTorrent view, so that you can watch the progress of hashing and the results afterwards. If all of them are finished, you can then start those that were successfully restored like so:

Sometimes rTorrent loses track of where it stores the data for an item, leading to an empty Base path in the Info panel. You can try to fix this by selectively rehashing those, with these commands:

Performing Periodic Tasks¶

Simple Queue Management¶ This is a queue management one-liner (well, logically one line). Before you run it automatically, add a trailing “-n” to test it out, e.g. play with the queue size parameter and check out what would be started. Then put it into a script, crontab that and run it every (few) minute(s). export rt_max_start = 6 ; rtcontrol -q --start --yes hash = $( echo $( \ rtcontrol -qrs is_active -o is_open,hash is_complete = no is_ignored = no \ | head -n $rt_max_start | grep ^CLS | cut -f2 ) | tr " " , ) It works by listing all incomplete downloads that heed commands and sorting the already active ones to the top. Then it looks at the first rt_max_start entries and starts any closed ones. Note that this means you can exempt items from queue management easily by using the I key in the curses interface. See rTorrent Queue Manager for a much better solution.

Move on Completion¶ The following moves completed downloads still physically residing in a work directory (change the realpath filter when you named your download directory differently), to another directory (note that you can restrict this further, e.g. to a specific tracker by using “alias=NAME”). You don’t need any multiple watch folders or other prerequisites for this. rtcontrol --from-view complete 'realpath=*/work/*' -qo '~/bin/rtmv "$(path)s" ~/rtorrent/done --cron' | bash Test it first without the | bash part at the end, to make sure it’ll in fact do what you intended. Another advantage is that in case you ever wanted to switch clients, or exchange the drive you host the data on, you can do so easily since all the active downloads still reside at one place in your download directory (in form of a bunch of symlinks) — even if their data is scattered all over the place in reality. You can also extend it to create more organized completion structures, e.g. creating a directory tree organized by month and item type, as follows: RT_SOCKET=/home/bt/rtorrent/.scgi_local # Move completed torrents to "done", organized by month and item type (e.g. "2010-09/tv/avi") */15 * * * * test -S $RT_SOCKET && ~/bin/rtcontrol --from-view complete 'realpath=*/work/*' -qo '~/bin/rtmv "$(path)s" ~/rtorrent/done//$(now.iso).7s/$(traits)s --cron' | bash The above is a fully working crontab example, you just have to adapt the paths to your system. If you want to create other organizational hierarchies, like “by tracker”, just replace the $(now.iso).7s/$(traits)s part by $(alias)s . And if you don’t want the file type in there (i.e. just “tv”), use $(traits.pathdir)s to have it removed. To get themed trackers specially treated, you can add hints to the [TRAITS_BY_ALIAS] section of the config (see config.ini.default for examples). Afterwards, you can always move and rename stuff at will and still continue seeding, by using the rtmv tool in version 0.3.7 ­— this will rename the data file or directory at its current location and automatically fix the symlink in the download directory to point at the new path. Example: cd ~/rtorrent/done/2010-09/tv/avi rtmv foo.avi bar.avi

Ratio Management¶ While rTorrent has a built-in form of ratio management since a few versions, it’s hard to use after-the-fact and also hard to understand — you need to have different watch directories and complex settings in your .rtorrent.rc to use that. It can be much simpler — a basic form of ratio management using rtcontrol looks like this: rtcontrol is_complete = yes is_open = yes ratio = +1.1 alias = sometracker,othertracker --stop You will always want to have the is_complete=yes is_open=yes ratio=+1.1 part, which excludes all torrents that are still downloading, closed or not having the necessary ratio. Another basic filter is is_ignored=no , which excludes items that have their ignore commands flag set (via the I key) from ratio management. To that you can add anything you think fits your needs, and also use several commands with different minimum ratios for different trackers by selecting them using alias or tracker , like in the example above. Assuming you have your original seeds in a directory named seed and don’t want to ratio-limit them, one thing you might add is 'datapath=!*/seed/*' to prevent them from being stopped. Only your imagination (and the available fields) are the limit here. If you then put these commands into a script that runs every few minutes via cron , you have a very flexible form of ratio management that can be changed on a whim. Note For cron use, you’ll want to add the --cron --yes options to any rtcontrol commands. The first one redirects logging to a special logfile ~/.pyroscope/log/cron.log , and the second positively answers any prompts that would appear when using --delete or --cull . To complete your command line, you add the action you want to take on the torrents found, in the above example --stop ; --delete is another possibility, which removes the item from the client, but leaves the data intact. Starting with version 0.3.10, you can also delete the downloaded data by using the --cull option. You can also protect items from removal by using activity indicators, specifically the active and last_xfer fields. The condition active=+10i checks that no peer was connected in the last 10 minutes, while last_xfer=+10i does the same for the last time data was transferred. Note that data transferred means either upload or download went over the threshold defined by pyro.last_xfer.min_rate (in bytes/s, with a default of 5000).

Bandwidth Management¶ Say you want to have torrents that are already seeded back take a back-seat when other torrents with a ratio less than 100% are active — but when they’re not, all torrents should take full advantage of the available bandwidth. The last part is not possible with the built-in throttle groups, but here’s a fix that works by setting the maximum rate on the seed throttle dynamically. Put this into your .rtorrent.rc : throttle_up = seed,900 Then save the dynamic seed throttle script into ~/bin/rt_cron_throttle_seed . Finally, extend your crontab with these lines ( crontab -e ): RT_SOCKET=/home/bt/rtorrent/.scgi_local BW_SEED_MAX=900 BW_SEED_SLOW=200 # Throttle torrents that are seeded 1:1 when there are other active ones * * * * * test -S $RT_SOCKET && ~/bin/rt_cron_throttle_seed seed $BW_SEED_MAX $BW_SEED_SLOW --cron # Put torrents seeded above 1:1 into the seed throttle */10 * * * * test -S $RT_SOCKET && rtcontrol ratio=+1.05 is_complete=1 is_ignored=0 throttle=none -q -T seed --yes --cron The 900 and 200 in the above examples are the bandwidth limits in KiB/s, you need to adapt them to your connection of course, and all paths need to be changed to fit your system. Each time the throttle rate is changed, a line like the following will be appended to the file ~/.pyroscope/log/cron.log : 2010 - 08 - 30 14 : 16 : 01 INFO THROTTLE 'seed' up = 200.0 KiB / s [ 2 prioritized ] [ __main__ . SeedThrottle ]