A no-frills time tracking toolkit for command line nerds
A no-frills time tracking toolkit for command line nerds
hours is a no-frills time tracking toolkit for the command line.
It's designed for users who want basic time tracking for their tasks/projects
right in the terminal. With a simple and minimalistic UI, almost everything in
hours can be achieved with one or two keypresses. It can also generate
plaintext reports, summary statistics, and logs based on time tracked.
For a while, I've been wanting to keep track of time I spend on side projects and other non-day-job activities. I also wanted to be able to generate plain text reports to get an overview of time allocation. All of this needed to be done via a fast command line tool that prioritised ease of use over fancy-but-ultimately-not-so-useful features. I couldn't find a tool that precisely fit these needs, so I decided to build one for myself.
Download a pre-built binary from the latest release. See Verifying release artifacts for instructions on verifying your download.
You can also install from source using the go toolchain:
go install github.com/dhth/hours@latestNewbie tip: If you want to see how
hoursworks without having to track time, you can have it generate dummy data for you. See here for more details.
Open the TUI by simply running hours. The TUI lets you do the following:
Besides a TUI, hours also offers reports, statistics, and logs based on the
time tracking you do. These can be viewed using the subcommands report,
stats, and log respectively.
hours report [flags] [arg]Output a report based on task log entries.
Reports show time spent on tasks per day in the time period you specify. These
can also be aggregated (using -a) to consolidate all task entries and show the
cumulative time spent on each task per day.
Accepts an argument, which can be one of the following:
today for today's report
yest for yesterday's report
3d for a report on the last 3 days (default)
week for a report on the current week
date for a report for a specific date (eg. "2024/06/08")
range for a report for a date range (eg. "2024/06/08...2024/06/12", "2024/06/08...today", "2024/06/08..."; shouldn't be greater than 7 days)Note: If a task log continues past midnight in your local timezone, it will be reported on the day it ends.
Reports can also be viewed via an interactive interface using the
--interactive/-i flag.
hours log [flags] [arg]Output task log entries.
Accepts an argument, which can be one of the following:
today for log entries from today (default)
yest for log entries from yesterday
3d for log entries from the last 3 days
week for log entries from the current week
date for log entries from a specific date (eg. "2024/06/08")
range for log entries for a date range (eg. "2024/06/08...2024/06/12", "2024/06/08...today", "2024/06/08...")Note: If a task log continues past midnight in your local timezone, it'll appear in the log for the day it ends.
Logs can also be viewed via an interactive interface using the
--interactive/-i flag.
hours stats [flag] [arg]Output statistics for tracked time.
Accepts an argument, which can be one of the following:
today show stats for today
yest show stats for yesterday
3d show stats for the last 3 days (default)
week show stats for the current week
date show stats for a specific date (eg. "2024/06/08")
range show stats for a date range (eg. "2024/06/08...2024/06/12", "2024/06/08...today", "2024/06/08...")
all show stats for all log entriesNote: If a task log continues past midnight in your local timezone, it'll be considered in the stats for the day it ends.
Stats can also be viewed via an interactive interface using the
--interactive/-i flag.
hours can show you the task being actively tracked using the active
subcommand. This subcommand supports the following placeholders using the
--template/-t flag:
{{task}}: for the task summary
{{time}}: for the time spent so far on the active log entryTip: This can be used to display the active task in tmux's (or similar terminal multiplexers) status line using:
set -g status-right "#(hours active -t ' {{task}} ({{time}}) ')".You can have hours generate dummy data for you, so you can play around with
it, and see if its approach of showing reports/logs/stats works for you. You can
do so using the gen subcommand.
hours gen --dbpath=/var/tmp/throwaway.dbhours supports custom themes for its user interface (for the TUI and the
output of the logs, report, and stats commands. New themes can be added
using hours themes add, which will create a JSON file in hours' config
directory. You can then tweak this file as per your liking.
A sample theme config looks like the following. Colors codes can be provided in ANSI 16, ANSI 256, or HEX formats. You can choose to provide only the attributes you want to change.
…You can view configured themes using hours themes list.
Running hours with the --theme flag will load up that theme.
Alternatively, you can set $HOURS_THEME to the theme name so you don't have to
pass the flag every time.
Here's a sampling of custom themes in action.
| Theme | Preview |
|---|---|
| Solarized Dark | |
| Monokai | |
| Nord | |
| Dracula | |
| Gruvbox | |
| Catppuccin | |
| Tokyonight |
hours has 6 views:
| Shortcut | Action |
|---|---|
1 |
Switch to Tasks List View |
2 |
Switch to Task Logs List View |
3 |
Switch to Inactive Tasks List View |
| `` | Go to next view/form entry |
| `` | Go to previous view/form entry |
q/`` |
Go back or quit |
| `` | Quit immediately |
? |
Show help view |
| Shortcut | Action |
|---|---|
k/`` |
Move cursor up |
j/`` |
Move cursor down |
h/`` |
Go to previous page |
l/`` |
Go to next page |
| `` | Refresh list |
| Shortcut | Action |
|---|---|
a |
Add a task |
u |
Update task details |
s |
Start/stop recording time on a task; stopping will open up the "Task Log Entry View" |
S |
Quick switch recording; will save a task log entry for the currently active task, and start recording time for another |
f |
Finish the currently active task log without comment |
| `` | Edit the currently active task log/Add a new manual task log entry |
| `` | Discard currently active recording |
| `` | Go to currently tracked item |
| `` | Deactivate task |
Note: ~ at the end of a task log comment indicates that it has more lines that are not visible in the list view
| Shortcut | Action |
|---|---|
d |
Show task log details |
``/u |
Update task log entry |
| `` | Delete task log entry |
| Shortcut | Action |
|---|---|
h |
Go to previous entry |
l |
Go to next entry |
| Shortcut | Action |
|---|---|
| `` | Activate task |
| Shortcut | Action |
|---|---|
enter/`` |
Save entered details for the task log |
k |
Move timestamp backwards by one minute |
j |
Move timestamp forwards by one minute |
K |
Move timestamp backwards by five minutes |
J |
Move timestamp forwards by five minutes |
h |
Move timestamp backwards by a day |
l |
Move timestamp forwards by a day |
Each release includes checksums for all artifacts. The checksum file is signed using cosign.
Replace x.y.z below with the release version you want to verify.
Download the following files from the release:
hours_x.y.z_checksums.txthours_x.y.z_checksums.txt.pemhours_x.y.z_checksums.txt.sigVerify the checksum file's signature:
cosign verify-blob hours_x.y.z_checksums.txt \
--certificate hours_x.y.z_checksums.txt.pem \
--signature hours_x.y.z_checksums.txt.sig \
--certificate-identity-regexp 'https://github\.com/dhth/hours/\.github/workflows/.+' \
--certificate-oidc-issuer "https://token.actions.githubusercontent.com"Download the archive for your platform and validate its checksum. For example, for Linux x86-64:
curl -sSLO https://github.com/dhth/hours/releases/download/vx.y.z/hours_x.y.z_linux_amd64.tar.gz
sha256sum --ignore-missing -c hours_x.y.z_checksums.txtOnce both checks pass, extract the archive:
tar -xzf hours_x.y.z_linux_amd64.tar.gz
./hours -h
# profit!No open issues yet, or sync has not completed.