A Powerful Node.JS CLI Time Tracker ⏱️🚀
Tags: node, typescript, productivity, javascript
Published: 2023-12-24 19:52:57

After using Ruby's [**timetrap**](https://github.com/samg/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**](https://github.com/f3rno64/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.

![Output of `'tt l -c'`](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/uswwmgkuktuclg9xl1y0.png)

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`.

![Output of running `'tt ss'`](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/8kcimucb1ntgemr7eh4h.png)

---

### 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:

![Output of running `tt l track-time-cli --since '7 days ago'`](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/2hz4v6sana36y6415d9w.png)

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:

![Output of running `tt l --all-sheets --since '2 days ago' -r -h`](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/93daz54xepdqpkldma65.png)

---

#### 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:

![Output of `'tt week -t -h'`](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/8rkqhy9htpa3zoeqgi0e.png)

---

## 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**](https://github.com/f3rno64/track-time-cli/blob/main/README.md) and the [**GitHub repo itself**](https://github.com/f3rno64/track-time-cli).

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

Happy holidays, everyone! 🎅🎄