cassiopeia

A simple time tracking tool for the kookie office ecosystem.

The kookie office ecosystem is a set of free software, plain text tools that I use to run my business. The other tool you may want to look at is called [invoice]!

How to use

Each time file only tracks a single customer or project that you are working on. The time file itself is simply a set of commands, followed by associated data. The following four keywords exist:

• HEADER: define metadata about the client, and store the time file version to avoid parsing with an incompatible version in the future
• START: opens a work session with a local timezone timestamp
• STOP: closes a work session with a local timezone timestamp
• INVOICE: mark the previous section of sessions as "billed". This is useful if a project is long-running and you want to bill parts of the work that you have been doing.

It is recommended not to write this file by hand, although you definitely can. Lines starting with ;; are comments and will be ignored. Careful though: they will be stripped from the file next time that cassiopeia writes it out. Comment pass-through is on the roadmap, but not yet implemented!

cass(1) comes with a few commands

• start will start tracking for an account
• stop will stop tracking and error if no open slot exists
• invoice will add an invoice block to the time file

All commands require a -f (or --file) parameter to know which time file they are operating on. If none is provided, the time.cass file in the current working directory is tried. If this does not exist, the program exits with an error.

By default time values are rounded to the next 15 minutes. To disable this, pass -r to either the start or stop commands.

Interaction with invoice

cassiopeia is designed to output .yml configuration that can be used to generate invoices for your clients. For this, it needs access to your client database, and uses the client and project keys in your time file header to look them up. If none are present, you can pass this data to the invoice command manually with --client and --project. You provide your client database path with --client-db

The following command will generate an invoice for a project done for the ACME inc. client:

$ cass invoice --client-db /home/office/clients.yml --client acme --project world-domination

Contrutions welcome via my [public inbox]