Rtorrent API
Apps & Automationrtorrent-apiRtorrent API is an Agent Skill for apps & automation published in the tympanix/Electorrent repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
rTorrent XML-RPC command reference focused on remote control, multicall patterns, load methods, and the torrent commands used by Electorrent.
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Inspect the Agent Skill at https://github.com/tympanix/Electorrent/blob/HEAD/.github/skills/rtorrent-api/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/rtorrent-api, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
Skill: rTorrent API
Purpose
Use this skill when you need to integrate with rTorrent over XML-RPC.
Protocol
- Transport: XML-RPC over HTTP(S)
- Common path:
/RPC2 - Command names are the API surface, for example
d.multicall2orload.start - Prefer modern dotted command names from rTorrent 0.9+; deprecated aliases like
load_start,d.get_name, orget_download_ratestill appear in old examples but should not be used for new integrations
Command model and calling conventions
- rTorrent exposes both variables and commands
- read a value with the variable-like command name, for example
d.name - mutate with a
.setcommand, for exampled.priority.set
- read a value with the variable-like command name, for example
- Multicall selector strings usually need a trailing
=- example:
d.multicall2("", "main", "d.hash=", "d.name=", "d.custom1=") - keyed accessors also follow that shape, for example
d.custom=addtime
- example:
- All torrent-scoped
d.*calls take the torrent info hash as the first XML-RPC argument
Example shape:
d.name = <hash> -> string
- Common scoped patterns:
t.multicall(<hash>, "", ...)for trackers on one torrentf.multicall(<hash>, "", ...)for files on one torrentp.multicall(<hash>, "", ...)for peers on one torrent
- Batch unrelated calls with
system.multicall([{ methodName, params }...])
Important command groups
| Group | Purpose | Important examples |
|---|---|---|
d.* | Torrent/download fields and actions | d.multicall2, d.name, d.state, d.start, d.stop, d.erase |
t.* | Tracker fields and tracker multicalls | t.multicall, t.url, t.scrape_complete, t.is_enabled |
f.* | File fields and file priority | f.multicall, f.path, f.size_bytes, f.priority.set |
p.* | Peer inspection | p.multicall, p.address, p.client_version, p.down_rate |
load.* | Add torrents and magnet links | load.normal, load.start, load.raw_start, verbose variants |
view.* | Named views for listing/filtering/sorting torrents | view.list, view.add, view.filter, view.sort |
session.* | Session path/name/save behavior | session.path, session.name, session.save |
method.*, schedule2, event.* | Scripting, dynamic methods, scheduling | method.insert, method.set_key, schedule2 |
execute.*, system.* | Host/system interaction | execute.throw, execute.capture, system.client_version, system.shutdown.normal |
network.*, protocol.*, throttle.*, dht.*, pieces.* | Connectivity, encryption, limits, DHT, piece behavior | network.port_range, protocol.encryption.set, throttle.global_down.max_rate.set, dht.mode.set |
directory.*, group*.seeding.ratio.* | Default save path and seeding ratio policy | directory.default.set, group.seeding.ratio.enable, group2.seeding.ratio.max.set |
Commands commonly used for remote clients
Connection and capability
system.client_versionsystem.api_versionif present on the targetview.list- enumerate named views such as
main
- enumerate named views such as
Torrent listing
d.multicall2("", "main", ...)- query many torrent fields at once from the
mainview
- query many torrent fields at once from the
system.multicall([...])- batch heterogeneous XML-RPC calls
Common listing fields for remote UIs:
- identity/path:
d.hash,d.name,d.base_path,d.directory,d.tied_to_file,d.loaded_file - size/progress:
d.size_bytes,d.completed_bytes,d.left_bytes,d.completed_chunks,d.chunk_size - state/rates:
d.is_active,d.is_open,d.complete,d.state,d.down.rate,d.up.rate,d.down.total,d.up.total - swarm/tracker summary:
d.peers_accounted,d.peers_complete,d.tracker_size,d.tracker_numwant - metadata/custom fields:
d.message,d.custom1,d.custom=addtime
Tracker listing
t.multicall(<hash>, "", ...)- query trackers for one torrent
Important tracker fields:
t.urlt.groupt.typet.is_enabledt.is_opent.min_intervalt.normal_intervalt.scrape_completet.scrape_downloadedt.scrape_incompletet.scrape_time_last
File and peer listing
f.multicall(<hash>, "", ...)- query per-file path, size, progress, and priority
p.multicall(<hash>, "", ...)- query live peer state when needed
Important file fields:
f.pathf.size_bytesf.completed_chunksf.size_chunksf.priorityf.priority.set
Important peer fields:
p.addressp.portp.client_versionp.completed_percentp.down_ratep.up_rate
Adding torrents
load.normal("", <uri>)- add without starting
load.start("", <uri>)- add from URL or magnet and start
load.raw("", <torrent-bytes>)- add raw torrent data without starting
load.raw_start("", <torrent-bytes>)- add from raw torrent bytes and start
load.verbose,load.start_verbose,load.raw_verbose- verbose load variants also exist on some targets
If a save location must be set at add time, pass it in the initial load.* call:
d.directory.set=<json-encoded-path>
Changing the directory after load is not equivalent for Electorrent's rTorrent flow.
Start/stop lifecycle
d.open(<hash>)d.start(<hash>)d.stop(<hash>)d.close(<hash>)
Typical start sequence:
d.opend.start
Typical stop sequence:
d.stopd.close
Removal and recheck
d.erase(<hash>)d.delete_tied(<hash>)d.check_hash(<hash>)
Common related fields:
d.hashingd.hashing_failedd.state_changedd.timestamp.startedd.timestamp.finished
Labels and priority
d.custom1.set(<hash>, <label>)d.custom.set(<hash>, <key>, <value>)d.custom1...d.custom5d.priority.set(<hash>, <0-3>)
Priority values commonly used by clients:
| Value | Meaning |
|---|---|
0 | off / do not download |
1 | low |
2 | normal |
3 | high |
Host-side filesystem helper
execute.throw("", "mkdir", "-p", <path>)- create download directories before loading a torrent
Useful related execution/system commands:
execute2,execute.nothrow,execute.captureexecute.*.bgbackground variantssystem.file.allocatesystem.shutdown.normalsystem.shutdown.quick
Session, view, and settings commands
Useful server/session inspection:
session.pathsession.namesession.savedirectory.defaultdirectory.default.set
Useful network/rate settings often surfaced by remote clients:
throttle.global_down.max_ratethrottle.global_down.max_rate.setthrottle.global_up.max_ratethrottle.global_up.max_rate.setthrottle.max_downloads.globalthrottle.max_downloads.global.setthrottle.max_uploads.globalthrottle.max_uploads.global.setnetwork.port_rangenetwork.port_range.setnetwork.port_opennetwork.bind_addressnetwork.proxy_addressnetwork.http.proxy_addressnetwork.scgi.open_localnetwork.scgi.open_portnetwork.xmlrpc.dialect.setnetwork.xmlrpc.size_limitprotocol.encryption.setprotocol.pexdht.mode.setdht.port
Scripting and automation
Useful for advanced integrations and config management:
method.insertmethod.getmethod.setmethod.list_keysmethod.has_keymethod.set_keyschedule2schedule_remove2
Useful multicall pattern
For efficient snapshots, use d.multicall2 for torrent rows and t.multicall or f.multicall for nested resources, then normalize result arrays by column order on the client side.
Example:
d.multicall2("", "main", "d.hash=", "d.name=", "d.size_bytes=", "d.custom=addtime")
Remember that selector order defines result column order.
Electorrent usage
Electorrent uses:
system.client_versiond.multicall2t.multicallsystem.multicallf.multicallload.startload.raw_startexecute.throwd.open,d.startd.stop,d.closed.custom1.setd.custom=addtimed.custom5.setd.erased.delete_tiedd.check_hashd.priority.set