TORF(1)

📦 version 5.2.1, in ubuntu stonking

✨ NAME ✨

okay so bestie, TORF(1) is the manual page for torf — literally the command line tool to create, display and edit torrents. no cap, she does it all. 💅

🌸 SYNOPSIS 🌸

torf PATH [OPTIONS] [-o TORRENT]
torf -i INPUT
torf -i INPUT [OPTIONS] -o TORRENT
torf -i TORRENT PATH

🎀 DESCRIPTION 🎀

torf can create, display and edit torrent files and verify the integrity of the files in a torrent. periodt.

torf PATH [OPTIONS] [-o TORRENT] — Create the torrent file TORRENT from the file or directory PATH. slay.
torf -i INPUT — Display information stored in the torrent file or magnet URI INPUT. info dump, but make it cute.
torf -i INPUT [OPTIONS] -o TORRENT — Edit the existing torrent file or magnet URI INPUT (e.g. to fix a typo) and create the new torrent file TORRENT.

Warning bestie, listen. Editing a torrent can change its hash, depending on what is changed, which essentially makes it a new torrent. See OPTIONS to find out whether a certain option will change the hash.

torf -i TORRENT PATH — Verify that the content in PATH matches the metadata in the torrent file TORRENT.

If PATH ends with a path separator (usually “/”), the name of the torrent (as specified by the metadata in TORRENT) is appended.

💅 OPTIONS 💅

fr fr, options that start with --no take precedence.

PATH — The path to the torrent’s content.
--in, -i INPUT — Read metainfo from the torrent file or magnet URI INPUT. If INPUT is “-” and does not exist, the torrent data or magnet URI is read from stdin.
--out, -o TORRENT — Write to torrent file TORRENT. Default: NAME.torrent
--reuse, -r PATH — Copy piece size and piece hashes from existing torrent PATH. The existing torrent must have identical files. If PATH is a directory, it is searched recursively for a matching torrent. This option may be given multiple times.
--noreuse, -R — Ignore all --reuse arguments. This is particularly useful if you have reuse paths in your configuration file.
--exclude, -e PATTERN — Exclude files from PATH that match the glob pattern PATTERN. This option may be given multiple times. See EXCLUDING FILES.
--include PATTERN — Include files from PATH that match the glob pattern PATTERN even if they match any --exclude or --exclude-regex patterns. This option may be given multiple times. See EXCLUDING FILES.
--exclude-regex, -er PATTERN — Exclude files from PATH that match the regular expression PATTERN. This option may be given multiple times. See EXCLUDING FILES.
--include-regex, -ir PATTERN — Include files from PATH that match the regular expression PATTERN even if they match any --exclude or --exclude-regex patterns. This option may be given multiple times. See EXCLUDING FILES.
--notorrent, -N — Do not create a torrent file.
--nomagnet, -M — Do not create a magnet URI.
--name, -n NAME — Destination file or directory when the torrent is downloaded. Default: Basename of PATH

Warning editing alert. When editing, this option changes the info hash and creates a new torrent.

--tracker, -t URL — List of comma-separated announce URLs. This option may be given multiple times for multiple tiers. Clients try all URLs from one tier in random order before moving on to the next tier.
--notracker, -T — Remove trackers from an existing torrent.
--webseed, -w URL — A webseed URL (BEP19). This option may be given multiple times.
--nowebseed, -W — Remove webseeds from an existing torrent.
--private, -p — Tell clients to only use tracker(s) for peer discovery, not DHT or PEX.

Warning editing alert. When editing, this option changes the info hash and creates a new torrent.

--noprivate, -P — Allow clients to use trackerless methods like DHT and PEX for peer discovery.

Warning editing alert. When editing, this option changes the info hash and creates a new torrent.

--comment, -c COMMENT — A comment that is stored in the torrent file.
--nocomment, -C — Remove the comment from an existing torrent.
--date, -d DATE — The creation date in the format YYYY-MM-DD[ HH:MM[:SS]], now for the current time or today for today at midnight. Default: now
--nodate, -D — Remove the creation date from an existing torrent.
--source, -s SOURCE — Add a “source” field to the torrent file. This is usually used to make the torrent’s info hash unique per tracker.

Warning editing alert. When editing, this option changes the info hash and creates a new torrent.

--merge JSON — Update existing metainfo in TORRENT with a JSON object. This option may be given multiple times. Fields in JSON that have a value of null (unquoted) are removed in the output TORRENT. Adding or removing items from an existing list is not supported.

This example adds a “custom” section to the “info” section, removes the “comment” field and changes “creation date”.

$ torf -i old.torrent \
       --merge '{"info": {"custom": {"this": "that", "numbers": [1, 2, 3]}}}' \
       --merge '{"comment": null, "creation date": 123456789}' \
       -o new.torrent

This also works when creating a torrent.

$ torf path/to/my/files \
       --merge '{"my stuff": {"my": ["s", "e", "c", "r", "e", "t"]}}'

Warning editing alert. If the “info” section is modified, the info hash changes and a new torrent is created.

--nosource, -S — Remove the “source” field from an existing torrent.

Warning editing alert. When editing, this option changes the info hash and creates a new torrent.

--xseed, -x — Randomize the info hash to help with cross-seeding. This simply adds an entropy field to the info section of the metainfo and sets it to a random integer.

Warning editing alert. When editing, this option changes the info hash and creates a new torrent.

--noxseed, -X — De-randomize a previously randomized info hash of an existing torrent. This removes the entropy field from the info section of the metainfo.

Warning editing alert. When editing, this option changes the info hash and creates a new torrent.

--max-piece-size SIZE — The maximum piece size when creating a torrent. SIZE is multiplied by 1 MiB (1048576 bytes). The resulting number must be a multiple of 16 KiB (16384 bytes). Use fractions for piece sizes smaller than 1 MiB (e.g. 0.5 for 512 KiB).
--creator, -a CREATOR — Name and version of the application that created the torrent.
--nocreator, -A — Remove the name of the application that created the torrent from an existing torrent.
--yes, -y — Answer all yes/no prompts with “yes”. At the moment, all this does is overwrite TORRENT without asking.
--config, -f FILE — Read command line arguments from configuration FILE. See CONFIGURATION FILE. Default: $XDG_CONFIG_HOME/torf/config where $XDG_CONFIG_HOME defaults to ~/.config
--noconfig, -F — Do not use any configuration file.
--profile, -z PROFILE — Use predefined arguments specified in PROFILE. This option may be given multiple times. See CONFIGURATION FILE.
--verbose, -v — Produce more output or be more thorough. This option may be given multiple times.
- Display bytes with and without unit prefix, e.g. “1.38 MiB / 1,448,576 B”.
- Any other effects are explained in the relevant arguments' documentation.
--json, -j — Print information and errors as a JSON object. Progress is not reported.
--metainfo, -m — Print the torrent’s metainfo as a JSON object. Byte strings (e.g. “pieces” in the “info” section) are encoded in Base64. Progress is not reported. Errors are reported normally on stderr.

Unless --verbose is given, any non-standard fields are excluded and metainfo that doesn’t represent a valid torrent results in an error.

Unless --verbose is given twice, the “pieces” field in the “info” section is excluded.

--human, -u — Display information in human-readable output even if stdout is not a TTY. See PIPING OUTPUT.
--nohuman, -U — Display information in machine-readable output even if stdout is a TTY. See PIPING OUTPUT.
--help, -h — Display a short help text and exit.
--version, -V — Display the version number and exit.

💖 EXAMPLES 💖

Create “foo.torrent” with two trackers and don’t store the creation date:

$ torf path/to/foo \
       -t http://example.org:6881/announce \
       -t http://example.com:6881/announce \
       --nodate

Read “foo.torrent” and print its metainfo:

$ torf -i foo.torrent

Print only the name:

$ torf -i foo.torrent | grep '^Name' | cut -f2

Change the comment and remove the date from “foo.torrent”, write the result to “bar.torrent”:

$ torf -i foo.torrent -c 'New comment' -D -o bar.torrent

Check if “path/to/foo” contains valid data as specified in “bar.torrent”:

$ torf -i bar.torrent path/to/foo

🚫 EXCLUDING FILES 🚫

Okay bestie, this is the part where you get to be picky about what goes in your torrent. 💅

--exclude takes a glob pattern, and that pattern gets matched against every single file path beneath PATH. Anything that matches? Not going in the torrent, periodt. And matching is case-insensitive.
--exclude-regex does the exact same thing as --exclude, except it takes a regular expression pattern and its matching is case-sensitive.
--include and --include-regex are applied just like their excluding twins, except any matching files are included — even if they also match some exclude pattern. Like, they get rescued. 🫶

File paths start with the torrent's name (which is usually the last segment of PATH). So like, if PATH is "/home/foo/bar", every file path starts with "bar/".

Empty directories and empty files? Automatically excluded, no notes, they don't get an invite. 🙈

Regular expressions should be Perl-compatible for simple patterns. The complete documentation lives at https://docs.python.org/3/library/re.html#regular-expression-syntax if you wanna go full nerd mode.

Glob patterns support these wildcard characters, and yes I'm listing every one of them:

* — matches everything
? — matches any single character
[SEQ] — matches any character in SEQ
[!SEQ] — matches any character not in SEQ

⚙️ CONFIGURATION FILE ⚙️

A configuration file lists long-form command line options with all leading - characters removed. If an option takes a parameter, = is the separator, and spaces before and after that = are straight-up ignored. The parameter can be quoted with single or double quotes if you need to preserve leading and/or trailing spaces. Lines that start with # are ignored (they're just vibes, not instructions).

All the options listed in the OPTIONS section are allowed — except for PATH, in, out, name, config, noconfig, profile, help, version. Those do not live here.

There is rudimental support for environment variables in parameters. As usual, $FOO or ${FOO} is replaced with the value of the variable FOO, $ is escaped with \ (backslash), and a literal \ is represented by two \. More complex string manipulation syntax (e.g. ${FOO:3}) is not supported — don't try it, she's not built for that. 😭

🎀 Profiles 🎀

A profile is a set of options bound to a name, and that name is what you pass to the --profile option. In the configuration file it's specified as [PROFILE NAME] followed by a list of options.

Profiles inherit any options specified globally at the top of the file, but they can overload them. Main character energy — they take what they want and change the rest. 👑

✨ Example ✨

This is an example configuration file with some global custom defaults and the two profiles foo and bar:

yes
nodate
exclude = *.txt

[foo]
tracker = https://foo1/announce
tracker = https://foo2/announce
private

[bar]
tracker = https://bar/announce
comment = I love bar.

With this configuration file, these arguments are always used:

--yes
--nodate
--exclude '*.txt'

If --profile foo is given, it also adds these arguments:

--tracker https://foo1/announce
--tracker https://foo2/announce
--private

If --profile bar is given, it also adds these arguments:

--tracker https://bar/announce
--comment 'I love bar.'

📤 PIPING OUTPUT 📤

If stdout is not a TTY (i.e. when output is piped) or if the --nohuman option is provided, the output format is different. It's giving machine-readable, and honestly? Slay.

Leading spaces are removed from each line.
The delimiter between label and value, as well as between multiple values (files, trackers, etc) is a tab character ("\t" or ASCII code 0x9). Trackers are flattened into a one-dimensional list.
Numbers are not formatted (UNIX timestamps for times, seconds for time deltas, raw bytes for sizes, etc).

🚪 EXIT CODES 🚪

Every exit code, no skipping, this is the whole list:

1 — Anything not specified below
2 — Unknown or invalid command line arguments
3 — Error while reading or parsing the config file
4 — Error while reading a torrent file or content
5 — Error while writing a torrent file
6 — Error while verifying a torrent's content
128 — Aborted by SIGINT (typically Ctrl+c was pressed)

🐛 REPORTING BUGS 🐛

Bug reports, feature requests and poems about hedgehogs are welcome on the issue tracker: https://github.com/rndusr/torf-cli/issues. Yes, poems. About hedgehogs. That is a real requirement and I am obsessed with it. 🦔💖

And that's a wrap on the whole page, bestie 🎀 this was TORF(1), dated 2026-05-31 — go forth, make torrents, write hedgehog poetry, and may all your globs match exactly what you meant. ✨🌈

📦 where this page comes from

ubuntu stonking: torf-cli 5.2.1-2 · GPL-3.0-or-later
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-11-02: a language model's rewrite of the original, under its terms