Tired of manual bumping invoice number, calculating number of working days and looking up exchange rates and converting expenses into your currency?
Do you prefer automation? Then klirr is something for you!
Klirr is an AMAZING (Aesthetic, Multi-layouts/-language, Automatic, Zero-Maintenance, Inter-month Idempotent, Nimble, Gratis) invoice solution written in Rust + Typst
Tip
Scroll down to example invoice in the bottom to see what the invoice looks like.
Or try it out with cargo install klirr && klirr sample
Description ^
- Aesthetic – Produces polished, professional invoices. Klirr uses Typst templates to generate a beautiful invoice PDF for your services and expenses.
- Multiple Config – Localized, multiple Layouts, Invoice Granularity and Cadence. Klirr dynamically loads invoice labels in different languages (currently supports English and Swedish, adding more languages is trivial). This means your invoices can easily be generated in the language that suits you or your client. The invoice format is powered by Typst, and while Klirr comes with one elegant layout by default, the code is prepared to very easily support additional layouts. Klirr supports multiple
granularities
invoicing with fixed rate per hour, day, fortnight or month, and supports multiplecadence
invoicing bi-weekly or monthy. - Automatic – Automatically calculates number of worked days/hours. Klirr uses your system’s calendar to determine the target
period's
(month/fortnight) working days or hours and sets the invoice date to the last day of theperiod
, with the due date calculated based on your specified payment terms. Klirr also supports input of a certain number of days/hours off, subtracting those from the billable quantity – all handled automatically so that your invoice reflects the correct time worked. - Zero-Maintenance – One-time configuration via an interactive Terminal UI captures all company, client, project info etc. After this initial setup, no manual editing is required, and no coding or format knowledge (Rust/Typst/RON (the data format your information is recorded in)) is needed
- Inter-period Idempotent – Inter-period idempotence ensures consistent invoice numbering. No matter how many times you build an invoice in a given
period
(month/fortnight), it will reuse the same invoice number. When a newperiod
begins, Klirr automatically increments to the next number. This guarantees a stable, chronological sequence of invoices without duplicates or gaps. - Nimble - Quickly and effortlessly generates invoices in no-time, generating a invoice for services takes less than
10 ms
1 - Gratis – Free and open source forever, Klirr is free and open software licensed under MIT and installable with
brew install
,cargo install
or buildable from source.
If that was not enough, klirr also supports generation of expense invoices which automatically fetched currency exchange rates and translates them into your currency at the date of transaction for all your purchases (see [#expenses] below).
Klirr also supports automatic emailing of the invoices (see [#email] below).
Installation ^
You can either install klirr
from a prebuilt binary or you can build it yourself.
Pre-built binaries ^
All prebuilt binaries are cryptographically signed and include build attestations for security verification. See SECURITY.md for details on verifying downloads.
brew ^
brew install Sajjon/klirr/klirr
Direct Download ^
You can download signed binaries directly from GitHub Releases. All releases are marked as "Verified" by GitHub and include build attestations.
Build ^
If you wanna build your self you can do it with Rust and cargo.
Install Rust ^
If you want to build the source yourself, you need Rust.
Install klirr
^
cargo install klirr
Usage ^
You can try klirr out with sample data before you set it up with your information if you want. Try running:
klirr sample
Init ^
Before you can use klirr
to generate invoices you need to provide information about your company, the client, your payment details, and other info, do it using interactive terminal ui (TUI) by running:
klirr data init
You will be prompted
After setup is complete, you should have the following files in $DATA_PATH/klirr/data
(
$DATA_PATH
depends on OS, so full path is $HOME/Library/Application Support/klirr/data
on macOS):
vendor.ron
client.ron
invoice_info.ron
payment.ron
service_fees.ron
expenses.ron
These files use RON
("Rusty Object Notation") file format, a modern object notation superior to JSON/YAML/TOML.
Edit Data ^
If you later want to edit the data you input during init you can do so with another command:
klirr data edit all
Will start a flow similar to init
flow, but loading in all your existing data, hit ENTER to keep using existing data, or input a new value.
Alternatively you can edit individual files using:
klirr data edit vendor
klirr data edit client
You can see the possible values with:
klirr data edit --help
Note
klirr data edit
does not support editing expenses.ron
(expensed months) since
it is an array of values and not easily edited in a simple TUI prompt.
You append expenses using the klirr data expenses
command, see more info
below.
Manually ^
You can of course manually edit the files in the data folder by opening them up in your favourite text editor.
You can at any time validate the data by running:
klirr data validate
Or if you just wanna print the contents you can run:
klirr data dump
Generate Invoice ^
klirr invoice
or for current period
(month) instead of last using --period
:
klirr invoice --period current
or if you want to configure output path using -out
:
klirr invoice --out $HOME/my/custom/path/my_custom_name_of_file.pdf
Note
If you don't specify out
path the invoice will be saved in
$HOME/invoices
.
Off (free) for some days/hours? ^
If you did not work for some days/hours, and you need to not invoice for those days, e.g. 6
days off, use:
klirr invoice services-off --quantity 6 --unit days
klirr invoice services-off --quantity 16 --unit hours
Important
The unit
MUST match the rate
specified in the service_fees.ron
, e.g.
if you are invoicing with a daily rate, you must pass --unit days
and analogoulsy if you are invoicing with an hourly rate you
must pass --unit hours
.
Took vacation a whole period
or parental leave? ^
You can ensure klirr uses correct invoice number calculations if you need to skip invoicing completely some period
s by marking said period(s) as "period off". You do it by:
klirr data period-off --period "2025-06"
Which will write to $DATA_PATH/klirr/data/invoice_info.ron
This ensures that there are no gaps in invoice numbers for the month(s) you were off.
klirr data period-off --period "2025-06-first-half"
This ensures that there are no gaps in invoice numbers for the month(s) you were off.
Tip
There is currently no support for subtracting/removing periods off using Cli, if you made a mistake
or otherwise wanna perform some changes, manually edit the file
$DATA_PATH/klirr/data/invoice_info.ron
where $DATA_PATH
depends on OS, but typically
$HOME/Library/Application Support
on macOS using your favourite text editor.
After edit you can validate the data with:
cargo run --bin klirr data validate
Invoice for expenses ^
First add the expense, then generate the invoice.
Add expenses ^
klirr data expenses --period 2025-05 -e "Sandwich, 6, EUR, 1, 2025-05-31" -e "Lunch, 11, GBP, 2, 2025-05-31"
Note
The transaction day is allowed to be a different month than the value you put in --month
, e.g. if
if you had an expense on last of June but wanna include that expense in the invoice made in July
should save the expense under July.
Note
klirr data expenses
will aggregate identical expenses (disregarding quantity
) under one entry and sum
up the quantity. So if you run the klirr data expenses
twice with identical input and lets say one expense
item having quantity 2
, if you run it lets say four times, it will still show as one entry but with a
quantity of 8
.
Tip
There is currently no support for subtracting/removing expenses using Cli, if you made a mistake
or otherwise wanna perform some changes, manually edit the file $DATA_PATH/klirr/data/expenses.ron
where $DATA_PATH
depends on OS, but
typically $HOME/Library/Application Support
on macOS
using your favourite text editor.
After edit you can validate the data with:
cargo run --bin klirr data validate
You cannot edit expenses using klirr data edit
as mentioned above.
Generate expenses invoice ^
Then generate the expenses invoice:
klirr invoice expenses
Note
Exchange rates will be cached in $DATA_PATH/klirr/data/cached_rates.ron
keyed
under the (Date, FromCurrency, ToCurrency)
triple, to not burden the exchanges
API unnecessarily and to make klirr extra fast for you.
Email ^
Klirr can automatically send an email with the invoice for you after it has been generated.
This requires you to setup an App Password with your email service, for information on how to set it up for Gmail see here. If you setup klirr to be able to send emails you will be prompted for this App Password and you will be prompted for an encryption password which will be used to encrypt the App Password. The encryption password can be anything as long as it adheres to minimum length requirement (typically 4 chars min).
Init ^
Get started with email sending of your invoices by setting up the email configuration, run:
klirr email init
Similarly to klirr data init
you will now be prompted for a series of inputs required to send your email, including sender email, sender App Password, encryption password (see Security below for more info), recipients email address and more.
Later, when using this email sending feature you will always be prompted to input the encryption password, so that klirr can decrypt the App Password to be able to send emails.
Tip
Optionally, if you don't want to have to input the encryption password every
time you invoice you can export it in an environment variable named
KLIRR_EMAIL_ENCRYPTION_PASSWORD
, we recommend you use direnv
and source
it from a hidden file, typically .envrc.secret
place in a directory you
will run klirr
from, which is safer than exporting the password in your
.zshrc
.
Send Test email ^
You can try sending a test email using klirr email test
(you will be prompted for you encryption password).
Security ^
Important
Klirr's email feature is safe to use. Klirr uses strong encryption and employes all IT security best practices to keep your App Password safe. It is crucual that an attack does not get access to your App Password since email services does not allow users to limit the scope and permission of the App Password, with it and attacker can read all your emails and send emails to anyone impersonating you!
Therefor, klirr employes these best practices to keep your App Password safe:
- Key-Derivation: Klirr does not use your encryption password directly, first it's run through a Hash based Key-Derivation-Function using a application unique
INFO
(see 'How Should You Introduce Randomness into HKDF?' section of this blog post) and cryptographically secure random generatedSALT
, this forms a strong and uniqueEncryptionKey
- Advanced Encryption: Klirr uses [AES (Advanced Encryption Standard)] encryption with 256 bits strength, encrypted using the
EncryptionKey
from last step. - Zeroisation: Klirr uses Zeroisation to eagerly erase sensitive secrets from memory.
You can review how klirr employes these safety measures in the encryption folder of the code.
Development ^
Interested in development? See development guide
How it works ^
Interested in how it works? See explanation guide
Etymology ^
Klirr is a Swedish 🇸🇪 an onomatopoeia word meaning "clink" - the sound of coins falling onto a hard surface. It is part of the Swedish idiom "klirr i kassan" ("clink in the cash register") meaning "cash flow", income you get from invoicing!
Example ^
This is an example of the Aioo Layout
rendered using English
.