mtracker

mtracker is a simple cli tool for Linux that lets you keep track of watched movies and series.

Designed to work well with standard Linux command line tools like grep.
Flat file system: All data is saved in a human-readable text file.
No built-in cloud synchronization. Of course, you can set up some kind of synchronization yourself if you wish to.
No data is fetched from the internet. You enter all the information that's useful to you manually.

Installation

If you have Rust installed, you can simply use cargo:

cargo install mtracker

Otherwise just download the latest release and put it somewhere within your PATH variable, e.g.: /usr/local/bin

sudo curl -o /usr/local/bin/mtracker https://github.com/r-unruh/mtracker/releases/latest/download/mtracker

Don't forget to make the file executable:

sudo chmod +x /usr/local/bin/mtracker

More user-friendly install options will probably be added at some point.

Tutorial

Let's assume your friend Max tells you about a fun horror movie. This is how you add it to your watchlist:

mtracker add "Pearl (2022)" --tag=watchlist --note="Recommended by Max"

After watching the movie you decide to rate it a 8/10:

mtracker rate "Pearl (2022)" 8

This command assumes that you have now watched the item and removes it from the watchlist automatically.

You can rate movies you already know directly without having to add them first:

mtracker rate "Session 9 (2001)" 10
mtracker rate "In Fabric (2018)" 4

Now lets see what we have so far by listing all items:

mtracker ls

Which returns this list, sorted by rating:

++++++++++ Session 9 (2001)
++++++++-- Pearl (2022)
+++------- In Fabric (2018)

This should cover the basics. Type mtracker help [subcommand] to see all options.

[!NOTE] Commands are not yet stable and may change in future versions. Make sure to backup your database on a regular basis.

Database

The database is just a plain text file that you can edit by hand. It looks like this:

Forrest Gump
year: 1994
rating: 9
tags: drama, comedy
last_seen: 2020-12-31

Bodies Bodies Bodies
year: 2022
tags: watchlist
note: recommended by Max

Whiplash
rating: 10

On Linux, the database file is automatically created and stored in ~/.local/share/mtracker/db.txt. If any relevant XDG environment variables (e.g., XDG_DATA_HOME) are set, they will be respected, and the file will be stored according to the XDG Base Directory Specification.

Features

Ratings

You can rate movies on a scale of your choice. mtracker doesn't force a rating system. The highest rated item in your database determines the scale: If the highest rated movie is a 7, then all the ratings go from 0 to 7. Of course, you don't have to rate anything at all.

Here are a few options:

Rating Scale	Explanation
1 to 10	You can rate the way most movie websites do.
1 to 5	In case you prefer fewer options, this might be better. There are no decimal numbers though.
0 to 1	Binary mode, or: Like/Dislike. Most simple! Ratings don't have to start at 1.
0 to 2	If you often find yourself neither liking nor disliking movies, you may need a third option. This is the system I'm using: 2 = Like 1 = Okayish 0 = Dislike

Command examples

Command	Action
`mtracker ls`	List all items
`mtracker ls --tag=horror,comedy`	List items that are tagged both horror and comedy
`mtracker ls --year=">=2020"`	List items that were released in and after 2020
`mtracker add "Aliens (1986)" --tag=watchlist,horror`	Add new item with tags OR add tags to an existing item
`mtracker rate "Aliens (1986)" 5`	Rate item a 5 (and remove from watchlist)
`mtracker ls \\| grep -i aliens`	Use grep to find entries
`mtracker ls \\| grep +++`	Use grep to search for items with a rating of at least 3

r-unruh / mtracker

readme