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

• 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

• 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).

You can either install klirr from a prebuilt binary or you can build it yourself.

All prebuilt binaries are cryptographically signed and include build attestations for security verification. See SECURITY.md for details on verifying downloads.

brew install Sajjon/klirr/klirr

You can download signed binaries directly from GitHub Releases. All releases are marked as "Verified" by GitHub and include build attestations.

If you wanna build your self you can do it with Rust and cargo.

If you want to build the source yourself, you need Rust.

cargo install klirr

You can try klirr out with sample data before you set it up with your information if you want. Try running:

klirr sample

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.

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

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

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

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

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:

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.

First add the expense, then generate the invoice.

klirr data expenses --period 2025-05 -e "Sandwich, 6, EUR, 1, 2025-05-31" -e "Lunch, 11, GBP, 2, 2025-05-31"

Then generate the expenses invoice:

klirr invoice expenses

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).

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.

You can try sending a test email using klirr email test (you will be prompted for you encryption password).

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.

Interested in development? See development guide

Interested in how it works? See explanation guide

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!

This is an example of the Aioo Layout rendered using English.

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