command line tool to keep track of tv shows and episodes

View project onGitHub


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.



  • Gather show information such as dates, names, etc from several sources:,
  • Track only the shows you watch by editing a configuration file
  • Track the status of episodes: new ➙ adquired ➙ 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 composed of three subsections 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 subsection source defines which api use to query episodes information, at the moment tvcmd supports: tvrage and thetvdb.

The second subsections 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, attackontitan, steinsgate, marvelsagentsofshield, theofficeus, cosmosaspacetime_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 can be run in either command mode:

$ tvcmd -e "ls friends.s0*"

or shell mode:

$ tvcmd
tvcmd> ls friends.s0*

Real Case Execution

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

Being 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 the 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, steinsgate.s01e10 or to select many: friends.s01e0* scrubs.*, steinsgate.s0*.

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

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

tvcmd> adquire 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.