Commands Reference

The reference chapter lists all relevant XMLRPC and ‘private’ commands provided by rTorrent with a short explanation. See the Scripting Guide on how to combine them into meaningful command sequences, and Using XMLRPC for Remote Control for some general hints on using the XMLRPC API

Use the search box in the sidebar to find specific commands, or the Search Page. The generated index also lists all the command names.

The following are similar, but incomplete resources:

Download Items and Attributes

d.* commands

All d.* commands take an info hash as the first argument when called over the XML-RPC API, to uniquely identify the target object. ‘Target’ is the term used for that 1st parameter in error messages and so on.

d.name = ‹hash› ≫ string ‹name›

When called within configuration methods or in a Ctrl-X prompt, the target is implicit.

d.multicall2
d.multicall.filtered
download_list

‘d.multicall.filtered’ is rTorrent-PS 1.1+ only

d.multicall2 = ‹view›, [‹cmd1›=[‹args›][, ‹cmd2›=…]] ≫ list of lists of results ‹rows of results›
d.multicall.filtered = ‹view›, ‹predicate›, [‹cmd1›=[‹args›][, ‹cmd2›=…]] ≫ same as 'multicall2'
download_list = ‹view› ≫ list of strings ‹info hashes›

These commands iterate over the content of a given view, or default when the view is omitted or empty. download_list always just returns a list of the contained infohashes.

d.multicall2 iterates over all items in view and calls the given commands on each, assembling the results of those calls in a row per item. Typically, the given commands either just have a side effect (e.g. d.stop), or return some item attribute (e.g. d.name).

d.multicall.filtered is only available in rTorrent-PS, and evaluates the predicate condition as a filter for each item, only calling the commands for items that match it. See elapsed.greater for an example.

If you request a lot of attribute values on all items, make sure you set a big enough value for network.xmlrpc.size_limit to hold all the returned data serialized to XML. It is also valid to pass no commands at all to d.multicall2, but all you get from that is a list of empty lists.

Example

$ rtxmlrpc --repr d.multicall2 '' tagged d.hash= d.name= d.custom=category
[['91C588B9A9B5A71F0462343BC74E2A88C1E0947D',
  'sparkylinux-4.0-x86_64-lxde.iso',
  'Software'],
 ['17C14214B60B92FFDEBFB550380ED3866BF49691',
  'sparkylinux-4.0-x86_64-xfce.iso',
  'Software']]

$ rtxmlrpc --repr download_list '' tagged
['91C588B9A9B5A71F0462343BC74E2A88C1E0947D',
 '17C14214B60B92FFDEBFB550380ED3866BF49691']
d.name
d.base_filename
d.base_path
d.directory
d.directory.set
d.directory_base
d.directory_base.set
d.name = ‹hash› ≫ string ‹name›
d.base_filename = ‹hash› ≫ string ‹basename›
d.base_path = ‹hash› ≫ string ‹path›
d.directory = ‹hash› ≫ string ‹path›
d.directory_base = ‹hash› ≫ string ‹path›
d.directory.set = ‹hash›, ‹path› ≫ 0
d.directory_base.set = ‹hash›, ‹path› ≫ 0

These commands return various forms of an item’s data path and name, and the last two can change the path, and sometimes the name in the file system. Note that rTorrent-PS can also change the displayed name, by setting the displayname custom attribute using d.custom.set.

Basics:

  • d.base_filename is always the basename of d.base_path.
  • d.directory_base and d.directory are always the same.
  • d.base_filename and d.base_path are empty on closed items, after a restart, i.e. not too useful (since 0.9.1 or so).

Behaviour when d.directory.set + d.directory_base.set are used (tested with 0.9.4):

  • d.base_path always remains unchanged, and item gets closed.

  • d.start sets d.base_path if resume data is OK.

  • ‘single’ file items (no containing folder, see d.is_multi_file):

    • d.directory[_base].setd.name is never appended (only in d.base_path).
    • after start, d.base_path := d.directory/d.name.
  • ‘multi’ items (and yes, they can contain just one file):

    • d.directory.setd.name is appended.
    • d.directory_base.setd.name is not appended (i.e. item renamed to last path part).
    • after start, d.base_path := d.directory.

Making sense of it (trying to at least):

  • d.directory is always a directory (thus, single items auto-append d.name in d.base_path and cannot be renamed).
  • d.directory_base.set means set path plus basename together for a multi item (thus allowing a rename).
  • only d.directory.set behaves consistently for single+multi, regarding the end result in d.base_path.

The definition below is useful, since it always contains a valid path to an item’s data, and can be used in place of the unreliable d.base_path.

# Return path to item data (never empty, unlike `d.base_path`);
# multi-file items return a path ending with a '/'.
method.insert = d.data_path, simple,\
    "if=(d.is_multi_file),\
        (cat, (d.directory), /),\
        (cat, (d.directory), /, (d.name))"
d.state
d.state_changed
d.state_counter
d.is_open
d.is_active
d.state = ‹hash› ≫ bool (0 or 1)
d.state_changed = ‹hash› ≫ value ‹timestamp›
d.state_counter = ‹hash› ≫ value ‹count›
d.is_open = ‹hash› ≫ bool (0 or 1)
d.is_active = ‹hash› ≫ bool (0 or 1)

These commands return the item’s state (1 = started or paused, 0 = stopped), when that changed the last time, and how often it did change. Note that although pausing / resuming a started item does not change state, the timestamp and counter are.

In summary:

  • Closed items are not open, with state=0.
  • Paused items are open, but not active, with state=1.
  • Started items are both open and active, with state=1.

The three state values are persisted to the session, while active (paused) is not. See How Can I Stop All Torrents From a Shell? on how you can use that to influence the startup behaviour of rTorrent.

d.open
d.close
d.pause
d.resume
d.close.directly
d.try_close
TODO
d.start
d.stop
d.try_start
d.try_stop

Starts or stops an item, including everything that needs to be done for that. For starting, that includes hashing the data if it already exists. On stop, incomplete chunks are discarded as part of the stop.

The try variants look at the d.ignore_commands flag and thus only conditionally start/stop the item.

d.loaded_file
d.tied_to_file
d.tied_to_file.set

d.loaded_file is the metafile from which this item was created. After loading from a watch directory, this points to that watch directory, but after a client restart it is the session file (since the item is then loaded from there).

d.tied_to_file also starts out as the file the item is initially created from, but can be set to arbitrary values, and an item can be untied using d.delete_tied, leading to an empty value and the deletion of the tied file.

One of the stop_untied, close_untied, or remove_untied commands can then be used in a schedule to stop, close, or remove an item that lost its tied file, including when you delete or move it from the outside in a shell or cron job.

d.accepting_seeders
d.accepting_seeders.disable
d.accepting_seeders.enable
d.accepting_seeders = ‹hash› ≫ bool (0 or 1)
d.accepting_seeders.disable = ‹hash› ≫ 0
d.accepting_seeders.enable = ‹hash› ≫ 0

Controls whether or not new connections to seeders are sought out. Existing connections are not effected.

d.bitfield
d.bitfield = ‹hash› ≫ string ‹bitfield›

Returns the bitfield represented by a string of hexadecimal digits, with each character representing the “completeness” of each field. Note that due to rounding inaccuracies, the number of fields with likely neither align exactly with the number of chunks nor number of bytes.

d.bytes_done
d.bytes_done = ‹hash› ≫ value ‹bytes›

This tracks the amount of bytes for a torrent which has been accepted from peers. Note that bytes aren’t considered to be “completed” until the full chunk is downloaded and verified. See d.completed_bytes for that value. See also d.left_bytes for the number of bytes yet to be accepted.

d.check_hash
d.check_hash = ‹hash› ≫ 0

Checks the piece hashes of an item against its data. Started items are paused during the rehashing.

d.chunk_size
d.chunk_size = ‹hash› ≫ value ‹size›

Returns the item’s chunk size in bytes (also known as the “piece size”).

d.chunks_hashed
d.chunks_hashed = ‹hash› ≫ value ‹chunks›

While a torrent is hash checking, this tracks the number of chunks that have successfully hashed.

d.chunks_seen
TODO
d.complete
d.incomplete
d.complete = ‹hash› ≫ bool (0 or 1)
d.incomplete = ‹hash› ≫ bool (0 or 1)

Indicates whether an item is complete (100% done) or not.

d.completed_bytes
d.completed_chunks
d.completed_bytes = ‹hash› ≫ value ‹bytes›
d.completed_chunks = ‹hash› ≫ value ‹chunks›

Returns the number of completed bytes and chunks, respectively. “Completed” means the bytes/chunk has been downloaded and verified against the hash.

d.connection_current
d.connection_current.set
d.connection_leech
d.connection_seed
TODO
TODO
d.delete_tied
d.delete_tied = ‹hash› ≫ 0

Delete the d.tied_to_file, which obviously also unties the item. This command is bound to the U key by default, and also called whenever an item is erased.

Example

# Delete metafile from a watch dir directly after loading it
# (note that a copy still remains in the session directory)
schedule2 = watch_cleaned, 29, 10, \
    ((load.normal, (cat,(cfg.watch),"cleaned/*.torrent"), "d.delete_tied="))
d.creation_date
d.creation_date = ‹hash› ≫ value ‹timestamp›

Returns a timestamp reflecting the .torrent file creation date (i.e. separate from the date the item was loaded into the client). This value can be inspected with tools like lstor:

$ lstor -o 'creation date' file.torrent
1480229112

TODO What does this return for magnet files?

d.custom
d.custom.set
d.custom_throw
d.custom1
d.custom1.set
d.custom2…5
d.custom2…5.set
d.custom[_throw] = ‹hash›, string ‹key› ≫ string ‹value›
d.custom.set = ‹hash›, string ‹key›, string ‹value› ≫ 0
d.custom1 = ‹hash› ≫ string ‹value›
d.custom1.set = ‹hash›, string ‹value› ≫ 0

Set and return custom values using either arbitrary keys, or a limited set of 5 numbered slots. Note that d.custom1 is not the same as d.custom=1 or d.custom=custom1, and can only be accessed by its assigned commands.

If d.custom is called for a key that doesn’t exist, it will return an empty string, unlike d.custom_throw which throws a No such custom value error.

Try to avoid the numbered versions, they’re obviously limited, and collisions with other uses are quite likely. ruTorrent for example uses #1 for its label, and the other slots for various other purposes.

Warning

Never add spaces after the key when using new syntax, i.e. (d.custom, bugfest  ) will look for the bugfest␣␣ key.

d.custom.if_z

rTorrent-PS 1.1+ only

d.custom.if_z = ‹hash›, string ‹key›, string ‹default› ≫ string ‹value›

Just like d.custom, but returns the ‹default› value if the ‹key› does not exist, or if its value is empty.

d.custom.keys

rTorrent-PS 1.1+ only

d.custom.keys = ‹hash› ≫ list of string ‹defined keys›

Returns a list of custom keys that are defined for an item.

Example

$ rtxmlrpc --repr d.custom.keys $(rtxmlrpc download_list | head -n1) | tr -d \\n
[… 'tm_downloaded', 'tm_last_scrape', 'tm_loaded', 'tm_started']
d.custom.items

rTorrent-PS 1.1+ only

d.custom.items = ‹hash› ≫ map of key / value strings ‹defined items›

Returns keys and their associated values, for all custom values of an item.

Example

$ rtxmlrpc --repr d.custom.items $(rtxmlrpc download_list | head -n1)
{…
 'tm_downloaded': '1522406424',
 'tm_last_scrape': '1527931151',
 'tm_loaded': '1522406432',
 'tm_started': '1522406432'}
d.disconnect.seeders
d.disconnect.seeders = ‹hash› ≫ 0

Cleanly drop all connections to seeders. This does not prevent them from reconnecting later on.

d.down.choke_heuristics
d.down.choke_heuristics.leech
d.down.choke_heuristics.seed
d.down.choke_heuristics.set
TODO
d.down.rate
d.down.total
d.down.rate = ‹hash› ≫ value ‹rate [bytes/s]›
d.down.total = ‹hash› ≫ value ‹total [bytes]›

The total amount and current rate of download traffic for this item. It’s possible for the total download to be greater than d.size_bytes, due to error correction or discarded data.

d.downloads_max
d.downloads_max.set
d.downloads_min
d.downloads_min.set
d.downloads_max = ‹hash› ≫ value ‹max›
d.downloads_max.set = ‹hash›, value ‹max› ≫ 0
d.downloads_min = ‹hash› ≫ value ‹max›
d.downloads_min.set = ‹hash›, value ‹max› ≫ 0

Control the maximum and minimum download slots that should be used per item. rTorrent will attempt to balance the number of active connections so that the number of unchoked connections is between the minimum and maximum, which means that these are not hard limits, but are instead goals that rTorrent will try to reach.

0 means unlimited, and while d.downloads_max can be set to less than d.downloads_min, rTorrent will then use d.downloads_min as the maximum instead.

d.erase
TODO
d.free_diskspace
d.free_diskspace = ‹hash› ≫ value ‹bytes›

Return the minimum free space of devices where files of the item reside on. In the usual case without symlinks and the like, it’s the free space of the drive holding d.directory.

d.group
d.group.name
d.group.set
TODO
d.hash
d.hash = ‹hash› ≫ string ‹hash›

Returns the hash of the torrent in hexadecimal form, with uppercase letters. The most common use is in the command list of a d.multicall2, to return the hash in a list of results. It can also be used to check if a hash already exists in the client – while most other getters can serve the same purpose, this is the obvious one to use for that.

If you are looking to cause a hash check, see d.check_hash.

d.hashing
d.hashing = ‹hash› ≫ value ‹hash_status›

Returns an integer denoting the state of the hash process. The possible values are:

  • 0 – No hashing is happening.
  • 1 – The very first hash check is occurring.
  • 2 – If pieces.hash.on_completion is enabled, the torrent is in the middle of hashing due to the finish event, and at the end, will be checked for completeness.
  • 3 – A rehash is occurring (i.e. the torrent has already been marked as complete once).

See also d.is_hash_checking.

d.hashing_failed
d.hashing_failed.set
d.hashing_failed = ‹hash› ≫ bool (0 or 1)
d.hashing_failed.set = ‹hash›, bool (0 or 1) ≫ 0

Checks to see if the hashing has failed or not. This flag is primarily used to determine whether or not a torrent should be marked for hashing when it’s started/resumed.

d.ignore_commands
d.ignore_commands.set
d.ignore_commands = ‹hash› ≫ bool (0 or 1)
d.ignore_commands.set = ‹hash›, bool (0 or 1) ≫ 0

The ignore flag controls the d.try_close, d.try_start, and d.try_stop commands, and if set to true exclude the item at hand from reacting to those commands.

One use of that is being able to exclude items from ratio control, if you use the try versions in group.seeding.ratio.command definitions.

d.is_hash_checked
d.is_hash_checking
d.is_hash_checked = ‹hash› ≫ bool (0 or 1)
d.is_hash_checking = ‹hash› ≫ bool (0 or 1)

These mark the hashing state of a torrent. d.is_hash_checked is counter-intuitive in that regardless of how much the torrent has successfully completed hash checking, if a torrent is active and is not in the middle of hashing (i.e. d.is_hash_checking returns 0), it will always return 1.

d.is_meta

since rTorrent-PS 1.1 / rTorrent 0.9.7

d.is_meta = ‹hash› ≫ bool (0 or 1)

Meta torrents refer to magnet torrents which are still in the process of gathering data from trackers/peers. Once enough data is collected, the meta torrent is removed and a “regular” torrent is created. Since meta torrents lack certain data fields, this is useful for filtering them out of commands that don’t play well with them.

d.is_multi_file
d.is_multi_file = ‹hash› ≫ bool (0 or 1)

Returns 1 if the torrents is marked as having multiple files, 0 if it’s a single file. Note that multifile-marked torrents are able to only have 1 actual file in them. See d.size_files for returning the number of files in an item.

d.is_not_partially_done
d.is_partially_done
TODO
d.is_pex_active
d.is_pex_active = ‹hash› ≫ bool (0 or 1)

Return whether PEX is active for this item. See protocol.pex to determine if PEX is active globally.

d.is_private
d.is_private = ‹hash› ≫ bool (0 or 1)

Indicates if the private flag is set. If it is, the client will not attempt to find new peers in addition to what a tracker returned (i.e. PEX and DHT are inactive).

d.left_bytes
d.left_bytes = ‹hash› ≫ value ‹bytes›

Tracks the number of bytes that have yet to be downloaded. See d.bytes_done for the inverse value, e.g. d.left_bytes plus d.bytes_done will always equal d.size_bytes.

d.load_date
d.load_date = ‹hash› ≫ value ‹time›

Returns the timestamp of when the torrent was loaded into the client. This is the value used when comparing fast-resume data against the actual files. Note that all torrents are considered to be newly loaded when pulled from the session directory, so this value will update every time rTorrent is restarted.

d.local_id
d.local_id_html
d.local_id = ‹hash› ≫ string ‹ID›
d.local_id_html = ‹hash› ≫ string ‹ID›

Returns the peer ID assigned to this item. This is the same value that is sent to the tracker when announces are done. d.local_id returns a hex string, while d.local_id_html returns the value percent encoded. See p.id to find this value for remote peers.

d.max_file_size
d.max_file_size.set
d.max_file_size = ‹hash› ≫ value ‹bytes›
d.max_file_size.set = ‹hash›, value ‹bytes› ≫ 0

Controls the maximum size of any file in the item. If a file exceeds this amount, the torrent cannot be opened and an error will be shown. Defaults to the value of system.file.max_size at the time the torrent is added.

d.max_size_pex
TODO
d.message
d.message.set
d.message.alert

d.message.alert is rTorrent-PS 1.1+ only

d.message = ‹hash› ≫ string ‹message›
d.message.set = ‹hash›, string ‹message› ≫ 0
d.message.alert = ‹hash› ≫ value ‹category›

Used to store messages relating to the item, such as errors in communicating with the tracker or a hash check failure.

The d.message.alert command returns an enum categorizing messages into classes, used for the configurable canvas of rTorrent-PS:

  • 0 ALERT_NORMAL
  • 1 ALERT_NORMAL_CYCLING (Tried all trackers)
  • 2 ALERT_GENERIC
  • 3 ALERT_TIMEOUT
  • 4 ALERT_CONNECT
  • 5 ALERT_REQUEST
  • ¿? 6 ALERT_GONE
  • 7 ALERT_PERMS
d.mode
TODO: Does not appear to be functional, only throws Object operator [mode] could not find element.
d.peer_exchange
d.peer_exchange.set
d.peer_exchange = ‹hash› ≫ bool (0 or 1)
d.peer_exchange.set = ‹hash›, bool (0 or 1) ≫ 0

Determines if PEX is enabled for this item. By default this is set to the value of protocol.pex.

d.peers_accounted
d.peers_complete
d.peers_connected
TODO
d.peers_max
d.peers_max.set
d.peers_min
d.peers_min.set
d.peers_not_connected
TODO
d.priority
d.priority.set
d.priority_str
d.priority = ‹hash› ≫ value ‹prio›
d.priority.set = ‹hash›, value ‹prio› ≫ 0
d.priority_str = ‹hash› ≫ string ‹name›

Controls the priority of the item. The possible settings (and the associated value) are as follows:

  • 0 – off
  • 1 – low
  • 2 – normal
  • 3 – high
d.ratio
Returns the current upload/download ratio of the torrent. This is the amount of uploaded data divided by the completed bytes multiplied by 1000. If no bytes have been downloaded, the ratio is considered to be 0.
d.save_full_session

Flushes the item’s state to files in the session directory (if enabled). This writes all files that contribute to an item’s state, i.e. the ‘full’ state.

See also session.save and d.save_resume below.

d.save_resume

Similar to d.save_full_session, but skips writing the original metafile, only flushing the data in the *.libtorrent_resume and *.rtorrent files.

The new data is written to *.new files and afterwards renamed, if writing those files succeeded.

d.size_bytes
d.size_chunks
d.size_files
d.size_pex
d.size_bytes = ‹hash› ≫ value ‹bytes›
d.size_chunks = ‹hash› ≫ value ‹chunks›
d.size_files = ‹hash› ≫ value ‹files›
d.size_pex = ‹hash› ≫ value ‹peers›

Returns the various size attributes of an item.

  • bytes – The total number of bytes in the item’s files.
  • chunks – The number of chunks, including the trailing chunk.
  • files – The number of files (does not include directories).
  • pex – The number of peers that were reported via the PEX extension. If d.is_pex_active is false, this will be always be 0.
d.skip.rate
d.skip.total
d.skip.rate = ‹hash› ≫ value ‹rate›
d.skip.total = ‹hash› ≫ value ‹total›

Skipped pieces are ones that were received from peers, but weren’t needed and thus ignored. These values are part of the main download statistics, i.e. d.down.rate and d.down.total.

d.throttle_name
d.throttle_name.set
TODO
d.timestamp.finished
d.timestamp.started
d.timestamp.finished = ‹hash› ≫ value ‹epoch›
d.timestamp.started = ‹hash› ≫ value ‹epoch›

Returns the time (as an epoch integer) the item was finished or started. These values are set when event.download.finished and event.download.resumed are triggered, respectively. If event.download.finished has not triggered yet, d.timestamp.finished will return 0.

d.tracker.insert
d.tracker.insert = ‹hash›, value ‹group›, string ‹url› ≫ 0

Inserts a tracker into a tracker group. A tracker group can be numbered from 0-32, and consists of multiple URLs.

d.tracker.send_scrape
d.tracker.send_scrape = ‹hash›, value ‹delay› ≫ 0

Manually triggers a scrape request after delay seconds. See `auto-scrape.rc`_ for an automated rTorrent scraping system.

d.tracker_announce
d.tracker_announce = ‹hash› ≫ 0

Manually triggers a tracker announce.

d.tracker_focus
d.tracker_size
d.tracker_focus = ‹hash› ≫ value ‹num›
d.tracker_size = ‹hash› ≫ value ‹num›

Returns the number of trackers assigned to the torrent.

d.tracker_numwant
d.tracker_numwant.set
d.tracker_numwant = ‹hash› ≫ value ‹numwant›
d.tracker_numwant.set = ‹hash›, value ‹numwant› ≫ 0

Controls the optional numwant parameter sent to the tracker. By default it’s set to -1, and rTorrent only sends numwant if it is greater than 0.

d.up.choke_heuristics
d.up.choke_heuristics.set
d.up.choke_heuristics.leech
d.up.choke_heuristics.seed
d.up.choke_heuristics.leech.set
d.up.choke_heuristics.seed.set

TODO

d.up.choke_heuristics.leech.set and d.up.choke_heuristics.seed.set are private.

d.up.rate
d.up.total
d.up.rate = ‹hash› ≫ value ‹rate [bytes/s]›
d.up.total = ‹hash› ≫ value ‹total [bytes]›

The total amount and current rate of upload traffic for this item.

d.update_priorities
d.update_priorities = ‹hash› ≫ 0

After a scripted change to priorities using f.priority.set, this command must be called. It updates the internal state of a download item based on the new priority settings.

d.uploads_max
d.uploads_max.set
d.uploads_min
d.uploads_min.set
d.uploads_max = ‹hash› ≫ value ‹max›
d.uploads_max.set = ‹hash›, value ‹max› ≫ 0
d.uploads_min = ‹hash› ≫ value ‹min›
d.uploads_min.set = ‹hash›, value ‹min› ≫ 0

Control the maximum and minimum upload slots that should be used. rTorrent will attempt to balance the number of active connections so that the number of unchoked connections is between the given minimum and maximum.

0 means unlimited, and when d.uploads_max is less than d.uploads_min, rTorrent will use d.uploads_min as the maximum instead.

d.views
d.views.has
d.views.push_back
d.views.push_back_unique
d.views.remove
TODO
d.wanted_chunks
d.wanted_chunks = ‹hash› ≫ value ‹chunks›

The number of chunks rTorrent wants to download. Contrast with d.completed_chunks, although d.wanted_chunks will not count chunks from files prioritized as “off” as wanted. See f.priority for commands relating to file prioritization.

d.tracker_alias
d.tracker_domain

rTorrent-PS only

d.tracker_domain returns a shortened version of the domain in the tracker’s URL, for a given download item. The chosen tracker is the first HTTP one with active peers (seeders or leechers), or else the first one.

d.tracker_alias (1.1+ only) is basically the same, but uses the mappings defined by trackers.alias.set_key to transform its return value. The main use-case for that is to be able to sort the rTorrent-PS trackers view by the same values as shown to the very right of the terminal.

But you can also use it in a d.multicall.filtered command together with string.equals, to easily select items of one or more specified tracker(s).

Examples

# Trackers view (all items, sorted by tracker domain and then name).
# This will ONLY work if you use rTorrent-PS!
view.add          = trackers
view.sort_new     = trackers, "compare=,d.tracker_alias=,d.name="
view.sort_current = trackers, "compare=,d.tracker_alias=,d.name="
$ rtxmlrpc d.multicall.filtered '' 'string.equals=(d.tracker_alias),Linux,Debian' \
           d.tracker_domain= d.name=
['linuxtracker.org', 'Container Linux 1745.7.0.iso']
['linuxtracker.org', 'robolinux64-mate3d-v9.3.iso']
['bttracker.debian.org', 'debian-9.4.0-amd64-netinst.iso']
d.tracker_scrape.complete
d.tracker_scrape.downloaded
d.tracker_scrape.incomplete

rTorrent-PS 1.1+ only

TODO

f.* commands

These commands can be used as arguments in a f.multicall. They can also be called directly, but you need to pass ‹infohash›:f‹index› as the first argument. Index counting starts at 0, the array size is d.size_files.

Example

$ rtxmlrpc --repr f.multicall "145B85116626651912298F9400805254FB1192AE" "" f.path=
[['ubuntu-16.04.3-server-amd64.iso']]

$ rtxmlrpc --repr f.size_bytes "145B85116626651912298F9400805254FB1192AE:f0"
865075200
f.multicall
f.multicall = ‹infohash›, ‹pattern›, [‹cmd1›=[‹args›][, ‹cmd2›=…]] ≫ list of lists of results ‹rows of results›

Iterates over the files in an item, calling the given f.* commands. The second argument, if non-empty, is a glob-like pattern (e.g. *.mkv) and filters the result for matching filenames. That pattern matching is very simplistic, be cautious and test that you get the results you expect.

See also d.multicall2 on basics regarding multi-calls.

f.completed_chunks
f.completed_chunks = ‹infohash› ≫ value ‹chunks›

The number of chunks in the file completed. Just as with f.size_chunks, this number is inclusive of any chunks that contain only part of the file.

f.frozen_path
f.frozen_path = ‹infohash› ≫ string ‹abspath›

The absolute path to the file.

f.is_created
f.is_open
TODO
f.is_create_queued
f.set_create_queued
f.unset_create_queued
f.is_resize_queued
f.set_resize_queued
f.unset_resize_queued
TODO
f.last_touched
f.last_touched = ‹infohash› ≫ value ‹microseconds›

The last time, in epoch microseconds, rTorrent prepared to use the file (for either reading or writing). This will not necessarily correspond to the file’s access or modification times.

f.match_depth_next
f.match_depth_prev
TODO
f.offset
f.offset = ‹infohash› ≫ value ‹bytes›

The offset (in bytes) of the file from the start of the torrent data. The first file starts at 0, the second file at f.size_bytes of the first file, the third at f.size_bytes of the first two files combined, and so on.

f.path
f.path = ‹infohash› ≫ string ‹path›

The path of the file relative to the base directory.

f.path_components
f.path_components = ‹infohash› ≫ array ‹components›

Returns an array of the individual parts of the path.

f.path_depth
f.path_depth = ‹infohash› ≫ value ‹depth›

Returns a value equal to how deep the file is relative to the base directory. This is equal to the number of elements in the array that f.path_components returns.

f.prioritize_first
f.prioritize_first.disable
f.prioritize_first.enable
f.prioritize_last
f.prioritize_last.disable
f.prioritize_last.enable
f.prioritize_first = ‹infohash› ≫ bool (0 or 1)
f.prioritize_first.disable = ‹infohash› ≫ 0
f.prioritize_first.enable = ‹infohash› ≫ 0
f.prioritize_last = ‹infohash› ≫ bool (0 or 1)
f.prioritize_last.disable = ‹infohash› ≫ 0
f.prioritize_last.enable = ‹infohash› ≫ 0

This determines how files are prioritized when f.priority is set to normal. While any high (i.e. 2) priority files take precedence, when a torrent is started, the rest of the files are sorted according to which are marked as prioritize_first vs prioritize_last. If both flags are set, prioritize_first is checked first. This sorting happens whenever d.update_priorities is called.

See also file.prioritize_toc.

f.priority
f.priority.set
f.priority = ‹infohash› ≫ value ‹priority›
f.priority.set = ‹infohash›, value ‹priority› ≫ 0

There are 3 possible priorities for files:

  • 0 off – Do not download this file. Note that the file can still show up if there is an overlapping chunk with a file that you do want to download.
  • 1 normal – Download this file normally.
  • 2 high – Prioritize requesting chunks for this file above normal files.

In the ncurses file view, you can rotate a selected file between these states with the space bar.

See also d.update_priorities.

f.range_first
f.range_second
TODO
f.size_bytes
f.size_chunks
f.size_bytes = ‹infohash› ≫ value ‹bytes›
f.size_chunks = ‹infohash› ≫ value ‹chunks›

Returns the number of bytes and chunks in the file respectively. If the file is only partially in some chunks, those are included in the count. This means the sum of all f.size_chunks can be larger than d.size_chunks.

p.* commands

These commands can be used as arguments in a p.multicall. They can also be called directly, but you need to pass ‹infohash›:p‹peerhash› as the first argument (referenced as target from here on out). The ‹peerhash› is the ID as returned by p.id, which is encoded as a hexadecimal string.

Example

$ hash="145B85116626651912298F9400805254FB1192AE" # some valid info hash
$ rtxmlrpc --repr p.multicall "$hash" "" p.id= p.port=
[['17C14214B60B92FFDEBFB550380ED3866BF49691', 62066]]
$ rtxmlrpc --repr p.port "$hash:p17C14214B60B92FFDEBFB550380ED3866BF49691"
62066
p.multicall
p.multicall = ‹infohash›, "", [‹cmd1›=[‹args›][, ‹cmd2›=…]] ≫ list of lists of results ‹rows of results›

Iterates over the peers in an item, calling the given p.* commands.

The second argument is ignored, pass an empty string. See also d.multicall2 on basics regarding multi-calls.

p.address
p.address = ‹target› ≫ string ‹address›

Returns the IP address of the peer.

p.banned
p.banned.set
p.banned = ‹target› ≫ bool (0 or 1)
p.banned.set = ‹target›, bool (0 or 1) ≫ 0

Returns (or sets) whether to ban the peer for too much bad data being sent, which means rTorrent will never connect to the peer again.

TODO What are the conditions for a peer being banned automatically?

Warning

Once a peer is set as banned, it cannot be unbanned. Only restarting rTorrent can clear the ban.

p.call_target
p.call_target = ‹infohash›, ‹peerhash›, ‹cmd›, [‹arg1›, [, ‹arg2›…]] ≫ bool (0 or 1)

TODO While functional, the code looks incomplete and it isn’t very useful.

p.client_version
p.client_version = ‹target› ≫ string ‹client version›

Returns a string client containing the client and version of the peer, if rTorrent knows enough to parse the peer ID. Otherwise, Unknown will be returned. The list of clients rTorrent understands is available in client_list.cc.

p.completed_percent
p.completed_percent = ‹target› ≫ value ‹percent›

Returns the percent of data the remote peer has completed.

p.disconnect
p.disconnect_delayed
p.disconnect = ‹target› ≫ 0
p.disconnect_delayed = ‹target› ≫ 0

Disconnects from the specified peer. The p.disconnect disconnects immediately, while p.disconnect_delayed puts the actual disconnect into a queue.

TODO What causes delayed disconnect actions to finally be acted upon?

p.down_rate
p.down_total
p.down_rate = ‹target› ≫ value ‹rate  [bytes/s]›
p.down_total = ‹target› ≫ value ‹total  [bytes]›

Returns the rate and total of the bytes you are downloading from the peer.

p.id
p.id = ‹target› ≫ string ‹peerhash›

Returns the peer ID hash, in the form of a 40-character hex string. This is the ID rTorrent uses to reference the peer in all XMLRPC commands, and is different from the ID peers send to identify themselves.

p.id_html
p.id_html = ‹target› ≫ string ‹client id›

Returns the client ID string, with non-printable characters percent encoded, like URLs. This command is completely unrelated to p.id. This is instead the raw string that peers send to identify themselves uniquely, and is what p.client_version attempts to parse. See BEP 20 for more information on the conventions clients use for the value.

p.is_encrypted
p.is_encrypted = ‹target› ≫ bool (0 or 1)

Returns true if the connection to the peer is encrypted (not just obfuscated). However, if this returns true, p.is_obfuscated will always be true as well. See protocol.encryption.set.

p.is_incoming
p.is_incoming = ‹target› ≫ bool (0 or 1)

Return true if the remote peer was the first one to initiate the connection.

p.is_obfuscated
p.is_obfuscated = ‹target› ≫ bool (0 or 1)

Returns true if the header messages sent to the peer are obfuscated. If the connection is fully encrypted, this is true automatically. Be aware that this means the data is still being sent unencrypted.

p.is_preferred
p.is_unwanted
p.is_preferred = ‹target› ≫ bool (0 or 1)
p.is_unwanted = ‹target› ≫ bool (0 or 1)

Returns whether or not the peer is marked as preferred or unwanted when IP filtering is in use.

p.options_str
p.options_str = ‹target› ≫ string ‹options›

Returns the reserved option bytes as a string. Currently only two options are recognized by rTorrent: extensions (BEP 10) and DHT (BEP 5). For clients that support both (most modern ones do), 0000000000100005 will be the returned string.

p.peer_rate
p.peer_total
p.peer_rate = ‹target› ≫ value ‹rate [bytes/s]›
p.peer_total = ‹target› ≫ value ‹total [bytes]›

Returns the rate and total of the bytes which the peer is downloading from everyone (local client included). Note that this is calculated from the number of chunks the peer has completed, and as such should not be taken as an exact indicator.

p.port
p.port = ‹target› ≫ value ‹port›

Returns the remote port as an integer.

p.is_snubbed
p.snubbed
p.snubbed.set
p.snubbed = ‹target› ≫ bool (0 or 1)
p.is_snubbed = ‹target› ≫ bool (0 or 1)
p.snubbed.set = ‹target›, bool (0 or 1) ≫ 0

Control if a peer is snubbed, meaning that rTorrent will stop uploading to the peer. p.is_snubbed is an alias for p.snubbed.

p.up_rate
p.up_total
p.up_rate = ‹target› ≫ value ‹rate [bytes/s]›
p.up_total = ‹target› ≫ value ‹total [bytes]›

Returns the rate and total of the bytes you are uploading to the peer.

t.* commands

These commands can be used as arguments in a t.multicall. They can also be called directly, but you need to pass ‹infohash›:t‹index› as the first argument. Index counting starts at 0, the array size is d.tracker_size.

t.multicall
t.multicall = ‹infohash›, "", [‹cmd1›=[‹args›][, ‹cmd2›=…]] ≫ list of lists of results ‹rows of results›

Iterates over the trackers in an item, calling the given t.* commands.

The second argument is ignored, pass an empty string. See also d.multicall2 on basics regarding multi-calls.

t.activity_time_last
t.activity_time_next
t.can_scrape
t.disable
t.enable
t.failed_counter
t.failed_time_last
t.failed_time_next
t.group
t.id
t.is_busy
t.is_enabled
t.is_enabled.set
t.is_extra_tracker
t.is_open
t.is_usable
t.latest_event
t.latest_new_peers
t.latest_sum_peers
t.min_interval
t.normal_interval
t.scrape_complete
t.scrape_counter
t.scrape_downloaded
t.scrape_incomplete
t.scrape_time_last
t.success_counter
t.success_time_last
t.success_time_next
t.type
t.url
TODO

load.* commands

The client may be configured to check a directory for new metafiles and load them. Items loaded in this manner will be tied to the metafile’s path (see d.tied_to_file).

This means when the metafile is deleted, the item may be stopped (see stop_untied), and when the item is removed the metafile is also. Note that you can untie an item by using the U key (which will also delete the tied file), and using Ctrl-K also implicitly unties an item.

load.normal
load.verbose
load.start
load.start_verbose

TODO Synopsis

Load a metafile or watch a pattern for new files to be loaded (in watch directory schedules).

normal loads them stopped, and verbose reports problems to the console (like when a new file’s infohash collides with an already loaded item).

TODO Post-load commands

load.raw
load.raw_start
load.raw_start_verbose
load.raw_verbose

load.raw_start_verbose since rTorrent 0.9.7

Load a metafile passed as base64 data. The method of encoding the data for XMLRPC will vary depending on which tool you’re using.

Take note that d.tied_to_file and d.loaded_file (until a client restart) will be empty for items added by these commands – which is the case for all items added via ruTorrent.

As with load.normal, raw loads them stopped, and raw_verbose reports problems to the console.

Example

$ mktor -q README.md local
$ rtxmlrpc --debug load.raw_verbose '' @README.md.torrent | egrep 'xmlrpclib|stats'
DEBUG    load.raw_verbose('', <xmlrpclib.Binary instance at 0x15e1200>) took 0.000 secs
DEBUG    XMLRPC stats: 3 req, out 795 bytes [564 bytes max], in 445 bytes [153 bytes max], …
$ rtxmlrpc d.multicall.filtered '' 'string.contains=$d.name=,README' \
           d.name= d.tied_to_file= d.loaded_file=
['README.md', '', '']

session.* commands

session.name
session.name.set
session.name ≫ string ‹name›
session.name.set = string ‹name› ≫ 0

This controls the session name. By default this is set to system.hostname + ‘:’ + system.pid. Like session.path, once the session is active this cannot be changed

session.on_completion
session.on_completion.set
session.on_completion ≫ bool (0 or 1)
session.on_completion.set = bool (0 or 1) ≫ 0

When true, d.save_resume is called right before event.download.finished occurs.

session
session.path
session.path.set
session.path ≫ string ‹path›
session.path.set = string ‹path› ≫ 0

session.path.set specifies the location of the directory where rTorrent saves its status between starts – a command you should always have in your configuration.

It enables session management, which means the metafiles and status information for all open downloads will be stored in this directory. When restarting rTorrent, all items previously loaded will be restored. Only one instance of rTorrent should be used with each session directory, though at the moment no locking is done.

An empty string will disable session handling. Note that you cannot change to another directory while a session directory is already active.

session is an alias for session.path.set, but should not be used as it may become deprecated.

session.save

Flushes the full session state for all torrents to the related files in the session folder. Note that this can cause heavy IO with many torrents. The default interval this command runs at can be adjusted, however if rTorrent restarts or goes down, there may be a loss of statistics and resume data for any new torrents added after the last snapshot.

See also d.save_full_session, which saves the state of a single item.

session.use_lock
session.use_lock.set
session.use_lock ≫ bool (0 or 1)
session.use_lock.set = bool (0 or 1) ≫ 0

By default, a lockfile is created in the session directory to prevent multiple instances of rTorrent from using the same session simultaneously.

Scripting

method.* commands

method.insert
method.insert = ‹name›, ‹type›[|‹sub-type›…][, ‹definition›] ≫ 0

The general way to define any kind of command. See Object Types for the possible values in the 2nd argument, Commands regarding some basic info on custom commands, and get comfortable with Escaping because you typically need that in more complex command definitions.

TODO more details

method.insert.simple
method.insert.simple = ‹name›, ‹definition› ≫ 0

This is a shortcut to define commands that are simple non-private functions.

method.insert.c_simple
method.insert.c_simple = ‹name›, ‹definition› ≫ 0

Defines a const simple function. TODO Meaning what?

method.insert.s_c_simple
method.insert.s_c_simple = ‹name›, ‹definition› ≫ 0

Defines a static const simple function. TODO Meaning what?

argument.0
argument.1
argument.2
argument.3
# Internal, not callable from XMLRPC!
$argument.‹N›= ≫ value of Nth argument

These can be used to refer to arguments passed into a custom method, either via $argument.‹N›= or (argument.‹N›).

method.insert.value
method.insert.value = ‹name›, ‹default› ≫ 0

Defines a value that you can query and set, just like with any built-in value.

The example shows how to do optional logging for some new command you define, and also how to split a complicated command into steps using the multi method type.

# Enable verbose mode by setting this to 1
method.insert.value = sample.verbose, 0

# Do something with optional logging
method.insert = sample.action, multi|rlookup|static
method.set_key = sample.action, 10, ((print, "action"))
method.set_key = sample.action, 20, ((print, "action2"))
method.set_key = sample.action, 99,\
    ((branch, sample.verbose=,\
        "print=\"Some log message\""\
    ))
method.const.enable = sample.action
method.const
method.const.enable
method.const = ‹name› ≫ bool (0 or 1)
method.const.enable = ‹name› ≫ 0

Set a method to immutable (or final). method.const queries whether a given command is. If you try to change a const method, you’ll get an Object is wrong type or const. error.

See method.insert.value for an example.

method.erase
Doesn’t work, don’t bother.
method.get
method.get = ‹name› ≫ various (see text)

Returns the definition of a method, i.e. its current integer or string value, the definition for simple methods, or a dict of command definitions for multi methods. Querying any built-in method (a/k/a non-dynamic commands) results in a Key not found. fault.

The type of the definition can be either string or list, depending on whether "…" or ((…)) was used during insertion.

An example shows best what you get here, if you query the commands defined in the method.insert.value example, you’ll get this:

$ rtxmlrpc --repr method.get '' sample.verbose
1

$ rtxmlrpc --repr method.get '' sample.verbose.set
ERROR    While calling method.get('', 'sample.verbose.set'): <Fault -503: 'Key not found.'>

$ rtxmlrpc --repr method.get '' sample.action
{'10': ['print', 'action'],
 '20': ['print', 'action2'],
 '99': ['branch', 'sample.verbose=', 'print="Some log message"']}

method.get is also great to see what system handlers are registered. They often begin with a ! or ~ to ensure they sort before / after any user-defined handlers.

$ rtxmlrpc --repr method.get '' event.download.closed
{'!view.indemand': 'view.filter_download=indemand',
 'log': 'print="CLOSED ",$d.name=," [",$convert.date=$system.time=,"]"'}

The !view.‹viewname› handler is added dynamically when you register it for an event using view.filter_on.

method.set
TODO
method.set_key
method.has_key
method.list_keys
method.set_key = ‹name›, ‹key›[, ‹definition›] ≫ 0
method.has_key = ‹name›, ‹key› ≫ bool (0 or 1)
method.list_keys = ‹name› ≫ list of strings

Set entries in a multi method, query a single key, or list them all. If you omit the definition in a method.set_key call, the key is erased – it is safe to do that with a non-existing key.

method.set_key is commonly used to add handler commands to event types like event.download.finished. It can also be used to split complicated command definitions, see method.insert.value for an example.

See the explanation of the multi type for more details.

method.rlookup
method.rlookup.clear
TODO
method.redirect
method.redirect = ‹alias›, ‹target› ≫ 0

Defines an alias for an existing command, the arguments are command names. Aliases cannot be changed, using the same alias name twice causes an error.

event.* commands

rTorrent events are merely multi commands that are called automatically when certain things happen, like completion of a download item.

You can trigger them manually by calling them on selected items (e.g. via rtxmlrpc). Make sure though that the registered handlers do not have adverse effects when called repeatedly, i.e. know what you’re doing.

The handlers for an event can be listed like so:

rtxmlrpc --repr method.get '' event.download.finished

Note that practically all the events have pre-registered system handlers, often starting with a digit, !, or ~, for ordering reasons.

event.download.closed
event.download.opened
Download item was closed / opened.
event.download.paused
event.download.resumed
Download item was paused / resumed.
event.download.hash_done
event.download.hash_failed
event.download.hash_final_failed
TODO
event.download.hash_queued
event.download.hash_removed
TODO
event.download.inserted
event.download.inserted_new
event.download.inserted_session
inserted is always called when an item is added to the main downloads list. After that, inserted_session is called when the source of that item is the session state (on startup), or else inserted_new is called for items newly added via a load command.
event.download.finished
Download item is complete.
event.download.erased
Download item was removed.
event.view.hide
event.view.show

since rTorrent-PS 1.1 / rTorrent 0.9.8

event.view.hide = ‹new-view-name› ≫ 0
event.view.show = ‹old-view-name› ≫ 0

These events get called shortly before and after the download list canvas changes to a new view. Each gets passed the view name that is not available via ui.current_view at the time of the trigger, i.e. either the new or the old view name.

Be aware that during startup these view names can be empty strings!

Event handler example

method.set_key = event.view.hide, ~log,\
    ((print, "× ", ((ui.current_view)), " → ", ((argument.0))))'
method.set_key = event.view.show, ~log,\
    ((print, "⊞ ", ((argument.0)), " → ", ((ui.current_view))))'

Scheduling Commands

The scheduling commands define tasks that call another command or list of commands repeatedly, just like a cron job, but with a resolution of seconds.

schedule2
schedule2 = ‹name›, ‹start›, ‹interval›, ((‹command›[, ‹args›…])) ≫ 0
schedule2 = ‹name›, ‹start›, ‹interval›, "‹command›=[‹args›…][ ; ‹command›=…]" ≫ 0

Call the given command(s) every interval seconds, with an initial delay of start seconds after client startup. An interval of zero calls the task once, while a start of zero calls it immediately.

The name serves both as a handle for schedule_remove2, and as an easy way to document what this task actually does. Existing tasks can be changed at any time, just use the same name.

start and interval may optionally use a time format like [dd:]hh:mm:ss. An interval of 07:00:00:00 would mean weekly execution.

Examples

# Watch directories
schedule2 = watch_start, 11, 10, ((load.start, (cat, (cfg.watch), "start/*.torrent")))
schedule2 = watch_load,  12, 10, ((load.normal, (cat, (cfg.watch), "load/*.torrent")))

# Add day break to console log
# → ( 0:00:00) New day: 20/03/2017
schedule2 = log_new_day, 00:00:00, 24:00:00,\
    "print=\"New day: \", (convert.date, (system.time))"

# … or the equivalent using "new" syntax:
schedule2 = log_new_day, 00:00:05, 24:00:00,\
    ((print, "New day: ", ((convert.date, ((system.time_seconds)) )) ))
schedule_remove2
schedule_remove2 = ‹name› ≫ 0

Delete an existing task referenced by name from the scheduler. Deleting a non-existing task is not an error.

start_tied
stop_untied
close_untied
remove_untied
TODO
close_low_diskspace
TODO

Importing Script Files

import
try_import
import = ‹rc-file-path› ≫ 0
try_import = ‹rc-file-path› ≫ 0

Both of these commands open the given file and execute the contained commands, one per logical line.

Physical ines can be continued by escaping the line end with \. The maximum length is 4096 bytes.

Lines beginning with # are comments.

try_import ignores a missing script file, while import throws an error in that case.

If you’re nesting imports, relative filenames are resolved using system.cwd, and not based on the location of the importing file.

Example

import = (cat, (cfg.basedir), "_rtlocal.rc")
import.return

rTorrent-PS 1.1+ only

import.return= ≫ throw('import.return')

Leaves the currently imported file and returns to the level above.

Since this works by throwing an exception, you will see that exception when called outside of an imported file.

Example: Quick toggle of experimental configuration

Add a commented import.return into a configuration file, above some code you work on, at the very end of the file. Remove the # to test that code, put it back to ignore your experiment.

#import.return=
«here be dragons»

Example: Protecting imports that use new features

First, protect the import like this (to make it compatible with older builds):

branch=(system.has, "import.return="), ((import, using-math-stuff.rc))

Then in the using-math-stuff.rc file, you can return when certain capabilities are missing.

branch=(not, (system.has, "math.add=")), ((import.return))

You can do this incrementally ordered from older to younger capabilities, using exactly those features a build has to offer.

Conditions (if/branch/do)

branch
if
branch = ‹condition-cmd›, ‹then-cmds›[, ‹else-cmds›] ≫ 0
if = ‹condition›, ‹then-cmds›[, ‹else-cmds›] ≫ 0

Both of these commands take a predicate, and based on its value execute either the command or commands given as the 2nd argument, or else the ones in the 3rd argument. See Conditional Operators below for details on these predicates, and do for calling several commands in ‘new’ syntax as the then or else part.

The fundamental difference between branch and if is the first takes commands to evaluate for the predicate, the latter expects values.

See the following examples for details, these are easier to understand than long-winded explanations. Take note of the different forms of Escaping needed when the then/else commands themselves take arguments.

And always consider adding additional helper methods when you have complex multi-command then or else arguments, because escaping escalates fast. You also must use double parentheses if you use those, because otherwise both then and else are already evaluated when the branch/if itself is, which defeats the whole purpose of the conditional.

# Toggle a value between 0 and 1
method.insert.value = foobar, 0
method.insert = foobar.toggle, simple, \
    "branch=(foobar), ((foobar.set, 0)), ((foobar.set, 1))"

Using branch=foobar=, is equivalent, just using the older command syntax for the condition.

$ rtxmlrpc branch '' greater=value=2,value=2 cat=YES cat=NO
NO
$ rtxmlrpc branch '' greater=value=4,value=2 cat=YES cat=NO
YES

TODO: More examples, using or/and/not and other more complex constructs.

do

rTorrent-PS 1.1+ only

do = ‹cmd1›, [, ‹cmd2›…] ≫ 0

The do command behaves just like the vanilla catch command, the only difference being that it doesn’t catch exceptions.

It can be used to group a sequence of commands in ‘new’ syntax, for execution as the then or else command of if or branch.

Otherwise you’d need to use "cmd1=… ; cmd2=…; …" for such a sequence, with all the usual escaping problems when calling commands with several arguments.

Examples

branch = (system.has, "do="), \
    ((do, \
        ((print, "Just")), \
        ((print, "DO")), \
        ((print, "it!")) \
    )), \
    ((print, "Awwwwww!"))
$ rtxmlrpc do '' "false=" "foobar="
ERROR … Command "foobar" does not exist
RC=65
$ rtxmlrpc catch '' "false=" "foobar="
0
RC=0

Conditional Operators

false
Ignores any amount of arguments, and always returns 0.
and
or
not
TODO
less
equal
greater
less = ‹cmd1›[, ‹cmd2›] ≫ bool (0 or 1)
equal = ‹cmd1›[, ‹cmd2›] ≫ bool (0 or 1)
greater = ‹cmd1›[, ‹cmd2›] ≫ bool (0 or 1)

The comparison operators can work with strings or values (integers), returned from the given command(s). The most common form is with one provided command, that is then called for a target (e.g. with view.filter) or a target pair (e.g. view.sort_new or view.sort_current).

Consider this example, where items are sorted by comparing the names of target pairs, and the less command is called by a typical sorting algorithm:

view.sort_new     = name,((less,((d.name))))
view.sort_current = name,((less,((d.name))))

An example for a filter with two commands returning integer values is the important view, showing only items with a high priority:

view.add = important
ui.current_view.set = important
method.insert = prio_high, value|const|private, 3
view.filter = important, "equal=d.priority=,prio_high="

When two commands are given, their return types must match, and each command is called with the target (or the left / right sides of a target pair, respectively).

As you can see above, to compare against a constant you have to define it as a command. If you run rTorrent-PS, you can use value instead.

For strings, you can use cat as the command, and pass it the text literal.

view.filter = important, ((not, ((equal, ((d.throttle_name)), ((cat)) )) ))
view.filter = important, ((equal, ((d.throttle_name)), ((cat, NULL)) ))

Looks strange, like so many things in rTorrent scripting. The first filter shows all items that have any throttle set, i.e. have a non-empty throttle name. ((cat)) is the command that returns that empty string we want to compare against. The second filter selects items that have the special unlimited throttle NULL set.

elapsed.greater
elapsed.less
elapsed.greater = ‹start-time›, ‹interval› ≫ bool (0 or 1)
elapsed.less = ‹start-time›, ‹interval› ≫ bool (0 or 1)

Compare time elapsed since a given timestamp against an interval in seconds. The timestamps are UNIX ones, like created by system.time_seconds. The result is false if the timestramp is empty / zero.

Example

method.insert.value = cfg.seed_seconds, 259200
schedule2 = limit_seed_time, 66, 300, "d.multicall.filtered = started,\
    \"elapsed.greater = (d.timestamp.finished), (cfg.seed_seconds)\",\
    d.try_stop="

What this does is stop any item finished longer than 3 days ago (selected via d.multicall.filtered), unless it is set to ignore commands (d.try_stop checks the ignore flag before stopping).

compare

rTorrent-PS 0.x+ only

compare = ‹order›, ‹sort_key›=[, ...] ≫ bool (0 or 1)

Compares two items like less or greater, but allows to compare by several different sort criteria, and ascending or descending order per given field.

The first parameter is a string of order indicators, either one of aA+ for ascending or dD- for descending. The default, i.e. when there’s more fields than indicators, is ascending.

Field types other than value or string are treated as equal (or in other words, they’re ignored). If all fields are equal, then items are ordered in a random, but stable fashion.

Example: Sort a view by message and name

view.add = messages
view.filter = messages, ((d.message))
view.sort_new = messages, "compare=,d.message=,d.name="

String Functions

cat
cat=«text»[,…] ≫ string
cat={"array", "of", "text"}[,…] ≫ string

cat takes a list of object arguments, or an array of objects, and smushes them all together with no delimiter (see string.join for the variant with a delimiter).

Note that cat can be used to feed strings into the parser that are otherwise not representable, like passing an empty string where a command is expected via (cat,), or text starting with a dollar sign using (cat,{$}).

string.len

rTorrent-PS 1.1+ only

string.len = «text» ≫ value (length)

Returns the length of an UTF-8 encoded string in terms of Unicode characters.

Examples

# string.len
$ rtxmlrpc --repr string.len '' -- ''
0
$ rtxmlrpc --repr string.len '' -- 'foo123bar'
9
$ rtxmlrpc --repr string.len '' -- '♯'
1
$ rtxmlrpc --repr string.len '' --
ERROR … <Fault -503: 'string.len needs a string argument.0!'>
string.equals
string.startswith
string.endswith

rTorrent-PS 1.1+ only

string.equals = «text», «other»[, …] ≫ bool (0 or 1)
string.startswith = «text», «prefix»[, …] ≫ bool (0 or 1)
string.endswith = «text», «tail»[, …] ≫ bool (0 or 1)

Checks whether the first argument is equal to, starts with, or ends with another string.

If you pass more than two arguments, any match with the 2nd to last argument will return true (1).

Examples

# Show ETA column only on 'active' and 'leeching' views
method.set_key = event.view.show, ~eta_toggle, \
    "branch = \"string.equals=$ui.current_view=, active, leeching\", \
        ui.column.show=533, ui.column.hide=533"
$ rtxmlrpc --repr string.equals '' first 2nd | as_bool
‹false›
$ rtxmlrpc --repr string.equals '' foobar foobar | as_bool
‹true›
$ rtxmlrpc --repr string.equals '' foo bar foo | as_bool
‹true›

$ rtxmlrpc --repr string.startswith '' foobar '' | as_bool
‹true›
$ rtxmlrpc --repr string.startswith '' foobar foo | as_bool
‹true›
$ rtxmlrpc --repr string.startswith '' foobar baz foo 4th | as_bool
‹true›
$ rtxmlrpc --repr string.startswith '' foobar foe | as_bool
‹false›

$ rtxmlrpc --repr string.endswith '' foobar '' | as_bool
‹true›
$ rtxmlrpc --repr string.endswith '' foobar bar | as_bool
‹true›
$ rtxmlrpc --repr string.endswith '' foobar baz bar | as_bool
‹true›
$ rtxmlrpc --repr string.endswith '' foobar baz | as_bool
‹false›

$ rtxmlrpc --repr string.equals ''
ERROR … string.equals takes at least two arguments
$ rtxmlrpc --repr string.equals '' first
ERROR … string.equals takes at least two arguments
$ rtxmlrpc --repr string.equals '' first +2
ERROR … Wrong object type
$ rtxmlrpc --repr string.equals '' +1 2nd
ERROR … string.equals needs a string argument.0
string.contains
string.contains_i

rTorrent-PS 1.1+ only

string.contains[_i] = «haystack», «needle»[, …] ≫ bool (0 or 1)

Checks if a given string contains any of the strings following it. The variant with _i is case-ignoring, but only works for pure ASCII needles.

Example

$ rtxmlrpc d.multicall.filtered '' 'string.contains_i=(d.name),Mate' d.name=
['sparkylinux-4.0-x86_64-mate.iso']
string.substr

rTorrent-PS 1.1+ only

string.substr = «text»[, «pos»[, «count»[, «default»]]] ≫ string

Returns part of an UTF-8 encoded string. The positional arguments can be passed as either strings (base 10) or values, and they count Unicode characters. A negative «pos» is relative to the end of the string.

When «pos» is outside the string bounds (including ‘at the end’), then «default» is returned when provided, instead of an empty string.

Examples

# string.substr
$ rtxmlrpc --repr string.substr '' -- 'foo123bar'
'foo123bar'
$ rtxmlrpc --repr string.substr '' -- 'foo123bar' 6
'bar'
$ rtxmlrpc --repr string.substr '' -- 'foo123bar' 3 +3
'123'
$ rtxmlrpc --repr string.substr '' -- 'foo123bar' -6 3
'123'
$ rtxmlrpc --repr string.substr '' -- '➀ ♯'
u'\u2780 \u266f'
$ rtxmlrpc --repr string.substr '' -- '' 42
''
$ rtxmlrpc --repr string.substr '' -- 'foo' 3 +3 'bar'
'bar'
$ rtxmlrpc --repr string.substr '' -- '' 0 1 'foobar'
'foobar'
$ rtxmlrpc --repr string.substr '' -- '' 42 1 'Life, universe, everything'
'Life, universe, everything'
$ rtxmlrpc --repr string.substr '' -- 'foobar' 5
'r'
$ rtxmlrpc --repr string.substr '' -- 'foobar' 6
''
$ rtxmlrpc --repr string.substr '' -- '➀ ➁ ➂ ➃ ➄ ➅ ➆ ➇ ➈' 2 1
u'\u2781'
$ rtxmlrpc --repr string.substr '' -- '➀ ➁ ➂ ➃ ➄ ➅ ➆ ➇ ➈' 2 +2
u'\u2781 '
$ rtxmlrpc --repr string.substr '' -- '➀ ➁ ➂ ➃ ➄ ➅ ➆ ➇ ➈' -3 2
u'\u2787 '
$ rtxmlrpc --repr string.substr '' -- 'for123bar' 3 bad
ERROR … string.substr(count): junk at end of value: bad
RC=65
$ rtxmlrpc --repr string.substr '' --
ERROR … string.substr needs a string argument
RC=65
string.join

rTorrent-PS 1.1+ only

string.join = «delim»[, «object»[, …]] ≫ string

Works just like cat (including conversion of the passed objects to strings), but concatenates the arguments using a provided delimiter.

Examples

# string.join
$ rtxmlrpc --repr string.join '' ':'
''
$ rtxmlrpc --repr string.join '' '' 1 2 3
'123'
$ rtxmlrpc --repr string.join '' ':' a +2 [3,4
'a:2:34'
$ rtxmlrpc --repr string.join ''
ERROR … string.join needs a string argument.0
$ rtxmlrpc --repr string.join '' +42
ERROR … string.join needs a string argument.0
string.split

rTorrent-PS 1.1+ only

string.split = «text», «delim» ≫ array of string (parts)

Splits an UTF-8 encoded string into parts delimited by the 2nd argument. If that delimiter is the empty string, you’ll get a Unicode character array of the first argument.

Examples

# string.split
$ rtxmlrpc --repr string.split '' '1·₂·³' '·'
['1', u'\u2082', u'\xb3']
$ rtxmlrpc --repr string.split '' 1..2. .
['1', '', '2', '']
$ rtxmlrpc --repr string.split '' .1 .
['', '1']
$ rtxmlrpc --repr string.split '' abc .
['abc']
$ rtxmlrpc --repr string.split '' '1²₃' ''
['1', u'\xb2', u'\u2083']
$ rtxmlrpc --repr string.split '' '' '.'
['']
$ rtxmlrpc --repr string.split '' '' ''
[]
$ rtxmlrpc --repr string.split '' ''
ERROR … string.split needs a string argument.1
$ rtxmlrpc --repr string.split '' '' +1
ERROR … string.split needs a string argument.1
string.map
string.replace

rTorrent-PS 1.1+ only

string.map = «text», {«old»,«new»}[, …] ≫ string
string.replace = «text», {«old»,«new»}[, …] ≫ string

string.map scans a list of replacement pairs for an old text that matches all of the given string, and replaces it by new.

string.replace substitutes any occurence of the old text by the new one.

Examples

$ rtxmlrpc string.map '' 'foo' [foo,bar [bar,baz
baz

$ rtxmlrpc string.replace '' "it's like 1" [1,2ic [2,ma3 [3,g
it's like magic

$ rtxmlrpc -i 'print = (string.map, (cat, (value,1)), {0,off}, {1,low}, {2,""}, {3,high})'
# prints 'low' as a console message, this is how you map integers

Array Functions

array.at

rTorrent-PS 1.1+ only

array.at = «array», «pos» ≫ object (element)

TODO

Examples

# array.at
$ rtxmlrpc --repr array.at '' -- '[0,1,2' +0
0
$ rtxmlrpc --repr array.at '' -- '[0,1,2' +1
1
$ rtxmlrpc --repr array.at '' -- '[0,1,2' +2
2

$ rtxmlrpc --repr array.at '' -- '[0,1,2' +4
ERROR … array.at: index out of bounds
$ rtxmlrpc --repr array.at '' -- '[,' -1
ERROR … array.at: index out of bounds

# 1 element arrays do not work somehow (but also aren't that useful)
$ rtxmlrpc --repr array.at '' -- '[a' +0
ERROR … Wrong object type
$ rtxmlrpc --repr array.at '' -- '[]' +0
ERROR … Wrong object type

Math Functions

Most of these commands are available in rTorrent-PS 1.1+, in rTorrent-PS-CH, and rTorrent 0.9.7+. Deviations are explicitly noted.

Values can either be of type value or string – strings are automatically converted, with an error thrown when the string contains something other than digits.

The handled values are restricted to integer arithmetic (as in bash), because rTorrent has no floating point type. Division, average, and median always round down.

All commands support multiple arguments, including lists. List arguments are handled recursively, as-if there were a nested math.* call of the same type, with the list as its arguments.

When using multiple list arguments, or mixing them with plain numbers, this can lead to unexpected results with non-commutative operators, see the math.sub examples below.

math.add
math.sub
math.mul
math.div
math.mod

Basic arithmetic operators (+, -, *, /, %).

These share the same code, so the errors shown in the following examples usually apply to all commands, and are not repeated for each operator.

Examples

# math.add
$ rtxmlrpc --repr math.add '' -- 1 1
2
$ rtxmlrpc --repr math.add '' -- 1 -1
0
$ rtxmlrpc --repr math.add '' -- +1 +1
2
$ rtxmlrpc --repr math.add '' -- +1 -1
0
$ rtxmlrpc --repr math.add '' -- 1 +1
2
$ rtxmlrpc --repr math.add '' -- 1 -1
0
$ rtxmlrpc --repr math.add '' -- [1,2 3
6
$ rtxmlrpc --repr math.add '' -- text
ERROR … Could not convert
# math.sub
$ rtxmlrpc --repr math.sub '' -- 1 1
0
$ rtxmlrpc --repr math.sub '' -- 1 -1
2
$ rtxmlrpc --repr math.sub '' -- [1 [1
0
$ rtxmlrpc --repr math.sub '' -- [1,2
-1
$ rtxmlrpc --repr math.sub '' -- [9,3,3
3
# this breaks the law of the least surprise (it is "3 - (1 - 2)")
$ rtxmlrpc --repr math.sub '' -- 3 [1,2
4
# math.mul
$ rtxmlrpc --repr math.mul '' -- 0 1
0
$ rtxmlrpc --repr math.mul '' -- 2 -1
-2
# math.div
$ rtxmlrpc --repr math.div '' -- 4 +2
2
$ rtxmlrpc --repr math.div '' -- 8 3
2
$ rtxmlrpc --repr math.div '' -- 0 6
0

$ rtxmlrpc --repr math.div '' -- 6 0
ERROR … math.div: Division by zero
$ rtxmlrpc --repr math.div '' --
ERROR … math.div: No arguments provided
# math.mod
$ rtxmlrpc --repr math.mod '' -- 6 7
6
$ rtxmlrpc --repr math.mod '' -- 7 7
0
$ rtxmlrpc --repr math.mod '' -- 8 7
1

$ rtxmlrpc --repr math.mod '' -- 6 0
ERROR … math.mod: Division by zero
math.min
math.max
math.cnt
math.avg
math.med

Functions to calculate the minimum, maximum, element count, average, or median over the input values.

Examples

# math.min
$ rtxmlrpc --repr math.min '' -- 2 3 1
1
$ rtxmlrpc --repr math.min '' -- [2,3,1
1
$ rtxmlrpc --repr math.min '' -- 0 [2,3,1
0
$ rtxmlrpc --repr math.min '' -- [2,-3,1
-3
# math.max
$ rtxmlrpc --repr math.max '' -- 2 3 1
3
$ rtxmlrpc --repr math.max '' -- 2 -3 1
2
# math.cnt
$ rtxmlrpc --repr math.cnt '' --
0
$ rtxmlrpc --repr math.cnt '' -- 3 2 1
3
$ rtxmlrpc --repr math.cnt '' -- 3 3 1
3
$ rtxmlrpc --repr math.cnt '' -- 4 [3,2,1
4
# math.avg
$ rtxmlrpc --repr math.avg '' -- 2 3 1 4
2
$ rtxmlrpc --repr math.avg '' -- 2 3 1 5
2
$ rtxmlrpc --repr math.avg '' -- 2 3 1 6
3
# math.med
$ rtxmlrpc --repr math.med '' -- 1 3 3 3 5 42
3

Value Conversion & Formatting

The to_* forms are deprecated.

convert.kb
convert.mb
convert.xb
to_kb
to_mb
to_xb
TODO
convert.date
convert.elapsed_time
convert.gm_date
convert.gm_time
convert.time
to_date
to_elapsed_time
to_gm_date
to_gm_time
to_time
TODO
convert.throttle
to_throttle
TODO
convert.time_delta

rTorrent-PS 1.1+ only

convert.time_delta = ‹timestamp›[, ‹timebase›] ≫ string

Converts the difference of two timestamps into an approximate but short and human readable representation (the result is always 5 chars wide).

If timestamp is zero, the result is ⋅␣⋅⋅␣. If timebase is missing or zero, the current time is used instead.

Examples

# convert.time_delta
$ rtxmlrpc --repr convert.time_delta '' +"$(echo $(( $(date +'%s') + 86400 + 40000)) )"
'1d1…h'
$ rtxmlrpc convert.time_delta '' +1527903580 +1527903500
1’20”
$ rtxmlrpc convert.time_delta '' +1527903500 +1527903580
1’20”
$ rtxmlrpc --repr convert.time_delta '' +86400 +86400
u'\u22c5 \u22c5\u22c5 '
$ rtxmlrpc --repr convert.time_delta '' +0
u'\u22c6 \u22c6\u22c6 '

$ rtxmlrpc convert.time_delta ''
ERROR … convert.time_delta takes … arguments
$ rtxmlrpc convert.time_delta '' abc
ERROR … convert.time_delta: … must be a value
$ rtxmlrpc convert.time_delta '' +0 abc
ERROR … convert.time_delta: … must be a value
$ rtxmlrpc convert.time_delta '' 123
ERROR … convert.time_delta: … must be a value
$ rtxmlrpc convert.time_delta '' +0 123
ERROR … convert.time_delta: … must be a value
convert.human_size

rTorrent-PS 1.1+ only

convert.human_size = ‹bytes›[, ‹format›] ≫ string

Converts a size in bytes to a compact, human readable string. See also convert.xb for a similar command.

Format is a number (default 2), with these values:

  • 0: use 6 chars (one decimal place)
  • 1: just print the rounded value (4 chars)
  • 2: combine the two formats into 4 chars by rounding for values >= 9.95
  • +8: adding 8 converts zero values to whitespace of the correct length

Examples:

$ rtxmlrpc --repr convert.human_size '' +970 +0
'  0.9K'
$ rtxmlrpc --repr convert.human_size '' +970 +1
'  1K'
$ rtxmlrpc --repr convert.human_size '' +970 +10
'0.9K'
$ rtxmlrpc --repr convert.human_size '' +0 +2
'0.0K'
$ rtxmlrpc --repr convert.human_size '' +0 +10
'    '
convert.magnitude

rTorrent-PS 1.1+ only

convert.magnitude = ‹number› ≫ string

Converts any positive number below 10 million into a very compact string representation with only 2 characters. Above 99, only the first significant digit is retained, plus an order of magnitude indicator using roman numerals (c = 10², m = 10³, X = 10⁴, C = 10⁵, M = 10⁶). Zero and out of range values are handled special (see examples below).

Examples:

$ rtxmlrpc convert.magnitude '' +0
 ·
$ rtxmlrpc convert.magnitude '' +1
 1
$ rtxmlrpc convert.magnitude '' +99
99
$ rtxmlrpc convert.magnitude '' +100
1c
$ rtxmlrpc convert.magnitude '' +999
9c
$ rtxmlrpc convert.magnitude '' +1000
1m
$ rtxmlrpc convert.magnitude '' +9999999
9M
$ rtxmlrpc convert.magnitude '' +10000000
♯♯
$ rtxmlrpc -- convert.magnitude '' -1
♯♯
value

since rTorrent-PS 1.1 / rTorrent 0.9.8

value = ‹number›[, ‹base›] ≫ value

Converts a given number with the given base (or 10 as the default) to an integer value.

Examples:

$ rtxmlrpc -qi 'view.filter = rtcontrol, "equal = d.priority=, value=3"'
# the 'rtcontrol' view will now show all items with priority 'high'
$ rtxmlrpc --repr value '' 1b 16
27
$ rtxmlrpc --repr value '' 1b
ERROR    While calling value('', '1b'): <Fault -503: 'Junk at end of number: 1b'>

Logging, Files, and OS

execute.* commands

Call operating system commands, possibly catching their output for use within rTorrent.

Note

The .bg variants detach the child process from the rTorrent parent, i.e. it runs in the background. This must be used if you want to call back into rTorrent via XMLRPC, since otherwise there will be a deadlock.

throw means to raise an error when the called command fails, while the nothrow variants will return the exit code.

execute.throw
execute.throw.bg
execute2
execute.throw[.bg] = {command, arg1, arg2, ...} ≫ 0

This will execute a system command with the provided arguments. These commands either raise an error or return 0. execute2 is the same as execute.throw, and should be avoided.

Since internally spawn is used to call the OS command, the shell is not involved and things like shell redirection will not work here. There is also no reason to use shell quoting in arguments, just separate them by commas. If you need shell features, call bash -c "‹command›" like shown in this example:

# Write a PID file into the session directory
execute.throw = sh, -c, (cat, "echo >", (session.path), "rtorrent.pid", " ", (system.pid))

Note that the result of the (cat, …) command ends up as a single argument passed on to bash.

execute.nothrow
execute.nothrow.bg
execute.nothrow[.bg] = {command, arg1, arg2, ...} ≫ value ‹exit status›

Like execute.throw, but return the command’s exit code (warning: due to a bug the return code is shifted by 8 bits, so 1 becomes 0x100).

The .bg variant will just indicate whether the child could be successfully spawned and detached.

execute.capture
execute.capture_nothrow
execute.capture[_nothrow] = {command, arg1, arg2, ...} ≫ string ‹stdout›

Like execute.[no]throw, but returns the command’s standard output. The nothrow variant returns any output that was written before an error, in case one occurs. The exit code is never returned.

Note that any line-endings are included, so if you need a plain string value, wrap the command you want to call into an echo -n command:

method.insert = log_stamp, private|simple,\
    "execute.capture_nothrow = bash, -c, \"echo -n $(date +%Y-%m-%d-%H%M%S)\""
execute.raw
execute.raw.bg
execute.raw_nothrow
execute.raw_nothrow.bg
The execute.raw variants function identically to other execute.* commands, except that a tilde in the path to the executable is not expanded.

system.* commands

Commands related to the operating system and the XMLRPC API.

system.listMethods
system.methodExist
system.methodHelp
system.methodSignature
system.getCapabilities
system.listMethods ≫ array ‹methods›
system.methodExist = string ‹method› ≫ bool (0 or 1)
system.methodHelp = string ‹method› ≫ string ‹help›
system.methodSignature = string ‹method› ≫ string ‹signature›
system.getCapabilities ≫ array ‹capabilities›

XML-RPC introspection methods. For more information, see XML-RPC Introspection. Note that no help or signature is currently defined for rTorrent-specific commands.

system.capabilities
system.capabilities ≫ array ‹capabilities›

This returns protocol and version information about the XML-RPC interface implementation. See xmlrpc-c system.capabilities for more.

system.multicall
Similar to d.multicall2, this allows multiple commands to be sent in one request. Unlike d.multicall2, this is a generic multicall not specific to rTorrent. See the xmlrpc-c system.multicall docs for more.
system.daemon
system.daemon.set

since rTorrent 0.9.7

When set to true, rTorrent starts in the background without any curses UI. It can then only be controlled via XMLRPC commands and POSIX signals.

See Daemon Mode in the rTorrent wiki for more.

system.shutdown.normal
system.shutdown.quick

since rTorrent 0.9.7

These do shut down rTorrent – either quickly, or with waiting for BitTorrent stop events to be sent to trackers of active items.

In older versions of rTorrent, the only way to shut down the client without user interaction is to send a signal, read on for that…

POSIX Signal Handling

SIGINT and SIGHUP act like system.shutdown.normal, while SIGTERM is equivalent to system.shutdown.quick. SIGHUP support exists in rTorrent-PS and since rTorrent 0.9.7.

SIGWINCH causes a forced canvas redraw.

SIGPIPE is generally ignored, and SIGUSR1 ‘does nothing’.

SIGSEGV, SIGILL, and SIGFPE cause panic, meaning things are cleaned up if possible, before exiting the client. Also a stack dump is created, if that was enabled during compilation.

SIGBUS behaves almost the same (exits the client), but also prints some additional information regarding the signal reason, like Invalid address alignment or Non-existent physical address.

system.shutdown

This shuts down the XMLRPC server, but does not shut down rTorrent. It’s a built-in of the xmlrpc-c library.

See also system.shutdown.normal and system.shutdown.quick.

system.api_version
system.client_version
system.library_version
system.api_version ≫ string ‹version›
system.client_version ≫ string ‹version›
system.library_version ≫ string ‹version›

The versions of the XMLRPC API, the rTorrent client, and the libtorrent library respectively. The client and library versions are currently tightly coupled, while system.api_version is incremented whenever changes are made to the XMLRPC API.

system.colors.enabled
system.colors.max
system.colors.rgb
# rTorrent-PS only
system.colors.enabled ≫ bool (0 or 1)
system.colors.max ≫ int ‹colors›
system.colors.rgb ≫ int

Returns some ncurses system state related to colors (in rTorrent-PS only).

system.cwd
system.cwd.set
system.cwd ≫ string ‹path›
system.cwd.set = string ‹path› ≫ 0

Query or change the current working directory of the running process. This will affect any relative paths used after the change, e.g. in schedules.

system.env

since rTorrent-PS 0.x / rTorrent 0.9.7

system.env = ‹varname› ≫ string ‹env-value›

Query the value of an environment variable, returns an empty string if $varname is not defined.

Example

session.path.set = (cat, (system.env, RTORRENT_HOME), "/.session")
system.file.allocate
system.file.allocate.set
system.file.allocate ≫ bool (0 or 1)
system.file.allocate.set = bool (0 or 1) ≫ 0

Controls whether file pre-allocation is enabled. If it is, and file allocation is supported by the file system, the full amount of space required for a file is allotted immediately when an item is started. Otherwise space is used only when data arrives and must be stored.

system.file.max_size
system.file.max_size.set
TODO
system.file.split_size
system.file.split_size.set
system.file.split_suffix
system.file.split_suffix.set
TODO
system.file_status_cache.prune
system.file_status_cache.size
system.file_status_cache.size ≫ value ‹size›
system.file_status_cache.prune ≫ 0

Used when loading metafiles from a directory/glob, this helps prevent rTorrent from trying to load the same file multiple times, especially when using watch directories.

system.files.closed_counter
system.files.failed_counter
system.files.opened_counter
system.files.closed_counter ≫ value ‹closed›
system.files.failed_counter ≫ value ‹failed›
system.files.opened_counter ≫ value ‹opened›

Return the number of files which were closed, failed to open, and were successfully opened respectively.

system.has
system.has.list

rTorrent-PS 1.1+ only

system.has = ‹capability› ≫ bool (0 or 1)
system.has.list = ≫ list of string (capabilities)

This can be used to write configuration files that work on older builds (and on vanilla rTorrent), even when new features and commands are introduced.

The system.has.list command returns a list of non-method capabilities the running client has on board.

$ rtxmlrpc --repr system.has.list
['canvas_v2', 'colors', 'rtorrent-ps', 'system.has']

If a method name (ending in =) is passed, the call returns true when that method is already defined. The XMLRPC command system.methodExist is similar, but cannot be used from within rTorrent and its configuration.

$ rtxmlrpc system.has '' system.has=
1
$ rtxmlrpc system.has '' cute.kittens=
0

To make sure the system.has command can be actually used, add this somewhere early in your configuration:

# `system.has` polyfill (the "false=" silences the `catch` command, in rTorrent-PS)
catch = {"false=", "method.redirect=system.has,false"}

The following branch somehow self-absorbedly shows how this can be used:

branch=(system.has, system.has), ((print, "Your build can haz system.has!"))

In a vanilla rTorrent, there is silence, and zero capabilities.

A very practical use-case is auto-detection of rTorrent-PS 1.1+:

# `system.has` polyfill (the "false=" silences the `catch` command, in rTorrent-PS)
catch = {"false=", "method.redirect=system.has,false"}

# Set "pyro.extended" to 1 to activate rTorrent-PS features!
method.insert = pyro.extended, const|value, (system.has, rtorrent-ps)

It’s also especially useful in combination with a branched import, so whole snippets using new features are safe and don’t blow up in older builds. Or conditionally backfill something missing in older builds, like in this example:

# Define default columns for older rTorrent-PS builds
branch=(not, (system.has, canvas_v2)), ((import, rtorrent.d/05-rt-ps-columns.rc.include))
system.has.private_methods
system.has.public_methods

rTorrent-PS 1.1+ only

system.has.private_methods = ≫ list of string (method names)
system.has.public_methods = ≫ list of string (method names)

The system.has.private_methods and system.has.public_methods commands return a list of private / public methods, either built-in or defined via configuration. Private means a method is not callable via XMLRPC.

system.has.public_methods returns almost the same result as system.listMethods – what’s missing is the built-in methods of xmlrpc-c (see the example below).

Both these commands are only useful for things like comparing the lists generated by different client versions, or checking the completeness of this reference.

$ rtxmlrpc system.has.private_methods | wc -l
112
$ rtxmlrpc system.has.public_methods | wc -l
818
$ ( rtxmlrpc system.has.public_methods ; rtxmlrpc system.has.private_methods ) \
  | sort | uniq -c | awk '{print $1}' | sort | uniq -c
    930 1
$ ( rtxmlrpc system.has.public_methods ; rtxmlrpc system.listMethods ) \
  | sort | uniq -c | egrep -v '^ +2 ' | awk '{print $2}'
system.capabilities
system.getCapabilities
system.listMethods
system.methodExist
system.methodHelp
system.methodSignature
system.multicall
system.shutdown
system.hostname
system.hostname ≫ string ‹hostname›

Returns the hostname of the system.

system.pid
system.pid ≫ value ‹pid›

Returns the main process ID of the running client.

system.random

rTorrent-PS 1.0+ only

system.random = [[‹lower›,] ‹upper›] ≫ value

Generate uniformly distributed random numbers in the range defined by lowerupper.

The default range with no args is 0RAND_MAX. Providing just one argument sets an exclusive upper bound, and two args define an inclusive range.

An example use-case is adding jitter to time values that you later check with elapsed.greater, to avoid load spikes and similar effects of clustered time triggers.

system.time
system.time_seconds
system.time_usec
system.time ≫ value ‹time›
system.time_seconds ≫ value ‹time›
system.time_usec ≫ value ‹time›

Returns the system times in epoch notation. system.time_usec returns the value in microseconds instead of seconds. system.time is essentially an alias for system.time_seconds.

TODO Is there any practical difference when using the cached system.time?

system.umask.set
system.umask.set ≫ value ‹time›

Set the umask for the running rTorrent process.

log.* commands

log.add_output
log.add_output = ‹scope›, ‹name› ≫ 0

This command adds another logging scope to a named log file, opened by one of the log.open_file commands.

Log messages are classified into groups (connection, dht, peer, rpc, storage, thread, torrent, and tracker), and have a level of critical, error, warn, notice, info, or debug.

Scopes can either be a whole level, or else a group on a specific level by using ‹group›_‹level› as the scope’s name.

Example:

log.add_output = tracker_debug, tracelog
log.execute
log.execute = ‹path› ≫ 0

(Re-)opens a log file that records commands called via execute.* commands, including their return code and output. This can grow large quickly, see Log Rotation, Archival, and Pruning for how to manage this and other log files.

Passing an empty string closes the file.

Example:

log.execute = (cat, (cfg.logs), "execute.log")
log.xmlrpc
log.xmlrpc = ‹path› ≫ 0

(Re-)opens a log file that contains a log of commands executed via XMLRPC. This logs the raw SCGI and XMLRPC call and response for each request. The file can get huge quickly, see Log Rotation, Archival, and Pruning for how to manage this and other log files.

Passing an empty string closes the file.

Example:

log.xmlrpc = (cat, (cfg.logs), "xmlrpc.log")
log.open_file
log.open_gz_file
log.open_file_pid
log.open_gz_file_pid
log.open_file = ‹name›, ‹log file path›[, ‹scope›…] ≫ 0
log.open_gz_file
log.open_file_pid
log.open_gz_file_pid

All these commands open a log file, giving it a name to refer to. Paths starting with ~ are expanded. You can immediately add some logging scopes, see log.add_output for details on those.

The pid variants add the PID of rTorrent at the end of the file name (see Log Rotation, Archival, and Pruning for a way better scheme for log separation). Adding gz opens the logfile directly as a compressed streams, note that you have to add an appropriate extension yourself.

There is an arbitrary limit on the number of log streams you can open (64 in 0.9.6). The core of the logging subsystem is implemented in torrent/utils/log of libtorrent.

You can re-open existing logs in rTorrent-PS 1.1+ (and maybe in rTorrent 0.9.7+), by just calling an open command with a new path. To ‘close’ one, bind it to /dev/null.

Example:

log.open_file_pid = tracker, /tmp/tracker.log, tracker_debug
# … opens '/tmp/tracker.log.NNNNN' for debugging tracker announces etc.

Warning

Compressed log files do not seem to work, in version 0.9.6 at least.

log.vmmap.dump
log.vmmap.dump = ‹dump file path› ≫ 0

Dumps all memory mapping regions to the given file, each line contains a region in the format ‹begin›-‹end› [‹size in KiB›k].

log.messages

rTorrent-PS 0.x+ only

log.messages = ‹log file path› ≫ 0

(Re-)opens a log file that contains the messages normally only visible on the main panel and via the l key. Each line is prefixed with the current date and time in ISO8601 format. If an empty path is passed, the file is closed.

Example

log.messages = (cat, (cfg.logs), "messages.log")

Network (Sockets, HTTP, XMLRPC)

network.* commands

network.bind_address
network.bind_address.set
TODO
network.http.dns_cache_timeout
network.http.dns_cache_timeout.set
network.http.dns_cache_timeout.set = ‹seconds› ≫ 0
network.http.dns_cache_timeout ≫ ‹seconds›

Controls the DNS cache expiry (in seconds) for HTTP requests. The default is 60 seconds.

Set to zero to completely disable caching, or set to -1 to make the cached entries remain forever.

network.http.current_open
network.http.max_open
network.http.max_open.set
network.http.current_open ≫ value ‹num›
network.http.max_open ≫ value ‹max›
network.http.max_open.set = ‹max› ≫ 0

network.http.current_open returns the number of currently opened HTTTP connections, and network.http.max_open determines the upper limit for simultaneous HTTP connections.

Be wary of setting this too high, as even if your connection can support that many requests, the target host may not be able to respond quickly enough, leading to timeouts.

network.http.proxy_address
network.http.proxy_address.set
TODO
network.http.cacert
network.http.cacert.set
network.http.capath
network.http.capath.set
TODO
network.http.ssl_verify_host
network.http.ssl_verify_host.set
network.http.ssl_verify_peer
network.http.ssl_verify_peer.set
TODO
network.listen.backlog
network.listen.backlog.set
network.listen.port
TODO
network.local_address
network.local_address.set
TODO
network.max_open_files
network.max_open_files.set
TODO
network.max_open_sockets
network.max_open_sockets.set
network.open_sockets
TODO
network.port_open
network.port_open.set
network.port_random
network.port_random.set
network.port_range
network.port_range.set
TODO
network.proxy_address
network.proxy_address.set
TODO
network.receive_buffer.size
network.receive_buffer.size.set
network.send_buffer.size
network.send_buffer.size.set
network.receive_buffer.size ≫ value ‹size›
network.receive_buffer.size.set = ‹size› ≫ 0
network.send_buffer.size ≫ value ‹size›
network.send_buffer.size.set = ‹size› ≫ 0

Sets or gets the maximum socket receive / send buffer in bytes.

On Linux, the default buffer size for receiving data is set by the /proc/sys/net/core/rmem_default file (wmem_default for sending). The maximum allowed value is set by the /proc/sys/net/core/rmem_max file (wmem_max for sending).

See the tuning guide for tweaking these values

network.scgi.dont_route
network.scgi.dont_route.set
network.scgi.dont_route ≫ bool (0 or 1)
network.scgi.dont_route.set = ‹bool› ≫ 0

Enable / disable routing on SCGI connections, directly calling setsockopt to modify the SO_DONTROUTE flag.

network.scgi.open_local
network.scgi.open_port
network.scgi.open_local = string ‹path› ≫ 0
network.scgi.open_port = string ‹domain_or_ip›:‹port› ≫ 0

Open up a Unix domain socket or a TCP port for SCGI communication (i.e. the XMLRPC socket). Only use one of these!

Note

Using network.scgi.open_port means any user on the machine you run rTorrent on can execute arbitrary commands with the permission of the rTorrent runtime user. Most people don’t realize that, now you do! Also, never use any other address than 127.0.0.1 with it.

network.tos.set
network.tos.set = ‹flag› ≫ 0

Set the type of service flag to use in IP packets.

The options as pulled from strings.ip_tos are:

  • default
  • lowdelay
  • throughput
  • reliability
  • mincost

default uses the system default setting. A raw hexadecimal value can also be passed in for custom flags.

network.xmlrpc.dialect.set
network.xmlrpc.dialect.set = ‹dialect [value 0…2]› ≫ 0

Set the XMLRPC dialect to use, as defined by xmlrpc-c. The dialect parameter can have these values:

  • 0 – dialect_generic
  • 1 – dialect_i8
  • 2 – dialect_apache

dialect_i8 is the default value, which means the XMLRPC API will use the xmlrpc-c i8 extension type for returning long integers.

See its documentation for more information on how xmlrpc-c handles dialects.

network.xmlrpc.size_limit
network.xmlrpc.size_limit.set
network.xmlrpc.size_limit = ≫ value ‹bytes›
network.xmlrpc.size_limit.set = ‹max-size› ≫ 0

Set or return the maximum size of any XMLRPC requests in bytes. Human-readable forms such as 2M are also allowed (for 2 MiB, i.e. 2097152 bytes).

network.history.auto_scale
network.history.auto_scale.set
network.history.depth
network.history.depth.set
network.history.refresh
network.history.sample

Commands to add network traffic charts to the bottom of the collapsed download display.

Add these lines to your configuration:

# rTorrent-PS 0.*+ only!

# Show traffic of the last hour (112*32 = 3584 ≈ 3600)
network.history.depth.set = 112

method.insert = network.history.auto_scale.toggle, simple|private,\
    "branch=(network.history.auto_scale),\
        ((network.history.auto_scale.set, 0)),\
        ((network.history.auto_scale.set, 1))"
method.insert = network.history.auto_scale.ui_toggle, simple|private,\
    "network.history.auto_scale.toggle= ; network.history.refresh="

schedule2 = network_history_sampling, 1, 32, "network.history.sample="
schedule2 = bind_auto_scale, 0, 0,\
    "ui.bind_key=download_list, =, network.history.auto_scale.ui_toggle="

This will add the graph above the footer, you get the upper and lower bounds of traffic within your configured time window, and each bar of the graph represents an interval determined by the sampling schedule.

Pressing = toggles between a graph display with base line 0, and a zoomed view that scales it to the current bounds.

ip_tables.* commands

ip_tables.add_address
ip_tables.get
ip_tables.insert_table
ip_tables.size_data
TODO

ipv4_filter.* commands

ipv4_filter.add_address
ipv4_filter.dump
ipv4_filter.get
ipv4_filter.load
ipv4_filter.size_data
TODO

Bittorrent Protocol

dht.* commands

See the Github wiki for an example of enabling DHT in rTorrent.

dht.add_node
dht.add_node = string ‹[host]:[port]› ≫ 0

Adds a hostname/port to use for bootstrapping DHT information.

dht.mode.set
dht
dht.mode.set = string ‹mode› ≫ 0
dht = string ‹mode› ≫ 0

Controls when (if at all) DHT is activated. Regardless of what this is set to, DHT will never be used for torrents with the “private” flag enabled (see d.is_private). dht is an alias for dht.mode.set.

Possible values are:

  • on – Start DHT immediately.
  • off – Do not start DHT.
  • auto – Start and stop DHT as needed.
  • disable – Completely disable DHT.
dht.port
dht.port.set
dht_port
dht.port ≫ value ‹port›
dht.mode.set = value ‹port› ≫ 0
dht_port = value ‹port› ≫ 0

Controls which port DHT will listen on. Note that dht_port is an alias for dht.port.set, not dht.port.

dht.statistics

Returns {'active': 0, 'dht': 'disable', 'throttle': ''} when DHT is off, and …

TODO

dht.throttle.name
dht.throttle.name.set
TODO

pieces.* commands

pieces.hash.on_completion
pieces.hash.on_completion.set
pieces.hash.on_completion ≫ bool (0 or 1)
pieces.hash.on_completion.set = bool (0 or 1) ≫ 0

When set to true, this triggers a full hash check after a torrent completes. This is not strictly necessary, as hashing already occurs as each piece is downloaded, and turning it off is recommended if you encounter bugs such as completed torrents not announcing properly.

pieces.hash.queue_size
TODO
pieces.memory.block_count
pieces.memory.block_count ≫ value ‹blocks›

Returns the number of blocks rTorrent is tracking in memory. TODO What determines block size?

pieces.memory.current
pieces.memory.current ≫ value ‹bytes›

Returns the amount of memory rTorrent is currently using to track pieces which haven’t yet been synced to a file.

pieces.memory.max
pieces.memory.max.set
pieces.memory.max ≫ value ‹bytes›
pieces.memory.max.set = value ‹bytes› ≫ 0

Controls the max amount of memory used to hold chunk information. By default this is set to 1/5 of the available detected memory.

pieces.memory.sync_queue
pieces.memory.sync_queue ≫ value ‹bytes›

The amount of memory queued to be synced.

pieces.preload.min_rate
pieces.preload.min_rate.set
pieces.preload.min_size
pieces.preload.min_size.set
pieces.preload.min_rate ≫ value ‹bytes›
pieces.preload.min_rate.set = ‹bytes› ≫ 0
pieces.preload.min_size ≫ value ‹chunks›
pieces.preload.min_size.set = ‹chunks› ≫ 0

Preloading can be controlled to only activate when an item either reaches a certain rate of upload, and when the piece size is greater than a certain amount. Both conditions must be met in order for preloading to occur.

pieces.preload.type
pieces.preload.type.set
pieces.preload.type ≫ value ‹enum›
pieces.preload.type.set = value ‹enum› ≫ 0

When a piece is to be uploaded to a peer, rTorrent can preload the piece of the file before it does the non-blocking write to the network. This will not complete the whole piece if parts of the piece is not already in memory, having instead to try again later.

Possible values for value are:

  • 0 – off
  • 1 – madvise
  • 2 – direct page

Off means it doesn’t do any preloading at all.

madvise means it calls madvise on the file for the specific mmap‘ed memory range, which tells the kernel to load it in memory when it gets around to it. Which is hopefully before rTorrent writes to the network socket.

Direct paging means it touches each file page in order to force the kernel to load it into memory. This can help if you’re dealing with very large number of peers and large/many files, especially in a low-memory setting, as you can avoid thrashing the disk where loaded file pages get thrown out before they manage to get sent.

pieces.stats_not_preloaded
pieces.stats_preloaded
pieces.stats_not_preloaded ≫ value ‹num›
pieces.stats_preloaded ≫ value ‹num›

This counts the number of pieces that were preloaded or not, as per pieces.preload.min_size and pieces.preload.min_rate. If pieces.preload.type is set to 0, all pieces will be marked as not_preloaded.

pieces.stats.total_size
pieces.stats.total_size ≫ value ‹bytes›

Returns the total cumulative size of all files in all items. This includes incomplete files and does not consider duplicates, so it will often be larger than the sum of all the files as they exist on the disk.

pieces.sync.always_safe
pieces.sync.always_safe.set
pieces.sync.always_safe ≫ bool (0 or 1)
pieces.sync.always_safe.set = bool (0 or 1) ≫ 0

When safe sync is enabled, each chunk is synced to the file synchronously, which is slightly slower but ensures that the file has been written correctly.

pieces.sync.queue_size
pieces.sync.queue_size ≫ value ‹chunks›

The number of chunks that are queued up for writing in memory (i.e. not written to a file yet).

pieces.sync.safe_free_diskspace
pieces.sync.safe_free_diskspace ≫ value ‹bytes›

If d.free_diskspace ever drops below this value, all chunks will behave as though pieces.sync.always_safe is set to true. This is set to pieces.memory.current + 512 MiB.

pieces.sync.timeout
pieces.sync.timeout.set
pieces.sync.timeout ≫ value ‹seconds›
pieces.sync.timeout.set = value ‹seconds› ≫ 0

If the piece hasn’t been synced within this time period, immediately mark it for syncing.

pieces.sync.timeout_safe
pieces.sync.timeout_safe.set
pieces.sync.timeout_safe ≫ value ‹seconds›
pieces.sync.timeout_safe.set = value ‹seconds› ≫ 0

TODO This does not appear to be in use.

protocol.* commands

protocol.choke_heuristics.down.leech
protocol.choke_heuristics.down.leech.set
protocol.choke_heuristics.down.seed
protocol.choke_heuristics.down.seed.set
protocol.choke_heuristics.up.leech
protocol.choke_heuristics.up.leech.set
protocol.choke_heuristics.up.seed
protocol.choke_heuristics.up.seed.set
TODO
protocol.connection.leech
protocol.connection.leech.set
protocol.connection.seed
protocol.connection.seed.set
TODO
protocol.encryption.set
protocol.encryption.set = string ‹flags› ≫ 0

This command takes a comma-separated list of flags, as seen in strings.encryption, and uses them to determine how to handle connections to other peers (i.e. tracker and DHT connections are not effected by this setting). The flags are all applied simultaneously, which means that certain applied flags may not take effect (e.g. for prefer_plaintext,require_rc4, plaintext will never used despite the flag being applied). rTorrent has support for both plaintext “encryption” (uses no extra CPU cycles, provides only obfuscation of the header) and RC4 encryption (encrypts the entire header and message, at the cost of a few CPU cycles), with flags to control the behavior of both.

  • none – The default, don’t attempt any encryption.
  • allow_incoming – Allow incoming encrypted connections from other peers.
  • try_outgoing – Attempt to set up encryption when initiating a connection.
  • require – Require encryption, and reject peers who don’t support it.
  • require_RC4 – Require RC4 encryption specifically.
  • require_rc4 – Same as above.
  • enable_retry – If a peer is rejected for not supporting the encryption we need, retry the handshake.
  • prefer_plaintext – Prefer plaintext encryption.

See BitTorrent protocol encryption for more information.

protocol.pex
protocol.pex.set
protocol.pex ≫ bool (0 or 1)
protocol.pex.set = bool (0 or 1) ≫ 0

Controls whether peer exchange is enabled.

throttle.* commands

Throttles are names for bandwidth limitation rules (for upload, download, or both). The throttle assigned to the item in focus can be changed using Ctrl-T – it will rotate through all defined ones.

There are two system throttles, NULL and the one with an empty name. NULL is a special throttle for unlimited, and the latter is the global throttle, which is the default for new items and what’s shown in the status bar on the left as [Throttle ‹UP›/‹DOWN› KB].

TODO Explain how throttles work, borrowing from the global throttle.

Other commands in this group determine the limits for upload / download slots, and the amount of peers requested in tracker announces.

Warning

Note that since named throttles borrow from the global throttle, the global one has to be set to a non-zero value for the named ones to work (because borrowing from ∞ means there is no limit).

throttle.down
throttle.up
throttle.down = ‹name›, ‹rate› ≫ 0
throttle.up = ‹name›, ‹rate› ≫ 0

Define a named throttle. The rate must be a string (important when using XMLRPC), and is always in KiB/s.

You can also set a new rate for existing throttles this way (i.e. repeated definitions are no error).

throttle.down.max
throttle.up.max
throttle.down.max = ‹name› ≫ value ‹limit›
throttle.up.max = ‹name› ≫ value ‹limit›

Get the current limit of a named throttle in bytes/s.

Unknown throttles return -1, unlimited ones 0. If the global throttle is not set, you also get 0 for any call.

throttle.down.rate
throttle.up.rate
throttle.down.rate = ‹name› ≫ value ‹rate›
throttle.up.rate = ‹name› ≫ value ‹rate›

Get the current rate of a named throttle in bytes/s, averaged over recent history.

Unknown throttles always return 0. If the global throttle is not set, you also get 0 for any call.

throttle.global_down.max_rate
throttle.global_down.max_rate.set
throttle.global_down.max_rate.set_kb
throttle.global_up.max_rate
throttle.global_up.max_rate.set
throttle.global_up.max_rate.set_kb
Query or change the current value for the global throttle. Always use set_kb to change these values (the set commands have bugs), and be aware that you always get bytes/s when querying them.
throttle.global_down.rate
throttle.global_up.rate
throttle.global_down.rate ≫ value ‹rate›
throttle.global_up.rate ≫ value ‹rate›

Current overall bandwidth usage in bytes/s, averaged over recent history.

throttle.global_down.total
throttle.global_up.total
throttle.global_down.total ≫ value ‹bytes›
throttle.global_up.total ≫ value ‹bytes›

Amount of data moved over all items, in bytes.

TODO … in this session, including deleted items?

throttle.max_downloads
throttle.max_downloads.set
throttle.max_downloads.div
throttle.max_downloads.div.set
throttle.max_downloads.div._val
throttle.max_downloads.div._val.set
throttle.max_uploads
throttle.max_uploads.set
throttle.max_uploads.div
throttle.max_uploads.div.set
throttle.max_uploads.div._val
throttle.max_uploads.div._val.set
TODO
throttle.max_downloads.global
throttle.max_downloads.global.set
throttle.max_downloads.global._val
throttle.max_downloads.global._val.set
throttle.max_uploads.global
throttle.max_uploads.global.set
throttle.max_uploads.global._val
throttle.max_uploads.global._val.set
TODO
throttle.min_downloads
throttle.min_downloads.set
throttle.min_uploads
throttle.min_uploads.set
TODO
throttle.max_peers.normal
throttle.max_peers.normal.set
throttle.max_peers.seed
throttle.max_peers.seed.set
throttle.min_peers.normal
throttle.min_peers.normal.set
throttle.min_peers.seed
throttle.min_peers.seed.set
TODO
throttle.unchoked_downloads
throttle.unchoked_uploads
TODO
throttle.ip
throttle.ip = ‹throttle name›, ‹IP or domain name› ≫ 0

Throttle a specific peer by its IP address.

throttle.names
# rTorrent-PS 1.1+ only
throttle.names= ≫ array ‹names›

Returns a list of all defined throttle names, including the built-in ones (i.e. '' and 'NULL').

Example:

$ rtxmlrpc --repr throttle.names
['', 'NULL', 'kb500', 'lo_up', 'onemb']

User Interface

ui.* commands

Commands in this group control aspects of the curses UI.

ui.current_view
ui.current_view.set

ui.current_view since rTorrent-PS 0.x / rTorrent 0.9.7

ui.current_view.set = ‹viewname› ≫ 0
ui.current_view ≫ string ‹viewname›

Query or change the current view the user is seeing. view.list gives you a list of all the built-in and added views.

Typical uses are to change and then restore the active view, or rotate through a set of views. Rotating through views requires querying the current view and the view list, to find the next one.

In rTorrent-PS 1.1+ and rTorrent 0.9.8+, view changes also trigger event handlers for event.view.hide and event.view.show.

ui.current_view is needed if you want to use a hyphen - as a view name in rtcontrol to refer to the currently shown view. An example for that is passing -M- as an option, which performs in-place filtering of the current view via rtcontrol.

torrent_list_layout
ui.torrent_list.layout
ui.torrent_list.layout.set

since rTorrent 0.9.7

Offers a choice between full and compact layout.

ui.unfocus_download
Used internally before erasing an item, to move the focus away from it.
ui.bind_key
ui.bind_key.verbose
ui.bind_key.verbose.set

rTorrent-PS 0.x+ / 1.1+ only

# rTorrent-PS 0.x+ only
ui.bind_key = ‹display›, ‹key›, "command=[...]" ≫ 0
# rTorrent-PS 1.1+ only
ui.bind_key.verbose = ≫ bool (0 or 1)
ui.bind_key.verbose.set = ‹mode› (0 or 1) ≫ 0

Binds the given key on a specified display to execute the given command when pressed. Note that this needs to be called in a one-shot schedule, after rTorrent is fully initialized.

display must always be download_list, for the moment (currently, no other displays are supported).

key can be either a single character for normal keys, ^ plus a character for control keys, or a 4 digit octal code for special keys.

The ui.bind_key.verbose flag determines whether replacing an existing binding is logged (1, the default) or not (0).

Configuration Example

# Bind '^' to show the last "rtcontrol" result
schedule2 = bind_view_rtcontrol, 1, 0,\
    "ui.bind_key = download_list, ^, ui.current_view.set=rtcontrol"

Important

This currently can NOT be used immediately when rtorrent.rc is parsed, so it has to be scheduled for one-shot execution, shortly after startup (see above example).

ui.color.custom1…9
ui.color.alarm
ui.color.complete
ui.color.even
ui.color.focus
ui.color.incomplete
ui.color.info
ui.color.label
ui.color.leeching
ui.color.odd
ui.color.progress0
ui.color.progress20
ui.color.progress40
ui.color.progress60
ui.color.progress80
ui.color.progress100
ui.color.progress120
ui.color.queued
ui.color.seeding
ui.color.stopped
ui.color.title
ui.color.‹type›.set
ui.color.‹type›.index

rTorrent-PS 0.x+ only

ui.color.‹type›= ≫ string ‹color-spec›
ui.color.‹type›.set=‹color-spec› ≫ 0

These commands allow you to set colors for selected elements of the user interface in rTorrent-PS, in some cases depending on their status.

You can either provide colors by specifying the numerical index in the terminal’s color table, or by name (for the first 16 colors). The possible color names are “black”, “red”, “green”, “yellow”, “blue”, “magenta”, “cyan”, “gray”, and “white”.

You can use those names for both text and background color, in the form “«fg» on «bg»”, and you can add “bright” in front of a color to select a more luminous version. If you don’t specify a color, the default of your terminal is used.

Also, these additional modifiers can be placed in the color definitions, but it depends on the terminal you’re using whether they have an effect: “bold”, “standout”, “underline”, “reverse”, “blink”, and “dim”.

The private ui.color.‹type›.index calls return the related ID in the rTorrent-PS color table. These IDs are used in the color definitions C‹id›/‹len› of ui.column.render.

See the color scheme for 256 xterm colors for an example.

ui.canvas_color
ui.canvas_color.set

rTorrent-PS 1.1+ only

Not working right now.

ui.column.render

rTorrent-PS 1.1+ only

This is a multi-command that holds the column layout specifications for the customizable canvas v2 display in rTorrent-PS version 1.1+, and maps them to their rendering commands.

See Customizing the Display Layout in the rTorrent-PS manual for a detailed explanation.

ui.column.spec

rTorrent-PS 1.1+ only

ui.column.spec = ‹column index› ≫ string (column specification)

For a given column index, looks up the column specification as defined in ui.column.render. This can also be used to check whether a certain index is defined – an undefined one returns an empty string.

Examples

# Permanently remove the 'ignoring commands' column
method.set_key = ui.column.render, (ui.column.spec, 130)
$ rtxmlrpc --repr ui.column.spec '' 100
u'100:3C…/2:… '
$ rtxmlrpc --repr ui.column.spec '' +100
u'100:3C…/2:… '
$ rtxmlrpc --repr ui.column.spec '' 000
''
$ rtxmlrpc ui.column.spec
ERROR … ui.column.spec takes exactly one argument
ui.column.hide
ui.column.show
ui.column.is_hidden
ui.column.hidden.list

rTorrent-PS 1.1+ only

ui.column.hide = ‹column index›[, …] ≫ 0
ui.column.show = ‹column index›[, …] ≫ 0
ui.column.is_hidden = ‹column index› ≫ bool (0 or 1)
ui.column.hidden.list = ≫ array of value (column index list)

Hide or show columns by their index. The hide/show commands take any number of arguments, or a list of values.

The ui.column.is_hidden command allows to query the visibility of a column, and the last command returns a list of index values for all hidden columns.

The hiddden state is not persisted over client restarts. Also note that some columns are auto-hidden in case the terminal gets too narrow to show all of them.

ui.column.sacrificed
ui.column.sacrificed.set
ui.column.sacrificed.toggle
ui.column.sacrificial.list

rTorrent-PS 1.1+ only

The ui.column.sacrificed value is false (0) by default, and can set set as usual. The ui.column.sacrificed.toggle command changes the state of this value and ui.column.hides or ui.column.shows all the columns that ui.column.sacrificial.list returns (as a list of values).

ui.focus.end
ui.focus.home
ui.focus.pgdn
ui.focus.pgup
ui.focus.page_size
ui.focus.page_size.set

rTorrent-PS 0.x+ only

These commands support quick paging through the download list, and jumping to the start or end of it. See bind-navigation-keys.rc on how to use them in a rTorrent-PS configuration.

With the ui.focus.page_size.set command, the amount of items to skip can be changed from the default value of 50, e.g. in the _rtlocal.rc file.

ui.style.progress
ui.style.progress.set
ui.style.ratio
ui.style.ratio.set

rTorrent-PS 0.x+ only, obsolete with 1.1+

view.* commands

view.add
view.list
view.size
view.persistent
TODO
view.event_added
view.event_removed
TODO
view.filter
view.filter_all
view.filter_download
view.filter_on
TODO
view.set
view.set_visible
view.set_not_visible
view.size_not_visible
TODO
view.sort
view.sort_current
view.sort_new
TODO
view.collapsed.toggle
# rTorrent-PS 0.*+ only
view.collapsed.toggle=‹view-name› ≫ 0

This command changes between the normal item display, where each item takes up three lines, to a more condensed form exclusive to rTorrent-PS, where each item only takes up one line.

Further explanations on what the columns show and what forms of abbreviations are used, to get a display as compact as possible while still showing all the important stuff, can be found on Extended Canvas Explained. There you also find hints on how to correctly setup your terminal.

Note that each view has its own state, and that if the view name is empty, the current view is toggled. Newly added views are expanded – but in rTorrent-PS 1.1+ the built-in views are collapsed by default.

You can set the default state of views to collapsed in your configuration, by adding a toggle command for each created view.

Also when using rTorrent-PS before version 1.1, you should bind the current view toggle to a key, like this:

schedule = bind_collapse,0,0,"ui.bind_key=download_list,*,view.collapsed.toggle="

Miscellaneous

strings.* commands

strings.choke_heuristics
  • upload_leech
  • upload_leech_dummy
  • download_leech
  • download_leech_dummy
  • invalid
strings.choke_heuristics.download
  • download_leech
  • download_leech_dummy
strings.choke_heuristics.upload
  • upload_leech
  • upload_leech_dummy
strings.connection_type
  • leech
  • seed
  • initial_seed
  • metadata
strings.encryption
  • none
  • allow_incoming
  • try_outgoing
  • require
  • require_RC4
  • require_rc4
  • enable_retry
  • prefer_plaintext
strings.ip_filter
  • unwanted
  • preferred
strings.ip_tos
  • default
  • lowdelay
  • throughput
  • reliability
  • mincost

Options for network.tos.set.

strings.tracker_mode
  • normal
  • aggressive
strings.tracker_event

since rTorrent 0.9.7

  • completed
  • scrape
  • started
  • stopped
  • updated
strings.log_group

since rTorrent 0.9.7

  • connection_critical
  • connection_debug
  • connection_error
  • connection_info
  • connection_notice
  • connection_warn
  • critical
  • debug
  • dht_all
  • dht_critical
  • dht_debug
  • dht_error
  • dht_info
  • dht_manager
  • dht_node
  • dht_notice
  • dht_router
  • dht_server
  • dht_warn
  • error
  • info
  • instrumentation_choke
  • instrumentation_memory
  • instrumentation_mincore
  • instrumentation_polling
  • instrumentation_transfers
  • __non_cascading__
  • notice
  • peer_critical
  • peer_debug
  • peer_error
  • peer_info
  • peer_list_events
  • peer_notice
  • peer_warn
  • protocol_metadata_events
  • protocol_network_errors
  • protocol_piece_events
  • protocol_storage_errors
  • resume_data
  • rpc_dump
  • rpc_events
  • socket_critical
  • socket_debug
  • socket_error
  • socket_info
  • socket_notice
  • socket_warn
  • storage_critical
  • storage_debug
  • storage_error
  • storage_info
  • storage_notice
  • storage_warn
  • thread_critical
  • thread_debug
  • thread_error
  • thread_info
  • thread_notice
  • thread_warn
  • torrent_critical
  • torrent_debug
  • torrent_error
  • torrent_info
  • torrent_notice
  • torrent_warn
  • tracker_critical
  • tracker_debug
  • tracker_error
  • tracker_info
  • tracker_notice
  • tracker_warn
  • ui_events
  • warn

Singular Commands

These are ‘special’ and fall into no group.

directory.watch.added

since rTorrent 0.9.7

directory.watch.added = ‹root folder path›, ‹handler command name› ≫ 0

On Linux, use this command to watch a directory tree via inotify.

The provided handler command is called with the the full path of new files as the first argument, i.e. argument.0 in a custom handler method. Use method.insert to define such a more complex multi-command handler, and then use its name as the second argument to directory.watch.added.

See Watch Directories in the rTorrent wiki for more.

Configuration Example

directory.watch.added = "~/Downloads/watch/", load.start_verbose

TODO (Groups)

  • choke_group
  • file
  • group
  • group2
  • keys
  • ratio
  • scheduler
directory.default
directory.default.set
directory
encoding.add
encoding_list
TODO
trackers.disable
trackers.enable
trackers.numwant
trackers.numwant.set
trackers.use_udp
trackers.use_udp.set
TODO
trackers.alias.items

Returns all the mappings in the form «domain»=«alias» as a list.

Note that domains that were not explicitly defined so far, but shown previously, are also contained in the list, with an empty alias. So to create a list for you to fill in the aliases, scroll through all your items on main or trackers, so you can dump the domains of all loaded items.

Example that prints all the domains and their aliases as commands that define them:

rtxmlrpc trackers.alias.items \
    | sed -r -e 's/=/, "/' -e 's/^/trackers.alias.set_key = /' -e 's/$/"/' \
    | tee ~/rtorrent/rtorrent.d/tracker-aliases.rc

This also dumps them into the tracker-aliases.rc file to persist your mappings, and also make them easily editable. To reload edited alias definitions, use this:

rtxmlrpc "try_import=,~/rtorrent/rtorrent.d/tracker-aliases.rc"
trackers.alias.set_key

Sets an alias that replaces the given domain, when displayed on the right of the collapsed canvas.

Configuration Example

trackers.alias.set_key = bttracker.debian.org, Debian

TODO (singles)

print
add_peer
bind
catch
check_hash
connection_leech
connection_seed
download_rate
encoding_list
encryption
ip
key_layout
max_downloads
max_downloads_div
max_downloads_global
max_memory_usage
max_peers
max_peers_seed
max_uploads
max_uploads_div
max_uploads_global
min_downloads
min_peers
min_peers_seed
min_uploads
on_ratio
port_random
port_range
proxy_address
scgi_local
scgi_port
torrent_list_layout
upload_rate
fi.filename_last
fi.is_file
file.append
keys.layout
keys.layout.set
TODO

‘Intermediate’ Commands

The intermediate commands are kept around as aliases for ‘new’ ones – at least for the time being. Probably best avoided.

Avoiding the deprecated commands is a must, these will disappear at some time.

method.use_deprecated
method.use_deprecated.set
method.use_deprecated ≫ bool (0 or 1)
method.use_deprecated.set = ‹0 or 1› ≫ bool ‹current› (0 or 1)

The default is true. The undocumented -D command line options sets this to false with a Disabled deprecated commands console message.

method.use_intermediate
method.use_intermediate.set
method.use_intermediate ≫ value (0 … 2)
method.use_intermediate.set = ‹0 … 2› ≫ value ‹current› (0 … 2)

The default is 1 (allow everywhere), values other than 1 or 2 are treated like 0. The undocumented -I command line options sets this to 0 with a Disabled intermediate commands console message, while -K sets it to 2, printing Allowing intermediate commands without xmlrpc.

All the command aliases can be found in these three source files: command_local.cc, command_throttle.cc, and main.cc. Search for REDIRECT using grep.

These are called intermediate:

  • executeexecute2 (ignore both, just use execute.throw)
  • scheduleschedule2
  • schedule_removeschedule_remove2
  • group.‹name›.viewgroup2.‹name›.view
  • group.‹name›.view.setgroup2.‹name›.view.set
  • group.‹name›.ratio.mingroup2.‹name›.ratio.min
  • group.‹name›.ratio.min.setgroup2.‹name›.ratio.min.set
  • group.‹name›.ratio.maxgroup2.‹name›.ratio.max
  • group.‹name›.ratio.max.setgroup2.‹name›.ratio.max.set
  • group.‹name›.ratio.uploadgroup2.‹name›.ratio.upload
  • group.‹name›.ratio.upload.setgroup2.‹name›.ratio.upload.set

rTorrent 0.9.7 adds some missing group.seeding.* command aliases.

Standard Configuration Sets

The following sections explain some core commands added by well-known configuration sets.

If you want other setups (rtinst, QuickBox, …) to be documented, we accept pull requests.

Examples in This Manual

These commands are from snippets presented in other chapters.

cfg.drop_in
See Load ‘Drop-In’ Config Fragments. This is a private command.
event.download.finished_delayed
event.download.finished_delayed.interval
event.download.finished_delayed.interval.set
See Delayed Completion Handling for a full explanation.

rTorrent Wiki Template

The CONFIG Template wiki page defines a few commands in its configuration snippet. See Config Template Deconstructed for a detailed tour.

cfg.basedir
cfg.watch
cfg.logs

These define important base paths in the file system layout of a rTorrent instance, and are all private. They are used where appropriate to define further paths like the session directory, and allow easy changes at just one place.

By default, cfg.watch and cfg.logs are sub-dirs of cfg.basedir.

system.startup_time
A constant value that holds the system.time when the client was started.
d.data_path

Return path to an item’s data – this is never empty, unlike d.base_path. Multi-file items return a path ending with a /.

Definition:

method.insert = d.data_path, simple,\
    "if=(d.is_multi_file),\
        (cat, (d.directory), /),\
        (cat, (d.directory), /, (d.name))"

pyrocore Configuration

TODO check if they belong with “p-m-b”

In addition to the commands listed here, pyrocore also defines d.data_path.

d.session_file

Return path to session file.

Definition:

method.insert = d.session_file, simple, "cat=(session.path), (d.hash), .torrent"
d.tracker.bump_scrape
Send a scrape request for an item, set its tm_last_scrape custom attribute to now, and save the session data. Part of `auto-scrape.rc`_, and bound to the & key in rTorrent-PS, to manually request a scrape update.
d.timestamp.downloaded
d.last_active
TODO
d.watch.start
d.watch.startable
cfg.watch.start
cfg.watch.start.set

TODO

d.watch.startable is private.

d.category.set
load.category
load.category.normal
load.category.start

To add an item to a category previously added with pyro.category.add, or move it from its old one, use d.category.set and pass the new category name.

The load commands use this to load items from watch directories named like a category – all items loaded from there are added to the related category view. cfg.watch is used as the root directory which contains the category watch directories. They are private, and all use the equivalent verbose built-in command under the hood. To make starting the new items optional, load.category uses the d.watch.startable mechanism.

The definitions are in rtorrent.d/categories.rc, and a usage example is in rtorrent.d/autolabel-categories.rc.

pyro.category.add
pyro.category.list

The private pyro.category.add command adds a named category. That means a category_‹name› view is defined – you can rotate though those views in rTorrent-PS using the < and > keys.

See d.category.set and load.category on how to put new items into a category.

If you call the pyro.category.list command, it prints a list of currently defined categories to the rTorrent console.

For a full example, see rtorrent.d/autolabel-categories.rc.

d.last_xfer
d.last_xfer.is_active
TODO
quit
TODO
cull
purge

TODO

These are private commands, use rtcontrol from outside the client.

startup_time
TODO
tag.add
tag.rm
tag.show

TODO

These are private commands, from outside the client use rtcontrol with --tag, and its tagged field.

pyro.logfile_path
TODO
pyro.collapsed_view.add
pyro.view.collapsed.toggle
TODO
pyro.view.toggle_visible
TODO
pyro.color_theme.name
Used in color theme files of rTorrent-PS to announce switching to a different theme (defined in pyrocore‘s rtorrent.d/theming.rc).
pyro.watchdog

TODO

This is a private command.

pimp-my-box Configuration

TODO

In addition to the commands listed here, pimp-my-box also defines cfg.basedir, cfg.watch, and cfg.logs, and includes anything from pyrocore Configuration.

pyro.extended

Set pyro.extended to 1 to activate rTorrent-PS features. Note that this tells the rest of the configuration that it can safely use the extended command set – it won’t magically make a vanilla rTorrent an extended one.

Starting with rTorrent-PS 1.1+, this setting is detected automatically, thanks to system.has.

pyro.bin_dir

A constant that should be set to the bin directory where you installed the pyrocore tools.

Make sure you end it with a /; if this is left empty, then the shell’s path is searched.