21 releases (13 breaking)

0.17.0 Jan 14, 2024
0.16.0 Mar 16, 2023
0.15.0 Jan 18, 2023
0.13.1 Oct 9, 2022
0.4.1 Mar 27, 2020

#1089 in Command line utilities

27 downloads per month

MIT license

1.5K SLoC


Build Crates.io AUR

Small utility to store and calculate the time spent at work.

⚠️ v0.10.0 introduces a new storage file format. Run stempel migrate to update your json database to the new format.


Example for managing one day:

# First of, configure some settings
stempel configure
# start working now
stempel start
# start a break five minutes ago
stempel break start --offset 5m-
# optional: break can be canceled:
stempel cancel
# finish break in one hour (only if not canceled above)
stempel break stop --offset 1h+
# Finish the day
stempel stop
# Alternatively, you can specify the time point to stop as a time in 24h format
stempel stop --time 17:38

For a detailed reference, run stempel help or stempel SUBCOMMAND --help. Available subcommands are:

  • cancels the last break, start or does nothing if no break or start in the storage,
  • break: use start or stop as subcommand to handle breaks,
  • migrate: migrate storage file from old (before 0.10.0) to new format (since v0.10.0)
  • start: start a working period, aborts if you already started previously,
  • stats prints current statistics.
  • stop: checks if a start entry is in the storage file and calculates the working time, aborts if no start entry is found,
  • configure: set some defaults for stempel and save them alongside the database file. Currently available:
    • number of months printed by the statistic command
    • number of hours to work per day


Run stempel completions --shell <shell> to get a shell completion file, e.g. stempel completions --shell zsh for zsh. Source this file according to your specific shell.

source <(stempel completions --shell zsh)



This option allows to specify a positive or negative offset to the current time. In other words, giving the option --offset 10m+ means that the command is executed with the current time plus 10 minutes, 20s- stands for current time minus 20 seconds. The syntax allows [Xh][Xm][Xs](+-) where X can be any number and h|m|s refer to hours, minutes and seconds, respectively. Overridden by --timebelow.

Some examples:

  • 2h30m4s+: 2 hours, 30 minutes, 4 seconds from now
  • 1h90s-: 1 hour 90 seconds before now
  • 20m30s+: 20 minutes, 30 seconds from now
  • 60s-: one minute before now


This options allows to specify a time for the respective action. Use it if you want to start or stop at a certain time. The format is HH:MM in 24h where the date is set to the current day, e.g. 13:47 means today at 13h 47.


Specify a path to the storage file where all work entries are written to. The path defaults to $HOME/.config/stempel.json and is created on the first invocation of the start subcommand.


  • Statistics:
    • statistics of last two months grouped by weeks
    • allow printing only ranges of stats, e.g. months, years...
    • display long hours
  • Tracking: allow to specify start and stop time as cli arg
  • Tracking: cancel started work
  • Specify an offset from current time when starting or stopping
  • Add more possibilities to offset
  • Add configuration options




~282K SLoC