DEV Community

Cover image for A Powerful Node.JS CLI Time Tracker ⏱️🚀
Cris Mihalache
Cris Mihalache

Posted on • Originally published at datsusara.hashnode.dev

A Powerful Node.JS CLI Time Tracker ⏱️🚀

#node #cli #productivity #programming

Introducing super-time-tracker: A Node.js CLI Time Tracker (Rebuilt)

After using my own track-time-cli for a while, I found myself wanting more — more commands, more flexibility, and a cleaner experience overall. So I rebuilt it from the ground up, gave it a new name, and published it as super-time-tracker.

Introducing super-time-tracker, a Node.js CLI utility for tracking the time you spend on your projects, with natural language time input, tags, notes, and rich reporting commands.

It is a Node.js CLI app written in TypeScript. Like its predecessor, it supports natural language for task start and end times (e.g., 2 hours and 24 minutes ago or forty five minutes ago), and most commands accept flags to render durations in human-readable form or show times as relative.

Getting Started

Install it with your package manager of choice:

npm i -g super-time-tracker
Enter fullscreen mode Exit fullscreen mode

The entry point is stt. By default, running stt with no arguments shows the currently active time sheet entry.

All data is stored in ~/.super-time-tracker/db.json — a plain JSON file you can version-control in a git repo to back up your entries as they grow.

Run stt --help to view all supported commands.

A Note on Command Aliases

All commands have short aliases. For example, stt list is the same as stt l, and stt sheet is the same as stt s. I'll use the short forms throughout this post. Check stt --help for the full list.

Timesheets 📚

A task in super-time-tracker is a timesheet entry that belongs to a timesheet. Timesheets represent any grouping of tasks — typically a project or a client.

To view all timesheets, run stt ss. This command also accepts --today, --yesterday, --since <natural language time>, --filter <substring>, and --concise to narrow down the output.

Managing Timesheets

To create or switch to a timesheet, run stt s [name]. Running stt s with no name displays the currently active sheet. A default sheet named main is created on first run.

New in this version:

  • stt s --rename <new name> — rename the active sheet in place.
  • stt s <name> --delete — delete a sheet by name.

Tracking Tasks ⏱️

To check in to a new entry, run stt i <description>. If you started working earlier and forgot to check in, use --at:

stt i --at '2 hours and 24 minutes ago' crafting something
Enter fullscreen mode Exit fullscreen mode

You can also target a specific sheet with --sheet, attach tags with --tags, or add an opening note with --note:

stt i --sheet work --tags @frontend @bugfix fixing the modal
stt i --note 'starting with a plan' writing the architecture doc
Enter fullscreen mode Exit fullscreen mode

To end a task, run stt o, optionally with --at or --note:

stt o --at '5 minutes ago'
stt o --note 'wrapped up, tests passing'
Enter fullscreen mode Exit fullscreen mode

Notes

A new addition in this version is the dedicated note command, which attaches a timestamped note to the active entry:

stt n pair with alice on the widget
Enter fullscreen mode Exit fullscreen mode

You can also attach notes to specific past entries:

stt n --sheet work --entry 32 --at '30 minutes ago' got unblocked
Enter fullscreen mode Exit fullscreen mode

Resuming Entries

stt r resumes (clones) the most recent entry as a fresh active entry. You can also resume a specific entry by ID, on a different sheet, or with overrides:

stt r --entry 32
stt r --at '10 minutes ago' --tags @foo updated description
Enter fullscreen mode Exit fullscreen mode

Editing Entries

The edit command got a significant upgrade. You can now rewrite an entry's start/end times, update its tags, or delete it by ID:

stt e --entry 32 --start '10am' --end '11:30am'
stt e --entry 32 --tags @new @tags
stt e --entry 32 --delete
Enter fullscreen mode Exit fullscreen mode

Viewing Tasks 📃

List

stt l lists entries from the past 24 hours. It accepts --since, --all, --all-sheets, --filter, --concise, and -r (relative timestamps). For example:

stt l --since '7 days ago' --all-sheets -r -h
Enter fullscreen mode Exit fullscreen mode

Convenience Commands

There are dedicated commands for common time windows:

  • stt t — entries from today
  • stt y — entries from yesterday
  • stt w — a week summary; supports --total for a per-day aggregate, plus --since, --all-sheets, and --filter

Breakdown

stt b displays total durations broken down by day, weekday, and hour — useful for spotting patterns in when you work most. It accepts --today, --yesterday, --since, --all-sheets, and --filter.

Useful Flags

Nearly every command supports:

  • -h — render durations in human-readable format (e.g., 1 hour, 36 minutes instead of 1:36:18)
  • -r — show times as relative (e.g., 3 hours ago instead of an absolute timestamp)

Example Workflow

Here's a typical day with super-time-tracker:

stt s work
stt i --at '2 hours and 24 minutes ago' crafting something
stt n pair with alice on the widget
stt o
stt l --since '4 hours ago'
stt t
stt w
Enter fullscreen mode Exit fullscreen mode

What's New vs. track-time-cli

If you used the old track-time-cli (tt), here's a quick summary of what changed:

  • Notes — new dedicated command for attaching timestamped notes to entries
  • Tags — first-class support on stt i, stt r, and stt e
  • Sheet management — rename and delete sheets directly from the CLI
  • resume upgrades — resume with a time override, tag override, or description override
  • edit upgrades — rewrite start/end times from natural language, update tag sets
  • breakdown — improved with weekday and hour-of-day breakdowns in addition to per-day totals
  • sheets — now supports --today, --yesterday, --since, and --filter
  • New command: stt (instead of tt)

I haven't covered every flag and option in this post — check out the README and the full stt --help output for the complete picture.

Any feedback, comments, or suggestions are very welcome. Happy tracking! ⏱️

Top comments (0)