rtimelogger 0.8.1

A simple cross-platform CLI tool to track working hours, lunch breaks, and calculate surplus time
Documentation

Build Status Latest Release codecov License: MIT

rTimelogger is a cross-platform command-line time tracking tool written in Rust. It tracks working time using IN / OUT events, supports multiple locations, lunch rules, working gaps, and computes expected exit time and daily surplus accurately.

๐Ÿš€ Whatโ€™s new in v0.8.0

Version 0.8.0 is the first stable release based on the new timeline engine.

โœ… Timeline engine (stable)

  • Unlimited IN / OUT pairs per day

  • Deterministic reconstruction: events โ†’ timeline โ†’ pairs

  • Correct handling of:

    • lunch breaks
    • working gaps
    • multi-position days

  • Legacy work_sessions logic fully retired

๐Ÿ”— Working gap support

Time between pairs can be explicitly controlled:

  • --work-gap โ†’ gap counts as working time
  • --no-work-gap โ†’ gap does not count as working time

Features:

  • Stored in the database

  • Editable retroactively

  • Fully reflected in:

    • worked time
    • expected exit
    • surplus

Visual indicators:

  • ๐Ÿ”— working gap
  • โœ‚๏ธ non-working gap

๐Ÿงฎ Accurate calculations

  • Worked time:

    • sum of all pairs
    • minus non-working gaps
    • plus working gaps only when marked

  • Expected exit:

    • based on first IN
    • configured minimum working time
    • lunch rules and lunch window

  • Surplus is correct in all multi-pair scenarios

๐Ÿง  Consistency improvements

  • OUT events inherit position from IN when --pos is omitted

  • Pair details show the actual position of each pair

  • Clean event listing:

    • no duplicated dates
    • aligned output

  • Unified CLI message system:

    • โ„น๏ธ info ยท โš ๏ธ warning ยท โŒ error ยท โœ… success

โœจ Features

  • Event-based time tracking (IN / OUT)

  • Multiple working positions:

    • O Office
    • R Remote
    • C Client / On-site
    • H Holiday
    • M Mixed

  • Automatic calculation of:

    • expected exit
    • daily surplus

  • Configurable lunch rules

  • Event mode with:

    • pairing
    • per-pair summaries
    • JSON output
    • unmatched detection

  • Internal audit log

  • Safe database migrations with automatic backups

  • Cross-platform (Linux, macOS, Windows)

๐Ÿ“ฆ Installation

๐Ÿฆ€ Cargo (recommended)

cargo install rtimelogger

๐Ÿง Arch Linux (AUR)

yay -S rtimelogger

# or

paru -S rtimelogger

๐Ÿบ Homebrew (macOS / Linux)

brew tap umpire274/tap

brew install rtimelogger

โš™๏ธ Configuration

Initialize configuration and database:

rtimelogger init

Example rtimelogger.conf:

database: /home/user/.rtimelogger/rtimelogger.sqlite
default_position: O
min_work_duration: 8h
min_duration_lunch_break: 30
max_duration_lunch_break: 90
separator_char: "-"
show_weekday: None   # None | Short | Medium | Long

Override database path at runtime:

rtimelogger --db /custom/path/db.sqlite <command>

๐Ÿงญ Main commands overview

Command Description
init Initialize DB and config
add Add or edit IN / OUT events
list Show sessions, events, or details
del Delete events or pairs (with confirmation)
backup Backup database (optional compression)
export Export data (CSV / JSON / XLSX / PDF)
db Database utilities
config Manage configuration file
log Show internal audit log

โž• Add work sessions โ€” rtimelogger add

rtimelogger add <DATE> [OPTIONS]

Examples:

rtimelogger add 2025-12-15 --in 09:00

rtimelogger add 2025-12-15 --out 17:30

rtimelogger add 2025-12-15 --in 09:00 --lunch 30 --out 17:30

rtimelogger add 2025-12-15 --edit --pair 1 --out 18:00

rtimelogger add 2025-12-15 --out 10:30 --work-gap

rtimelogger add 2025-12-15 --edit --pair 2 --no-work-gap

๐Ÿ“‹ Listing sessions โ€” rtimelogger list

The list command displays saved work sessions, supporting multiple layouts and levels of detail.

Basic usage:

rtimelogger list                     # current month

Shows the sessions for the current month using the default tabular layout.

๐Ÿ“… Supported periods

rtimelogger list --period 2025-12

rtimelogger list --period 2025

rtimelogger list --period 2025-12-01

rtimelogger list --period 2025-12-01:2025-12-31

rtimelogger list --period all

๐Ÿ“† Weekday display

The weekday is shown inside the date column, using the format:

YYYY-MM-DD (Mo)
YYYY-MM-DD (Monday)

The format is controlled by the show_weekday configuration option:

Value Output example
none 2025-12-19
short 2025-12-19 (Mo)
medium 2025-12-19 (Mon)
long 2025-12-19 (Monday)

๐Ÿ“Š Standard output

rtimelogger list --period 2025-12

Example:

DATE (WD)        | POSITION        |  IN   | LNCH  |  OUT  |  TGT  |  ฮ”WORK
---------------------------------------------------------------------------
2025-12-19 (Fr)  | Remote          | 08:55 | 00:30 | 18:27 | 17:01 | -02h04m

Columns explained:

  • IN โ€“ first check-in of the day
  • LNCH โ€“ total lunch break duration
  • OUT โ€“ last check-out
  • TGT โ€“ planned exit time (minimum required work time)
  • ฮ”WORK โ€“ worked surplus or deficit

๐Ÿงพ Pair details (--details)

rtimelogger list --period 2025-12-19 --details

Displays the individual IN/OUT pairs for the selected day. It is available only for single-day periods or --today.

Output example:

DETAILS
PAIR |  IN   |  OUT  | WORKED | LUNCH | POSITION | WG
------------------------------------------------------
  1  | 08:55 | 09:37 | 00h42m |  0m   | Remote   |
  2  | 13:07 | 18:27 | 04h50m | 30m   | Remote   |

Columns explained:

  • PAIR โ€“ pair index
  • IN / OUT โ€“ timestamps for the pair
  • WORKED โ€“ worked time for the pair
  • LUNCH โ€“ lunch break for the pair
  • POSITION โ€“ position for the pair
  • WG โ€“ working gap indicator (๐Ÿ”— for working gap, โœ‚๏ธ for non-working gap)

๐Ÿ“ฆ Compact view (--compact)

rtimelogger list --period 2025-12 --compact

Shows a condensed, single-line-per-day view, suitable for long periods.

Example:

DATE (WD)        | POSITION | IN / LNCH / OUT       | TGT   | ฮ”WORK
--------------------------------------------------------------------
2025-12-19 (Fr)  | Remote   | 08:55 / 00:30 / 18:27 | 17:01 | ฮ” -02h04m
2025-12-22 (Mo)  | Holiday  | --:-- / --:-- / --:-- | --:-- | ฮ” -

Characteristics:

  • compact horizontal layout
  • weekday forced to short format
  • no pair details

โš ๏ธ --compact cannot be combined with --details

Events listing (--events)

rtimelogger list --period 2025-12-15 --events

Displays the raw IN / OUT events for the selected day.

Output example:

EVENTS:

     Date Time     | Type |    Lunch     |     Position     | Source | Pair | Work Gap
----------------------------------------------------------------------------------------
โ†’ 2025-12-19 08:55 |   in | lunch  0 min | Remote           |  cli   |   1  |
             09:37 |  out | lunch  0 min | Remote           |  cli   |   1  |
             13:07 |   in | lunch  0 min | Remote           |  cli   |   2  |
             18:27 |  out | lunch 30 min | Remote           |  cli   |   2  |

๐Ÿ–๏ธ Holiday days

Days marked as Holiday:

  • display no time values (--:--)
  • do not affect surplus calculations
  • are rendered as neutral rows

โž• Period total

At the end of the output, a cumulative total is always displayed:

ฮฃ Total ฮ”WORK: +02h04m

The total accounts for:

  • lunch breaks
  • work gaps
  • holidays (neutral contribution)

๐Ÿ”ข JSON output (--json)

rtimelogger list --period 2025-12 --json

Outputs the data in JSON format for easy integration with other tools or scripts.

๐Ÿ—‘๏ธ Delete data โ€” rtimelogger del

rtimelogger del 2025-12-15

rtimelogger del --pair 2 2025-12-15

All deletions require confirmation and automatically reindex pairs.

๐Ÿ’พ Backup database โ€” rtimelogger backup

rtimelogger backup --file /abs/path/backup.sqlite

rtimelogger backup --file /abs/path/backup.sqlite --compress
  • confirmation before overwrite
  • ZIP on Windows
  • TAR.GZ on Linux/macOS

๐Ÿ“ค Export data โ€” rtimelogger export

rtimelogger export --format pdf --file /abs/path/report.pdf --range 2025-12

Supported formats:

  • csv
  • json
  • xlsx
  • pdf

Output path must be absolute.

๐Ÿ—„๏ธ Database utilities โ€” rtimelogger db

rtimelogger db --info

rtimelogger db --check

rtimelogger db --vacuum

rtimelogger db --migrate

โš™๏ธ Configuration management โ€” rtimelogger config

rtimelogger config --print

rtimelogger config --edit

rtimelogger config --migrate

Missing fields are added automatically with defaults.

๐Ÿ“œ Internal audit log โ€” rtimelogger log

rtimelogger log --print

Shows timestamped internal operations (add, del, migrate, backup, โ€ฆ).

๐Ÿ”„ Upgrading from older versions

If you are upgrading from 0.7.x or earlier, read:

โžก๏ธ UPGRADE-0.7-to-0.8.md

This document explains:

  • schema changes
  • migration behavior
  • removed legacy features
  • important behavioral differences

๐Ÿ“š Documentation

๐Ÿ“œ License

MIT License โ€“ see LICENSE.