A Powerful Node.JS CLI Time Tracker ⏱️🚀

After using Ruby's timetrap (sadly no longer maintained) for many years, I realized there was no equivalent in the Node.JS ecosystem, so I decided to build one.

Introducing track-time-cli, a utility for keeping track of the time you spend on your projects and (eventually) viewing useful metrics and statistics on your performance.

It is a Node.JS CLI app written in TypeScript supporting natural language input for task start/end times (i.e., 1 hour ago or twelve minutes ago.)

Most commands offer arguments for altering the display of durations in natural language (i.e., 33:00 as 33 minutes) or times as relative (i.e., 12/24/2023, 6:51:39 PM as 26 minutes ago.)

Getting Started

Install it with npm i -g track-time-cli; the entry point/command is tt, and by default, when called with no arguments, it shows the currently active timesheet entry.

All data is stored in ~/.track-time-cli/db.json, a folder that you can turn into a git repository for backing up your data as the number of entries grows.

Run tt --help to view the list of supported commands:

track-time-cli now

Display all active time sheet entries

Commands:
  track-time-cli in <description..>    Check in to a time sheet     [aliases: i]
  track-time-cli now                   Display all active time sheet entries
                                                                       [default]
  track-time-cli out                   Check out of the currently active time
                                       sheet entry                  [aliases: o]
  track-time-cli week [sheets..]       Display a summary of activity for the
                                       past week                    [aliases: w]
  track-time-cli list [sheets..]       List all time sheet entries  [aliases: l]
  track-time-cli edit [description..]  View, modify, or delete a time sheet
                                       entry                        [aliases: e]
  track-time-cli today [sheets..]      Display a summary of activity for today
                                                                    [aliases: t]
  track-time-cli sheet [name]          Switch to or delete a sheet by name
                                                                    [aliases: s]
  track-time-cli sheets                List all sheets             [aliases: ss]
  track-time-cli resume                Resume the last active entry [aliases: r]
  track-time-cli yesterday [sheets..]  Display a summary of activity for
                                       yesterday                    [aliases: y]
  track-time-cli breakdown [sheets..]  Display total durations per day for one
                                       or more sheets               [aliases: b]

Options:
      --version   Show version number                                  [boolean]
  -h, --humanize  Print the total duration in human-readable format    [boolean]
      --help      Show help                                            [boolean]

Examples:
  tt in --at "20 minutes ago" fixing a bug  Check in at a custom time
  tt out --at "5 minutes ago"               Check out at a custom time
  tt list --today --all                     View all entries from today
  tt b                                      Show a breakdown of your activity
  tt today --all                            View activity for the current day

A Note on Command Aliases

Almost all commands have short aliases, which I will use exclusively in this post. For example, tt yesterday is the same as tt y. Check the output of tt --help for information on available aliases.

Timesheets 📚

A task in track-time-cli is known as a timesheet entry and belongs to a timesheet. Timesheets can represent any group or category of tasks but are primarily meant to represent individual projects.

To view the list of timesheets, run tt sheets or the shorter tt ss.

Managing Timesheets

To create a new timesheet, or switch to an existing one, run tt s [name]. Running tt s with no name will display the currently active timesheet.

When the DB is initialized, a timesheet named main is created and set as active by default.

To delete a timesheet, run tt s --delete [timesheet name].

Tracking Tasks ⏱️

To start, or check in to a timesheet entry, run tt in [description]. If you started working earlier and forgot to check in, you can do so retroactively with the --at argument, i.e., tt in --at '10 minutes ago' developing feature X would create a timesheet entry that started 10 minutes ago with a description of developing feature X.

If you want to start a new entry with the same description as the previous one, tt resume (or tt r) exists, which will check in with the same description as the most recently active entry on the sheet.

Similarly, to end or check out of a task, run tt out optionally, providing the --at argument (i.e., tt out --at '5 minutes ago) if you stopped working and forgot to check out of your time sheet.

All of the following are valid in/out time inputs:

• '19 minutes ago'
• 'forty five minutes ago'
• '1 hour and 20 minutes ago'
• '1 day, three hours, and 2 minutes ago'

Viewing Tasks 📃

To view historical and active tasks, there is the list command, tt l, which will print out a list of tasks. It is fairly powerful; here is the output of tt l --help:

track-time-cli list [sheets..]

List all time sheet entries

Options:
      --version          Show version number                           [boolean]
  -r, --ago, --relative  Print dates as relative time (e.g. 5 minutes ago)
                                                                       [boolean]
  -h, --humanize         Print the total duration in human-readable format
                                                                       [boolean]
  -s, --since            Only list entries since the specified date     [string]
  -t, --today            Show results for today                        [boolean]
      --all-sheets       Show results for all sheets                   [boolean]
  -a, --all              Show all sheet entries                        [boolean]
  -y, --yesterday        Show results from yesterday                   [boolean]
  -c, --concise          Exclude start and end dates from output, showing
                         duration only                                 [boolean]
      --help             Show help                                     [boolean]
      --sheets           Show results for the specified sheets
  [array] [choices: "track-time-cli", "cst", "personal", "time-speak", "coding",
    "gaming", "blog", "node-ts-lib-template", "track-time-cli-ui", "to-numbers"]

It defaults to showing data from the last 24 hours, a setting which can be modified with the --since argument. For example, for my own track-time-cli timesheet, running tt l track-time-cli --since '7 days ago' results in the following output:

The list command supports many options for formatting the output, such as displaying durations in natural language or times/dates as relative. For example, the output of tt l --all-sheets --since '2 days ago' -r -h for me is:

Convenience Commands

There are three commands to list specific spans of time, which I think one would often use:

• tt today (tt t)
• tt yesterday (tt y)
• tt week (tt w)

Their output and arguments are similar to tt l; here is the output of tt week -t -h for me:

Future Plans 🚀

A breakdown command currently shows the total time spent per hour of the day or per weekday for entries sourced from multiple time sheets.

This is WIP and will be improved in the future; the plan is to use the stored data to tell when you are most productive and view other useful derivative data.

I haven't covered every feature in this post, so feel free to check it out yourself!

For more information, check out the README.md and the GitHub repo itself.

Any feedback, comments, or suggestions would be more than welcome!

Happy holidays, everyone! 🎅🎄