From d40e014aebc778939ae8d9afae225b7d4f6cc949 Mon Sep 17 00:00:00 2001 From: Mx Kookie Date: Fri, 11 Dec 2020 17:58:39 +0000 Subject: cassiopeia: adding more types to the time file abstraction --- apps/cassiopeia/README.md | 64 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 64 insertions(+) create mode 100644 apps/cassiopeia/README.md (limited to 'apps/cassiopeia/README.md') diff --git a/apps/cassiopeia/README.md b/apps/cassiopeia/README.md new file mode 100644 index 000000000000..d6456bf7f403 --- /dev/null +++ b/apps/cassiopeia/README.md @@ -0,0 +1,64 @@ +# 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 any command. + + +## 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 -- cgit v1.2.3