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(ortt 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! 🎅🎄
Top comments (2)
This looks great! What was you motivation for building this?
I used to use timetrap for years to log my time spent working to get a sense of my daily average output. I decided to build something similar since nothing like it existed in the Node.JS world and timetrap is no longer maintained. It was a nice challenge, specifically adding logic to parse natural language input for start/end dates when checking in/out.
Plus, I love CLI tools in general 💖