rtimelogger 0.8.5

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.2

🗄️ Database migration

Starting from v0.8.2, rTimelogger automatically migrates the database schema to support the new National holiday position.

The migration extends the events.position CHECK constraint
The migration is idempotent (no changes are applied if the schema is already up to date)
No manual action is required

🧭 Notes

Holiday should be used for personal leave days
National holiday should be used for public holidays defined by law or company calendar
Future versions may introduce calendar-based automation for national holidays

✨ Features

Event-based time tracking (IN / OUT)
Multiple working positions:
- O Office
- R Remote
- C Client / On-site
- N National holiday
- 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

🐧📦 Linux (Debian / Ubuntu)

Starting from v0.8.0, rFortune provides an official .deb package.

You can install it directly from the GitHub Releases page:

sudo dpkg -i rtimelogger_<version>_amd64.deb

To verify integrity, download the corresponding .sig file and verify it with GPG (see below).

sha256sum -c rtimelogger_<version>_amd64.deb.sha256

gpg --verify rtimelogger_<version>_amd64.deb.sig

If dependencies are missing, complete the installation with:

sudo apt --fix-broken install

🐧🔧 Other Linux distros

You can still use the prebuilt tarball:

tar -xvf rtimelogger-<version>-x86_64-unknown-linux-gnu.tar.gz

sudo mv rtimelogger /usr/local/bin/

🍎 macOS

You can use the prebuilt tarballs for Intel or Apple Silicon:

tar -xvf rtimelogger-<version>-x86_64-apple-darwin.tar.gz

sudo mv rtimelogger /usr/local/bin/

tar -xvf rtimelogger-<version>-aarch64-apple-darwin.tar.gz

sudo mv rtimelogger /usr/local/bin/

🪟 Windows

Download the prebuilt zip file, extract it, and move rtimelogger.exe to a directory in your PATH, e.g., C:\Windows\System32\ or create a dedicated folder like C:\Program Files\rtimelogger\ and add it to your system PATH.

⚙️ Configuration

Initialize configuration and database:

rtimelogger init

Example rtimelogger.conf:

database: /home/user/.rtimelogger/rtimelogger.sqlite
default_position: O
min_work_duration: 8h
lunch_window: 12:30-14:00
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

📌 Day positions

rTimelogger supports multiple day positions to describe how a working day (or non-working day) is classified.

Supported positions

Code	Name	Description
`O`	Office	Regular office working day
`R`	Remote	Remote working day
`C`	On-site	Working day at customer site
`M`	Mixed	Mixed working locations
`H`	Holiday	Personal holiday (counts against personal leave allowance)
`N`	National holiday	Public holiday (does not affect personal leave allowance)

➕ Adding a national holiday

To mark a public/national holiday, use the add command with the national position.

rtimelogger add 2025-12-25 --pos n

rtimelogger add 2025-12-25 --pos national

Behavior

No --in, --out, --lunch, or --work-gap parameters are allowed
The day is recorded as a non-working public holiday
The day does not contribute to worked time
The day does not reduce personal holiday allowance

📋 List output behavior

National holiday days

In both standard and compact list views:

All time-related fields are displayed as --:--
Target end (TGT) is not computed
Worked delta (ΔWORK) is neutral (-)
The day is clearly labeled as National holiday

Example:

2025-12-25 (Thu) | National holiday | --:-- | --:-- | --:-- | --:-- | -

⚖️ Holiday vs National holiday

Aspect	Holiday (`H`)	National holiday (`N`)
Working day	❌	❌
Counts as personal leave	✅	❌
Expected time	❌	❌
ΔWORK contribution	❌	❌
Requires time entries	❌	❌

📋 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.

Import data (JSON / CSV)

Starting from v0.8.3, rTimelogger supports importing work sessions and holidays from external files.
This feature is designed to simplify preventive data entry, especially for national holidays.

The import system is safe by default and provides a full dry-run mode.

Supported formats

JSON

Flexible JSON structures are supported. The following formats are valid:

Root object with holidays:

{
  "year": 2026,
  "holidays": [
    {
      "date": "2026-01-01",
      "name": "New Year"
    },
    {
      "date": "2026-01-06",
      "name": "Epiphany"
    }
  ]
}

Root object with days:

{
  "days": [
    {
      "date": "2026-05-01",
      "position": "N",
      "name": "Labour Day"
    }
  ]
}

Root array of day objects:

[
  {
    "date": "2026-12-25",
    "name": "Christmas Day"
  }
]

Notes:

position is optional:
- if omitted, it defaults to NationalHoliday
name is optional and stored in the event meta field

CSV

CSV files must include a header row.

Example:

date,position,name
2026-01-01,N,New Year
2026-01-06,N,Epiphany
2026-04-25,N,Liberation Day

Notes:

position must be a valid location code (N, H, O, R, C, M)
name is optional

Import command

rtimelogger import --file <path> [options]

Options

--file <path> : Path to the input file (required)
--format <json|csv> : Input format (default: json)
--dry-run : Simulate the import without modifying the database (strongly recommended)
--replace : Replace existing events for conflicting dates (dangerous)
--source <label> : Logical label describing the origin of imported data. The final stored value will include the format automatically (e.g. import (from json))

Import behavior

Only Holiday and NationalHoliday positions are accepted by default.
Dates with existing work events are skipped unless --replace is used.
Imported holidays:
- do not affect the vacation balance
- are treated as regular timeline entries
Each import generates a detailed summary:
- total rows
- imported
- skipped
- conflicts
- invalid rows

Example (dry-run)

rtimelogger import \

  --file holidays_2026.json \

  --format json \

  --dry-run

Example (apply import)

rtimelogger import \

  --file holidays_2026.csv \

  --format csv \

  --source calendar

Metadata and traceability

Imported events store additional information in the meta field (JSON).
The source field tracks the origin of the data:
- CLI entries → cli
- Imports → import (from json) / import (from csv)

This ensures full traceability of all events.

🗄️ 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

📄 CHANGELOG.md
🔄 UPGRADE-0.7-to-0.8.md

📜 License

MIT License – see LICENSE.

rtimelogger 0.8.5

🚀 What’s new in v0.8.2

🗄️ Database migration

🧭 Notes

✨ Features

📦 Installation

🦀 Cargo (recommended)

🐧 Arch Linux (AUR)

🍺 Homebrew (macOS / Linux)

🐧📦 Linux (Debian / Ubuntu)

🐧🔧 Other Linux distros

🍎 macOS

🪟 Windows

⚙️ Configuration

🧭 Main commands overview

➕ Add work sessions — rtimelogger add

📌 Day positions

➕ Adding a national holiday

📋 List output behavior

⚖️ Holiday vs National holiday

📋 Listing sessions — rtimelogger list

Basic usage:

📅 Supported periods

📆 Weekday display

📊 Standard output

🧾 Pair details (--details)

📦 Compact view (--compact)

Events listing (--events)

🏖️ Holiday days

➕ Period total

🔢 JSON output (--json)

🗑️ Delete data — rtimelogger del

💾 Backup database — rtimelogger backup

📤 Export data — rtimelogger export

Import data (JSON / CSV)

Supported formats

JSON

CSV

Import command

Import behavior

Example (dry-run)

Example (apply import)

Metadata and traceability

🗄️ Database utilities — rtimelogger db

⚙️ Configuration management — rtimelogger config

📜 Internal audit log — rtimelogger log

🔄 Upgrading from older versions

📚 Documentation

📜 License

➕ Add work sessions — `rtimelogger add`

📋 Listing sessions — `rtimelogger list`

🗑️ Delete data — `rtimelogger del`

💾 Backup database — `rtimelogger backup`

📤 Export data — `rtimelogger export`

🗄️ Database utilities — `rtimelogger db`

⚙️ Configuration management — `rtimelogger config`

📜 Internal audit log — `rtimelogger log`