How to track your time in the terminal using the Klog CLI

As a .NET developer working as a software consultant, I’m keenly aware of the need to track my billable hours in an accurate fashion. It’s easy enough to keep track of the overall number of hours in a given week without software, but oftentimes, my hours need to be categorized by project or client which quickly becomes unwieldy.

In the past, I’ve tried a variety of apps and services on my phone or laptop, but I generally struggled to integrate them into my daily workflow. When I’m in the flow and switching between multiple projects in a day, it’s difficult to remember to check my phone or log into yet another app to log my entries. I needed something sticky that would linger at the back of my mind throughout my day without being overly distracting.

Naturally, my attention turned to the terminal. It’s the one tool that I’m guaranteed to use countless times throughout the day, regardless of the project, client, or laptop that I’m working on. In addition, I wanted something flexible that I could use to customize my shell prompt to display my current project status so I wouldn’t forget to keep it up to date.

This led me on a circuitous journey of exploration into the wonderful world that is terminal-based applications which ultimately culminated with a humble tool called Klog created by Jan Heuermann.

Klog is a text-based CLI time tracker. After evaluating a number of options (honorable mention to Watson), Klog checked all the boxes for me. It utilizes a text-based format that is human-readable and easy to edit. This also makes it relatively trivial to back up my entries and sync them across devices. Finally, it provided a json export option making it straightforward to write scripts, generate reports, and customize my shell prompt.

You can find all of the relevant installation instructions here. For reference, I’m using PowerShell in the following examples since I spend most of my time on Windows as a .NET developer, but they should be easily translated to other shells.

Once I have it installed, I like to start by creating my primary time entry file and storing it in a safe location like a GitHub repository or a OneDrive folder.

New-Item ~/SafeFolder/hours.klg

Next, I like to set a default bookmark to this file, so I don’t have to specify it every time I want to edit the file or append new entries.

klog bookmarks set ~/SafeFolder/hours.klg

On Windows, by default, klog launches the Notepad application to edit your timesheet file, which is fine, but I prefer to keep all of my work inside the terminal wherever possible. Fortunately, Klog provides an environment variable to modify this behavior. To set this, I need to edit my configuration file. I can never remember where the config folder is, but thankfully, running the following command provides it for me.

klog info config-folder

After navigating to the config folder listed, I can create the config.ini file and bootstrap the initial configuration using another klog command.

klog config

This outputs a valid configuration example for Klog that you can copy into the config.ini file. It also provides some additional comments to help you get started. In our case, the relevant setting is editor, which you can set to the text editor of your choice like vim or emacs. In my case, I’ve set it to Micro because I’m basic.😬

editor = micro

Now, when you edit your time entries with klog, it’ll launch with the editor of your choice!

klog edit

On any given day, this is my overall workflow for keeping track of all the different projects I’m working on. First, I start by creating the initial entry for the day and setting the number of hours I intend to work.

klog create --should 8h

Next, I start my first entry of the day.

klog start -r 30m -s "#projectA"

The ‘-r’ flag rounds my entry to the nearest thirty minutes, and the ‘-s’ flag sets the summary text for this entry. In my case, I’ve added a tag to signify the project I’m currently working on. Klog can filter my time entries based on this flag, which is great for generating reports or automating timesheets.

I can also stop the time entry using

klog stop -r 30m

Or I can switch to a new project utilizing

klog switch -r 30m -s "#projectB"

From there, I can generate reports in a variety of ways:

klog report #generate aggregated calendar report

klog tags #print total time logged by tag

klog today #print the total hours worked today

Make sure to check the available options in all of these commands using ‘-h’. Klog provides an incredible amount of flags to help you filter and aggregate entries in a variety of ways.

Finally, it also provides the option to export your entries as json.

klog json

Here is an example of the output.

{
  "records": [
    {
      "date": "2024-07-16",
      "summary": "",
      "total": "8h",
      "total_mins": 480,
      "should_total": "8h!",
      "should_total_mins": 480,
      "diff": "0m",
      "diff_mins": 0,
      "tags": [],
      "entries": [
        {
          "type": "range",
          "summary": "#projectA",
          "tags": ["#projecta"],
          "total": "8h",
          "total_mins": 480,
          "start": "7:00",
          "start_mins": 420,
          "end": "15:00",
          "end_mins": 900
        }
      ]
    }
  ],
  "errors": null
}

From here, I can write scripts to utilize the json for any number of tasks like keeping track of the expenditure for a particular project or automating time entries into an Excel spreadsheet. Using the json output, I can also customize my shell prompt to display the current project and hours of work remaining for the day. It’s invaluable for getting the tool to stick in my workflow and making sure that I remember to update my project entries as I’m working.

There are plenty of other commands and features to explore in Klog, but these are the ones that I use the most in my day-to-day. For more information, you can always check out the documentation. If you find it useful, make sure to star the repo on GitHub, it definitely deserves more attention!