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

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

Table Of Contents

• Description
• Installation
  • Pre-built binaries
    • brew
  • Build
    • Install Rust
    • Install klirr
• Usage
  • Init
  • Edit Data
    • Manually
  • Generate Invoice
    • Off for some days/hours?
    • Took vacation a whole period or parental leave?
  • Invoice for expenses
    • Add expenses
    • Generate expenses invoice
  • Email
    • Init
    • Send Test email
    • Security
• Development
• How it works
• Etymology
• Example

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 multiple cadence 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 the period, 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 new period 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¹
• 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):

1. vendor.ron
2. client.ron
3. invoice_info.ron
4. payment.ron
5. service_fees.ron
6. 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:

Days off

klirr invoice services-off --quantity 6 --unit days

Hours off

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 periods by marking said period(s) as "period off". You do it by:

Whole month off

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.

Whole fortnight 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:

1. 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 generated SALT, this forms a strong and unique EncryptionKey
2. Advanced Encryption: Klirr uses [AES (Advanced Encryption Standard)] encryption with 256 bits strength, encrypted using the EncryptionKey from last step.
3. 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.

Footnotes

1. When run on Macbook Pro M2 Max running macOS 15.5 (24F74) using a Klirr binary compiled with --release flag.