Skip to main content

Introduction

dey is a terminal-based time tracker for logging work hours against named jobs.

The name comes from the Alexander Dey Time Register Clock (1888), an early punch-clock that recorded employee hours on a paper roll. Like its namesake, dey uses a simple punch-in, punch-out model: start a timer against a job, stop it later. You can also backfill entries for past times.

Using a spreadsheet to track work hours is cumbersome: Excel is slow to open, times and dates must be entered manually, multiple jobs create an unwieldy number of columns, and generating summaries is complicated. This program offers a simple terminal-based alternative. It automatically records the current date and time, resolves short job-name fragments by substring matching, and produces clear daily and weekly summaries that can be filtered the same way. A single command also lets you undo the last entry, adjust its time, or change its job.

The design deliberately stays simple. Only one job can be active at a time. Features such as billing calculations, notes, hierarchical projects, tags, idle detection, goals, configuration files, and shell completions are omitted so the tool remains a focused Unix-style utility: easy to understand, quick to use with short commands, and simple to combine with other programs through its clean, well-formatted output.

A simple example shows creating a job for the first time, starting time tracking against that job, and then stopping the work over an hour later:

> dey -j meetings
  New job "meetings" created.
> dey -t
  00:00 | 07:42 -        meetings
> dey -t
  01:05 | 07:42 - 08:47  meetings

Data Storage

The data for the program is saved in text files at

OS Location
Windows %LOCALAPPDATA%\dey\
Linux $XDG_CONFIG_HOME/dey/ or ~/.config/dey/
macOS ~/.config/dey/

The jobs.txt file stores definitions of jobs:

a  meetings
a  permissive vacation
a  permissive sickness
i  Project X

Each job is defined with an ID (the row number in the file), an active, a, or inactive, i, flag, and a label. The inactive flag hides the job from searches when starting work on a job; it does not hide the history of work done for those jobs. The jobs are in the order they were created.

The logs.txt file stores the work done, called "logs":

20260919  07:31  0001  09:22
20260919  10:03  0003  13:45
20260920  08:10  0001  10:50
20260926  08:30  0002

Each log contains a date represented as an integer in YYYYMMDD format, a start time, a job ID, and a stop time. Times are in 24-hour format. Job IDs are four-digit integers, which means up to 9999 different jobs can exist. A missing stop time indicates that the log is currently active. Times are recorded to the nearest minute; finer precision is omitted because minute precision introduces only a zero-bias error, and many organizations do not require accuracy beyond one-tenth of an hour.

The time intervals of different logs cannot overlap, so at any given moment, work can be performed on only one job. As a consequence, no more than one log may have a missing stop time because it is current. A log cannot span more than one day. At the latest, it must end by 23:59. Consequently, no date arithmetic is performed. Logs are listed in the order they were created, which may differ from their chronological order.

Both the jobs file and the logs file have been designed so that in most cases, a full rewrite of the file is not necessary. Instead, a new job or log can be appended to the corresponding file. Though negligible anyway, this does reduce processing time and wear on solid state discs. It is not intended that the user ever directly modify these files; if you do, be very careful not to corrupt the format.

If full editing ability were supported, a log ID would need to accompany each log in order to address the specific log. Start and stop times would need to be directly specified. Even an interactive interface for editing would be preferable. These are all directions that would take away from the simplicity of this program. Therefore, what is not supported is the ability to edit any arbitrary log, besides the last. Consequently, it is the responsibility of the user to pay attention when entering logs and not create the occasion for editing logs several entries prior. The last entry can be modified, but anything prior must be modified by undoing entries. That said, the logs file is formatted such that it is not too difficult to directly edit, and the line numbers beside the jobs and visible with a code editor correspond to the job IDs.

Interface

Just the name of the program prints the status:

> dey
  07:32 | 14:10 - 15:05  meetings
> dey
  07:32 | 14:10 -        meetings

This shows the total time worked for the present day, the start and stop times and the job label of the latest log. If the latest log is current, nothing is printed in place of the stop time. If no logs exist for the present day, a statement to this effect is output.

Additional functionality is available with the following command arguments (flag letters preceded by a dash) and their optional tails (text following the arguments):

Arguments Description
-l {label} List all active jobs matching label
-L {label} List all jobs matching label
-j {label} {label} Create job, rename job
-i {label} Make job active job inactive
-a {label} Make job inactive job active
-t {time} {date} {label} Toggle time or switch active job
-e {time} {label} Edit time or job of last entry
-u {integer} Undo last log entries (default to 1)
-d {date} {label} Day report (default to recent date)
-w {weeks} {label} Week report (default to recent week)
-h Print command help

A date is entered in the format YYYY-MM-DD or YY-MM-DD. Time is entered in the format HH:MM. Each argument is a standalone instruction that does not depend on any other argument. Multiple command arguments can be given in a single terminal command and they will be executed in the order they are written.

Jobs

List Jobs

The list of existing active jobs can be printed by entering the -l flag without any job labels. This will print all the jobs in alphabetical order:

> dey -l
  meetings
  permissive sickness
  permissive vacation

The list can be narrowed down by entering part of a job label after the flag:

> dey -l perm
  permissive sickness
  permissive vacation

All string matching to job labels is case-insensitive.

All jobs including inactive ones can be listed with the -L flag:

> dey -L
  meetings
  permissive sickness
  permissive vacation
  Project X

The inactive jobs are marked in gray.

Create a Job

A new job can be defined with the -j argument followed by the job label:

> dey -j Clean-up
  New job "Clean-up" created.

If a job by that exact name (using case-insensitive matching) already exists, the command will be rejected.

Rename a Job

An active job can be renamed by adding a second string:

> dey -j Clean-up Cleanup
  Job "Clean-up" renamed to "Cleanup".

When searching for matches on the first string, a partial match will be accepted. For example, vaca would match permissive vacation. If no match or more than one match can be found, the command will be rejected. If the second string fully matches an existing job label, the command will be rejected.

Renaming an inactive job requires first making it active.

Active and Inactive Jobs

An active job can be made inactive so that it no longer is chosen as a valid match to new work by using the -i flag:

> dey -i Project\ X
  "Project X" is now inactive.

An inactive job can be made active by using the -a flag:

> dey -a Project\ X
  "Project X" is now active.

Job Aliases (not implemented)

A job can have an alias (or description) by appending the extra text to the job name separated by a colon:

> dey -j "Project X: Hyper-engine research"

This is useful when printing reports. Reports will list the names of projects. Because many projects can lead to very similar names which can make entering totals into official time-reporting software error-prone, the print feature will emphasize those parts of the names which are unique. However, the alias of the name will never be included in the emphasis because that part will never be used in reporting. That said, job searches can still match to the alias.

Toggle Clock

Without Time

Time tracking is toggled using the -t argument:

> dey -t
  00:18 | 07:42 -        Project X

This will start a log if none is current or end a log if one is current. The status will be automatically printed to give confirmation. The simplicity of not specifying whether the time is a start or stop means there can be only one active log at a time.

With Time

By default, the current time is used, but any time can be explicitly specified after the -t argument:

> dey -t 07:45
  00:15 | 07:45 -        Project X

This will mark the start or stop of a log with that time. If a new start or stop time overlaps with any other log of the same day, the command will be rejected and an explanation will be printed. So, giving a stop time that comes before the start time of the same log will be rejected and an explanation will be printed.

Only one current log is allowed at a time. This is why the interface does not provide separate start and stop commands. So, if a log is current (has no stop time) another log cannot be started. Instead, if the time is after the start time of the current log, the new time will be used as the stop time of the current log.

It is possible to forget to stop a log at the end of the day. So, the next day when a time is given, it will be used as the stop time of yesterday's log. If the stop time is before the log's start time, the command will be rejected. Clocking out will only apply to the same day as the start of the current log. This means you can clock out by entering something like dey -t 17:00 and this will apply to the day the current log was started. The program will not mark the log as continuing into the next day.

Because logs can be defined with specific times (other than the present), they can be created out of order. The log file is not sorted in chronological order. This is a deliberate choice to support undoing actions in the order they were commanded.

If an active log was started on a prior day, the date must be specified. A log cannot span across dates.

With Date

By default, the current day is used, but any date can be specified explicitly after the -t argument:

> dey -t 07:45 26-09-17

The format for dates is either 26-09-07 or 2026-09-07.

With Job Label

By default, the job of the last log is the assumed job for a new log. However, any job can be specified:

> dey -t meetings
  00:18 | 07:42 -        meetings

If no log is current, the job specified is used as the job of the new log. If a log is current, the current time or the time provided is used to stop the current log and to create a new log and the specified job is used for the new log. This makes it easy to switch jobs without having to explicitly stop the current log and start another. If the specified job does not match any previously-defined jobs, the command will be rejected.

Undo Last Entry (not implemented)

The last entry (start or stop or a log) can be undone with the -u argument:

> dey -u
  No logs for today.

Multiple entries can be undone at once by providing an integer.

Edit Last Entry (not implemented)

The last log entry (start time, job label, or stop time) can be edited with the -e argument. So, if a log is current, the -e command can be used to change the start time:

> dey -e 07:45
  00:15 | 07:45 -        Project X

Providing a job label will change the job of the last entry.

> dey -e meetings
  00:18 | 07:42 -        meetings

Both a time and a job label can be specified together.

Reports

Day Reports (partially implemented)

The day report shows the date of the last log, a color-coded graph of that day's work, and the total time worked for that day. This is followed by that day's logs, each preceded by the corresponding color-coding. If the output stream does not support ANSI escape codes, letters are used instead:

> dey -d
  2026-09-12 aaaaaabbbbbbbbbbbbbccccccccccccccccccccc 07:15

  a  02:45 | meetings
  b  02:30 | Project X
  c  03:59 | meetings

Colors are chosen from a subset of the 8-bit ANSI-escape-code colors based on the order the jobs first appeared in the day. (Only 8-bit colors are used because most terminal emulators support those but not all terminal emulators support millions of colors.) If letters are used instead, they are chosen in alphabetic order, again based on the jobs sequence in the day. Depending on the start and stop times for the day and the column width of the present output stream, each character in the graph corresponds to a tenth, quarter, half, or whole hour. The start of the bar corresponds to the beginning of the first log of the day and the end corresponds to the end of the last or present if a log is current.

Because the day summary can accept a date, any past day can be reported. If a date is provided (in the format 26-09-07 or 2026-09-07) the summary of that day will be printed. If a job label is provided as in dey -d meetings, the summary of just that job (or any job to which the text substring matches) for the current date will be printed. These two options can be combined as in dey -d 26-09-07 meetings to print a report of just that job for that date. The colors chosen will be the same as if all the jobs for the day were printed.

Week Reports (not implemented)

The week report (dey -w) aligns with the beginning of a week, not the current day. For example, if the current day is Wednesday, the current week would be from Sunday of that week to Wednesday, not the past seven days. The purpose of the week report is to show the total hours worked per day, per job, and for the week. The report is printed in a markdown-compatible format:

> dey -w
  Total | 09-06 | 09-07 | 09-09 | 09-10 | 09-11 | Job
  :---: | :---: | :---: | :---: | :---: | :---: | :---
  13:15 | 02:45 | 08:00 | 02:00 | 00:00 | 00:30 | Meetings
  16:30 | 03:30 | 00:00 | 05:00 | 02:00 | 06:00 | Documentation
  10:15 | 02:00 | 00:00 | 01:30 | 05:30 | 01:15 | Education
   ---  |  ---  |  ---  |  ---  |  ---  |  ---  |
  40:00 | 08:15 | 08:00 | 08:30 | 07:30 | 07:45 |

More weeks can be specified with a number after the -w argument flag. The additional weeks will be printed as separate tables in chronological order.

If a job label is provided, just like the day report, only logs matching that search will be printed. Because of substring search, multiple job labels can be matches.

Alternatives

There are several alternatives, but I believe none approach this problem with the same level of simplicity and succinctness or brevity as dey.

Metadata

Release files for dey 0.2.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for dey 0.2.1
File Size Uploaded Provenance Actions
dey-0.2.1.tar.gz 19.3 kB Without provenance Details for dey-0.2.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for dey 0.2.1
File Interpreter ABI Platform Actions
dey-0.2.1-py3-none-any.whl Python 3 none any Details for dey-0.2.1-py3-none-any.whl

Total release size: 33.1 kB

Release files / dey-0.2.1.tar.gz

Download URL dey-0.2.1.tar.gz
Size 19.3 kB
Tags Source
SHA-256 checksum
How to use checksums
cd9e67735dd5ca0a4f74311351d75082fb2f5269fe3a42f30bb7dc0327f6ee19
BLAKE2b-256 checksum
How to use checksums
96ebc9d98ab10c51d197bfa409bb8a738dad0e448fcd020c2098aa881a9847a9
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.13.16

Release files / dey-0.2.1-py3-none-any.whl

Download URL dey-0.2.1-py3-none-any.whl
Size 13.8 kB
Tags Python 3
SHA-256 checksum
How to use checksums
c5db875305b7afd56da8918e52114faa0b91f03f2cdadbc4ff26d20c201c14eb
BLAKE2b-256 checksum
How to use checksums
483b7bdf38a552b2043e58415f9109f1c9b38e3e6c09a3f26ceb09ddc3133be1
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.13.16

Security for dey 0.2.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page