You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
64 lines
2.6 KiB
64 lines
2.6 KiB
# 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
|
|
|