Repository files navigation

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 anAMAZING (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
    • Installklirr
• 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 usesTypst 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 multiplegranularities 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 targetperiod'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/hoursoff, 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 givenperiod (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 than10 ms¹
• Gratis –Free and open source forever, Klirr is free and open software licensed underMIT and installable withbrew 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 installklirr from a prebuilt binary or you can build it yourself.

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

brew install Sajjon/klirr/klirr

You can download signed binaries directly fromGitHub 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 needRust.

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 useklirr 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 dependson 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 useRON ("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 toinit 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 forcurrentperiod (month) instead oflast 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 someperiods 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 anApp Password with your email service, for information onhow to set it up forGmail see here.If you setup klirr to be able to send emails you will be prompted for thisApp Passwordand you will be prompted for an encryption password which will be used to encrypttheApp Password. The encryption password can be anything as long as it adheres tominimum 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 toklirr data init you will now be prompted for a series of inputs required to send your email, including sender email, senderApp 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 theApp Password to be able to send emails.

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

Therefor, klirr employes these best practices to keep yourApp Password safe:

1. Key-Derivation: Klirr does not use your encryption password directly, first it's run through aHash based Key-Derivation-Function using a application uniqueINFO (see 'How Should You Introduce Randomness into HKDF?' section ofthis blog post) and cryptographically secure random generatedSALT, this forms a strong and uniqueEncryptionKey
2. Advanced Encryption: Klirr uses [AES (Advanced Encryption Standard)] encryption with 256 bits strength, encrypted using theEncryptionKey from last step.
3. Zeroisation: Klirr usesZeroisation to eagerly erase sensitive secrets from memory.

You can review how klirr employes these safety measures in theencryption folder of the code.

Interested in development? Seedevelopment guide

Interested in how it works? Seeexplanation 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 theAiooLayout rendered usingEnglish.

1. When run onMacbook Pro M2 Max runningmacOS 15.5 (24F74) using a Klirr binary compiled with--release flag.