Metadata-Version: 2.4
Name: worklog-cli
Version: 2.0.0
Summary: A personal time-tracking system
Project-URL: Homepage, https://github.com/cproctor/worklog
Project-URL: repository, https://github.com/cproctor/worklog
Author-email: Chris Proctor <chris@chrisproctor.net>
License-Expression: MIT
Requires-Python: >=3.10
Requires-Dist: arrow
Description-Content-Type: text/markdown

# Worklog

A personal time-tracking system. 

Worklog provides a simple mechanism for logging in and out of accounts which are
billed for time elapsed. The author, a professor, uses it to bill time to
various commitments. Some really are paid hourly (e.g. consulting), but most are
not. The primary use is to track and analyze how time is spent. 

## Installation

Worklog can be easily installed using [pipx](https://pipx.pypa.io/latest/installation/):

    pipx install worklog-cli

or, if you use [uv](https://docs.astral.sh/uv/):

    uv tool install worklog-cli

You will also need to install [hledger](https://hledger.org/). 

## Usage

If you are just getting started, make a list of the ways you spend time (or at
least those you want to track). If you want to nest accounts, separate them with
colons. For example, here are a few of my accounts:

```
 research:grants
 research:projects
 research:pubs
 research:reading
 research:lab
 teaching:planning
 service:advising
 identity:website
 identity:network
 overhead:email
 overhead:waste
 overhead:admin
```

Now run `work`. You will be asked to log in to an account, and then to enter a
description of the work you are doing. (Accounts can be auto-completed using tab.)

```
% work
Log in to account: research:reading
Work description: Writing the Worklog README
[Enter to log out]
```

Press enter when you finish that work session, and you will be prompted to log
in to another account. Press Control + C when you are finished. That's it!

While entering an account name, press Tab to autocomplete; if there's more than
one match, press Tab again to list the possibilities.

## Commands

The base command is `work`, which enters a loop for logging in and out of
accounts. There are several other modes available:

- `work report` (or `work r`) shows work statistics and quits. By default it
shows daily balances for the past week, but this can be adjusted:
  - Append an account name to restrict the report to that account, e.g.
    `work report research:reading`.
  - `-b/--begin` and `-e/--end` set the date range (hledger date syntax), e.g.
    `work report -b 2026-01-01 -e 2026-02-01`.
  - `--daily`, `--weekly`, `--monthly`, or `--yearly` change how balances are
    grouped, e.g. `work report --monthly`.
- `work edit` (or `work e`) opens the current worklog for editing. Sometimes I find I need to
edit the worklog to add a work session or change times (for example, if I forgot
to log out before going to bed). 
- `work archive FILENAME` (or `work a FILENAME`) archives the current worklog at
the given filename and starts a new worklog. If you plan to log your work over
time, I suggest you keep your log
files in version control. 

## Configuration

Worklog follows the [XDG Base Directory](https://specifications.freedesktop.org/basedir-spec/latest/)
convention. A configuration file is automatically created at
`$XDG_CONFIG_HOME/worklog/config` (`~/.config/worklog/config` by default), and
worklog data is stored at `$XDG_DATA_HOME/worklog/worklog.timeclock`
(`~/.local/share/worklog/worklog.timeclock` by default). If you have an existing
`~/.worklog` directory from an older version of Worklog, it will automatically be
migrated to these locations the first time you run `work`.

```
[WORKLOG]
logfile = /Users/me/.local/share/worklog/worklog.timeclock
editor = vim
```

## Formats

Worklog relies on [hledger](https://hledger.org/), a Haskell implementation of
[ledger](https://github.com/ledger/ledger), for double-entry bookkeeping which
regards time as a resource just like money. One main design goal of this system
is a [human-readable ledger format](https://hledger.org/timeclock.html) which
can also be parsed by scripts. 

## Development

This project uses [uv](https://docs.astral.sh/uv/) for dependency management and
packaging.

```
uv sync              # create a virtualenv and install dependencies
uv run work           # run the CLI from source
uv build              # build the sdist and wheel into dist/
uv publish            # upload to PyPI
```


