timecard-rs

This is a program I make whenever I want to learn the intricacies of a language. I've done this before in Python, Kotlin/JVM, Kotlin/Native, and Kotlin/JS, now it's in Rust. However, it is also meant to be useful to myself, so maybe you can find some use in it, too.

timecard is a library that makes it easy to build applications that keep track of time, such as timecard-cli.

• timecard-rs
  • Install
  • Usage
    • Clocking In & Out
    • Undo
    • Log
  • Configuration
    • Duration Format

Install

Install the terminal application with Cargo:

$ cargo install timecard-cli
$ timecard
No log for today

Add the library to your project with Cargo:

$ cargo add timecard

Ensure Cargo binaries are in your path by adding this to your ~/.bashrc:

export PATH="$PATH:$HOME/.cargo/bin"

Then restart your terminal or run source ~/.bashrc.

Usage

Clocking In & Out

You start time entries by clocking in, and finish them by clocking out. You can only clock in/out at the current time, or at a time in the past.

$ timecard in 08:35
Clocked IN at 08:35 AM
$ timecard out 1hr  # current time is 11:15
Clocked OUT at 10:15 AM

A variety of time formats are accepted, including, but not limited to:

• An integer, representing minutes in the past. (e.g. timecard out 5 will clock out 5 minutes ago)
• An RFC 3339 datetime that is in the past, such as 2026-03-08T11:15
• An intuitive humantime string representing a duration in the past, such as 1hr7min or 10minutes.
• A human-readable time that is earlier today, e.g. 15:37, 3:37:53 PM, 3PM
• A human-readable datetime that is in the past, e.g. 20260308T3PM

Undo

You can remove the last time log by running the undo command:

$ timecard undo
Successfully removed last entry.
Entries for 2026-03-08:
IN: 08:35 AM

Log

You can see a log of all your time entries for the day:

$ timecard log
Entries for today:
IN: 08:35 AM    OUT: 11:15 AM

You can see other days by providing a date, similar to the formats used for clocking in or out:

# Assuming today is 2026-03-08
$ timecard log 1
Entries for 2026-03-07:
IN: 08:40 AM    OUT: 12:07 PM
IN: 01:02 PM    OUT: 04:59 PM
$ timecard log 2days
No entries exist for 2026-03-06
$ timecard log 2026-03-01
Entries for 2026-03-01:
IN: 08:27 AM    OUT: 12:31 PM
IN: 01:37 PM    OUT: 05:02 PM

You can also see logs for a date range by providing the --from-date and --to-date options:

# Assuming today is 2026-03-08
$ timecard log --from-date 2026-03-07
Entries from 2026-03-07 to today:
IN: 2026-03-07 08:40 AM    OUT: 2026-03-07 12:07 PM
IN: 2026-03-07 01:02 PM    OUT: 2026-03-07 04:59 PM
IN: 2026-03-08 08:35 AM    OUT: 2026-03-08 11:15 AM
$ timecard log --to-date 2026-03-02
Entries from forever ago to 2026-03-02:
IN: 2026-03-01 08:27 AM    OUT: 2026-03-01 12:31 PM
IN: 2026-03-01 01:37 PM    OUT: 2026-03-01 05:02 PM
$ timecard log --from-date 2026-03-01 --to-date 2026-03-07
Entries from 2026-03-01 to 2026-03-07:
IN: 2026-03-01 08:27 AM    OUT: 2026-03-01 12:31 PM
IN: 2026-03-01 01:37 PM    OUT: 2026-03-01 05:02 PM
IN: 2026-03-07 08:40 AM    OUT: 2026-03-07 12:07 PM
IN: 2026-03-07 01:02 PM    OUT: 2026-03-07 04:59 PM

You can even combine these two methods to get the log for the date range provided, as well for a single day's log.

Using the --all flag will ignore everything and just spit all of your time entries into the console.

You can also use the --csv flag to output in CSV format. You can then pipe the output to a file to save it.

$ timecard log --csv > log.csv
$ cat log.csv
Start,End
2026-03-08 08:35 AM,2026-03-08 11:15 AM

If you pass an argument to the --csv flag, it will be used as the column separator:

$ timecard log --csv ";"
Start;End
2026-03-08 08:35 AM;2026-03-08 11:15 AM

Configuration

The config file location depends on what OS you're on:

The default file that is generated is self-explanatory. If you don't have any comments explaining how the config works, either delete or rename the file, then just run timecard. The newly generated file will contain comments explaining each field.

Duration Format

The duration_fmt config field uses a custom format defined below: