Skip to content
tvcmd is a command line interface (CLI) to keep track of tv shows and episodes. It is similar to websites such as or but for the command line, allowing greater flexibility like automatic torrent urls.
Branch: master
Clone or download

Latest commit

Fetching latest commit…
Cannot retrieve the latest commit at this time.


Type Name Latest commit message Commit time
Failed to load latest commit information.


tvcmd is a command line interface (CLI) to keep track of tv shows and episodes. It is similar to websites such as or but for the command line, allowing greater flexibility like printing torrent urls.



  • Gather show information such as dates, names, etc from several sources:,
  • Track the shows you watch by editing a configuration file
  • Track episodes status: new ➙ acquired ➙ seen
  • Print each show in whichever format you like, handy for generating torrent links


The main configuration file is located at .config/tvcmd/main.cfg, it is an ini style file that only has three fields inside a general section.


source = tvrage
shows = friends, scrubs, firefly, attack_on_titan, the_ricky_gervais_show
formats =${show+}+s${season}e${episode},${show+}+s${season}e${episode}.html?quality=1&order=1

The first field source defines which api use to query episodes information, at the moment tvcmd supports: tvrage and thetvdb.

The second field shows is probably the most important as it is the list of shows to follow. The list is separated by comma and the show names are lower case letters, numbers and/or the underscore symbol, ex: friends, attack_on_titan, steins_gate, marvels_agents_of_s_h_i_e_l_d_, the_office_us, cosmos_a_spacetime_odyssey, be careful though as some shows have different names depending on the source. You can find out the exact name of a show by typing the command search followed by a pattern, ex: search the offi

Finally, the optional subsection formats contains a list of strings, useful for automatic torrent url generation. The following expressions are automatically replaced for each episode:

  • ${show}: full show name
  • ${show+}: same as above but with the + symbol instead of spaces
  • ${season}: season number (2 decimals)
  • ${episode}: episode number (2 decimals)


tvcmd runs on either command mode:

$ tvcmd -e "ls friends.s0*"

or shell mode:

$ tvcmd
tvcmd> ls friends.s0*

Real Case Example

Let's say we enjoy watching these shows: Friends, Scrubs and Attack On Titan.

Begin by creating a basic configuration file:

source = thetvdb
shows = friends, scrubs, attack_on_titan
formats =${show+}+s${season}e${episode}.html?quality=1&order=1

Run tvcmd in shell mode and execute the following secuence of commands:

tvcmd> update
tvcmd> ls
tvcmd> format

Here update will query the source with your show list from your config file, ls will display the gathered episodes and format will print urls to download torrent files from, format can also be executed using the -f option:

$ tvcmd -f

Allowing greater flexibility:

$ firefox $(tvcmd -f "friends.s01*" |grep

Both format and ls receive a pattern to identify episodes, this pattern is {showname}.s{season#}e{episode#}, ex: friends.s01e01, scrubs.s03e21, steins_gate.s01e10. Additionally you can use wildcards for easier selections: friends.s01e0* scrubs., steins_gate.s0.

By default every new episode is marked as new, once you download an episode you can marked them as acquired with the acquire command and once you see it you can mark it as seen with the see command. Episodes always follow this secuence: new ➙ acquired ➙ seen.

Going back to our example once we have downloaded the episodes we can mark them as acquired so they won't show up again with format:

tvcmd> acquire friends.s01*
tvcmd> format

Or as seen and they won't show up again with ls:

tvcmd> see friends.s01*
tvcmd> ls

For further information run tvcmd -e help or in shell mode help and COMMAND -h.

You can’t perform that action at this time.