Invoice Toolkit

This project is a toolkit for generating invoices and letters from simple configuration files. While there are many tools and templates out there, I found it difficult to find a simple template that I could easily modify to my needs. The goal of this project is to provide simple templates that can be easily modified to suit also your needs.

Preview

Letter Template	Invoice Template (no VAT)	Invoice Template (with VAT)

Invoice and Letter Template

Features:

• Invoice Template
• Letter Template
• Migrate to typst for faster rendering
• Type validation using pydantic
• Support schema validation for VSCode (schemas are located in the schema directory)
• QR Code generation for bank transfer using tiaoma
• Support multiple pages for invoices
• Easy interaction using just
• Python dependency management using uv
• Keep track of the amount of invoices (using a csv file)
• Open Thunderbird with the generated pdf as attachment
  • Requires Thunderbird to be installed as a flatpak package
  • Additionally, you need to allow Thunderbird to access the output directory
  • You can disable this feature by setting settings.open_mail_client to false in config.yml

Getting Started

You can either just clone this repository or create a fork of it. First of all, you need to install the dependencies using uv (if you haven't heard of it, you should google it, and follow a tutorial on how to use it). Additionally I suggest using just.

For initial testing, I created some example configuration files. If you want to customize the templates to your needs, see examples/README.md.

Following, you should be able to create your first invoice or letter:

just invoice [invoice-path]
just letter [letter-path]

Omit the path argument to generate the bundled example. Run just --list to see all available commands.

Usage

The toolkit can be used directly via uvx without cloning the repository:

Generating invoices

uvx --extra cli invoice-toolkit toolkit invoice \
    --invoices invoices.yml \
    --config config.yml \
    --customer customer.csv

Generating letters

uvx --extra cli invoice-toolkit toolkit letter letter.md --config config.yml

Generating JSON schemas

uvx --extra cli invoice-toolkit toolkit schemas

YAML schema validation

For IDE autocompletion and validation, add a schema comment as the first line of your YAML files. You can reference the schemas locally or via GitHub:

# Local (cloned repo)
# yaml-language-server: $schema=../../schema/config.json

# GitHub (without cloning)
# yaml-language-server: $schema=https://raw.githubusercontent.com/felixhoffmnn/invoice-toolkit/main/schema/config.json

The schema/ directory contains pre-generated JSON schemas for all configuration models (config.json, invoices.json, customer.json). These are compatible with the YAML Language Server used by VS Code and other editors.

Available schemas:

Schema	Local path	GitHub URL
Config	schema/config.json	https://raw.githubusercontent.com/felixhoffmnn/invoice-toolkit/main/schema/config.json
Invoices	schema/invoices.json	https://raw.githubusercontent.com/felixhoffmnn/invoice-toolkit/main/schema/invoices.json
Customer	schema/customer.json	https://raw.githubusercontent.com/felixhoffmnn/invoice-toolkit/main/schema/customer.json

License

This project is licensed under the GNU GPLv3 License - see the COPYING file for details.

The invoice template is inspired by a template from Selfnet e.V..