# 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]!

[invoice]: https://git.spacekookie.de/kookienomicon/tree/infra/libkookie/overlays/kookie/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]

[public-inbox]: https://lists.sr.ht/~spacekookie/public-inbox