ClockifyAnalysis

CLI tool for analyzing Clockify time-tracking data. Generates reports, checks hours against time budgets, and can create default time entries.

Setup

Automatic

Simply build the app and let it create a config:

cargo build --release
clockify create-config   # creates ~/.config/clockify-analysis/ with starter files

Then edit ~/.config/clockify-analysis/env to add your API key, and ~/.config/clockify-analysis/config.toml to configure your workspace (use show-projects to find project IDs after inserting an API key).

Manual/Local

First, copy .env.example to .env and add your Clockify API key. Then copy config.toml.example to config.toml and fill in your project IDs (use show-projects to find them after inserting an API key). Note that the config in the local directory will take precedence over a global config.

Shell completion

Completion scripts are in the completions/ directory.

Bash — source it in your ~/.bashrc, or drop it into /etc/bash_completion.d/:

source completions/clockify.bash

Zsh — place completions/_clockify in a directory on your $fpath, then rebuild the completion cache:

cp completions/_clockify /usr/local/share/zsh/site-functions/
autoload -Uz compinit && compinit

Commands

create-config

Creates ~/.config/clockify-analysis/ with a starter config.toml and env file. Skips any file that already exists with a warning.

clockify create-config

---

show-projects

Lists all projects in your workspace with their IDs.

clockify show-projects

---

summary

Shows total hours logged for a month plus an estimate of remaining hours based on remaining workdays.

clockify summary [--month <month>] [--year <year>]

• --month — month name (e.g. January, Sep, 3) or last. Defaults to current month.
• --year — defaults to the most recent past occurrence of the given month.

---

lint

Checks time entries for common issues: missing pause, overlapping entries, entries without descriptions, days with no time tracked, and time logged on non-workdays or time-off days.

Exits with code 2 if violations are found.

clockify lint [--month <month>] [--year <year>]

---

create-report

Downloads a PDF report for a given month from Clockify.

clockify create-report [--month <month>] [--year <year>] [--output <path>]

• --output — output file path. Defaults to Report MM-YYYY.pdf.

---

create-default-entries

Creates the default time entries defined in config.toml for a given day, starting at the specified time. Checks for conflicts with existing entries before creating anything.

clockify create-default-entries [--day <day>] [--start <time>]

• --day — today (default), yesterday, tomorrow, or a weekday name (monday, fri, …). Weekday names always resolve to the most recent past occurrence.
• --start — start time in h:mm or hh:mm format. Defaults to 9:00.

---

time-budget

Reports time budget planning and constraints. Budgets are defined in config.toml as [[time-budget]] entries.

clockify time-budget [--id <id>] [--list]

• --list — lists all configured budgets in descending chronological order with numeric IDs.
• --id — which budget to inspect: current (default, the one containing today, or the most recent), prev/previous, next (nearest budget starting in the future), or a numeric ID from --list.

The report shows logged hours, remaining planned workdays (broken down by days off and public holidays), time-off days, and overflow (hours under or over budget).

Configuration

See config.toml.example for all available options.