Invoice Generator

A simple CLI tool for generating professional invoices as PDFs. Inspired by the unmaintained maaslalani/invoice project. This project fixes the issue where a fraction of a hourly or day rate isn't supported.

Preview

See example-invoice.pdf for a full example of what this tool generates.

Installation

No installation required! This project uses uv which handles dependencies automatically.

If you don't have uv installed, install it first:

curl -LsSf https://astral.sh/uv/install.sh | sh

Then clone this repository and run:

uv run python main.py generate [OPTIONS]

That's it! uv run will automatically install all dependencies on first run. No pip install or virtual environment setup needed.

Quick Start

Want to see what this generates? Run this command to create an example invoice:

uv run python main.py generate \
  --from "ABC Corp" \
  --to "XYZ Corp" \
  --item "Technical Review" --quantity 2 --rate 500 \
  --item "Documentation" --quantity 1 --rate 250 \
  --currency GBP \
  --tax 0.20 \
  --discount 0.10 \
  --note "Thank you for your business!" \
  --output my-invoice.pdf

This will create my-invoice.pdf with multiple line items, tax, discount, and payment methods (if configured).

Basic Usage

Generate a simple invoice:

uv run python main.py generate \
  --from "ABC corp" \
  --to "XYZ corp" \
  --item "Hiring Strategy and related activities" \
  --quantity 0.375 \
  --rate 1000 \
  --currency GBP \
  --note "For debugging purposes."

Multiple Items

Add multiple items to an invoice:

uv run python main.py generate \
  --from "ABC corp" \
  --to "XYZ corp" \
  --item "Hiring Strategy" --quantity 0.375 --rate 1000 \
  --item "Technical Review" --quantity 2 --rate 500 \
  --item "Documentation" --quantity 1 --rate 250 \
  --currency GBP \
  --output invoice.pdf

With Tax and Discount

uv run python main.py generate \
  --from "ABC corp" \
  --to "XYZ corp" \
  --item "Consulting Services" --quantity 1 --rate 1500 \
  --currency GBP \
  --tax 0.20 \
  --discount 0.10 \
  --note "Thank you for your business!"

Available Options

• --from: Your name or company (required)
• --to: Client name or company (required)
• --item: Item description (required, can be specified multiple times)
• --quantity: Item quantity, supports decimals like 0.375 (required, can be specified multiple times)
• --rate: Item rate/price (required, can be specified multiple times)
• --currency: Currency code (default: USD). Supported: USD, GBP, EUR, JPY, CAD, AUD
• --tax: Tax rate as decimal (e.g., 0.13 for 13%)
• --discount: Discount rate as decimal (e.g., 0.15 for 15%)
• --note: Additional note to include
• --invoice-number: Custom invoice number (default: auto-generated)
• --invoice-date: Custom invoice date (default: today)
• --output, -o: Output PDF file path (default: invoice.pdf)
• --no-payment-methods: Exclude payment methods from invoice

Payment Methods

You can optionally include payment information on your invoices (e.g., bank accounts, payment links).

Setup

1. Copy the example configuration file:

cp payment_methods.toml.example payment_methods.toml

2. Edit payment_methods.toml with your actual payment details:

[[bank_account]]
label = "Bank Transfer (UK)"
account_name = "Your Business Name Ltd"
account_number = "12345678"
sort_code = "12-34-56"

[[payment_link]]
label = "Pay Online via Stripe"
url = "https://buy.stripe.com/your-payment-link"

3. The payment_methods.toml file is automatically gitignored to keep your sensitive information safe.

Supported Fields

Bank Account:

• label: Display name (e.g., "Bank Transfer (UK)")
• account_name: Name on the account
• account_number: Account number
• sort_code: UK sort code (optional)
• routing_number: US routing number (optional)
• iban: International bank account number (optional)
• swift_bic: SWIFT/BIC code (optional)

Payment Link:

• label: Display text (e.g., "Pay Online via Stripe")
• url: Payment URL (clickable link in PDF)

You can add multiple bank accounts or payment links by repeating the sections.

Usage

If payment_methods.toml exists, payment methods are automatically included on invoices:

uv run python main.py generate \
  --from "ABC corp" \
  --to "XYZ corp" \
  --item "Consulting Services" --quantity 1 --rate 1500 \
  --currency GBP

To exclude payment methods from a specific invoice:

uv run python main.py generate \
  --from "ABC corp" \
  --to "XYZ corp" \
  --item "Consulting Services" --quantity 1 --rate 1500 \
  --currency GBP \
  --no-payment-methods