ivce

ivce is a local-first CLI for creating, validating, rendering, and emailing contractor invoices from YAML files.

It is designed for service invoices over explicit date ranges, with optional reimbursable expenses and PDF receipt bundles.

Project status: alpha. The CLI is usable for local invoice workflows, but command options and YAML fields may still change before 1.0.

Requirements

• Python 3.12+
• Typst CLI for PDF rendering. On macOS, install it with brew install typst; for other platforms, see the Typst installation docs.

Install

pip install ivce

The PyPI package is named ivce; it installs the ivce command.

Development Setup

python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

Usage

ivce init
ivce new standard 2026-06
ivce new standard 2026-08 --contractor acme --client globex --reference-profiles
ivce new standard 2026-05 --period-start 2026-05-01 --period-end 2026-05-31
ivce new standard 2026-05 --period-start 2026-05-01 --period-end 2026-05-07 --invoice-number INV-202605-W1 --output workspace/invoices/2026-05-w1.yml
ivce new reimbursement 2026-07
ivce validate workspace/invoices/2026-07.yml
ivce validate private-client/invoices/2026-07.yml --workspace private-client
ivce render workspace/invoices/2026-06.yml
ivce render private-client/invoices/2026-06.yml --workspace private-client
ivce render workspace/invoices/2026-06.yml --template classic
ivce render workspace/invoices/2026-07.yml --with-receipts
ivce email workspace/invoices/2026-06.yml --dry-run
ivce email private-client/invoices/2026-06.yml --workspace private-client --dry-run

Generated PDFs are written to workspace/dist/ by default. Rendered Typst source is written next to the PDF to make debugging template issues straightforward.

Files

• workspace/invoice.yml: contractor/client defaults.
• workspace/contractors/name.yml: reusable contractor profiles.
• workspace/clients/name.yml: reusable client profiles.
• workspace/invoices/YYYY-MM.yml: invoice data with explicit service period dates.
• workspace/receipts/YYYY-MM/: optional receipt attachments.
• workspace/dist/: generated invoice PDFs and receipt bundles.

Receipt Formats

Receipt bundles support pdf, jpg, jpeg, png, heic, and heif receipt files. PDF receipts can contain multiple pages. Image receipts are rendered into the bundle as one receipt page per image. HEIC/HEIF support uses the macOS sips command to convert images locally before bundling.

expenses:
  - date: "2026-07-03"
    description: Train ticket
    amount: "25.00"
    receipt: receipts/2026-07/train-ticket.jpg

Examples

Public fake examples live in examples/sample-data. They cover all built-in templates, profile references, a weekly billing period, and reimbursement display modes.

ivce validate examples/sample-data/invoices/2026-06-modern.yml --workspace examples/sample-data
ivce render examples/sample-data/invoices/2026-06-modern.yml --workspace examples/sample-data

Quickstart with the included sample workspace:

ivce templates list
ivce validate examples/sample-data/invoices/2026-06-modern.yml --workspace examples/sample-data
ivce render examples/sample-data/invoices/2026-06-classic.yml --workspace examples/sample-data --output-dir /tmp/invoice-example

Templates

The CLI ships with three built-in Typst/Jinja2 templates:

• modern: polished default with a branded header and summary band.
• classic: conservative business invoice.
• minimal: sparse type-driven layout for simple retainers.

List templates and render with a specific one:

ivce templates list
ivce render workspace/invoices/2026-06.yml --template modern
ivce render workspace/invoices/2026-06.yml --template-file ./templates/client.typ.j2

Template choices and branding are copied into each generated invoice so old invoices can be rerendered consistently:

template: modern
brand_color: "#1f4e79"
accent_color: "#d9e8f5"
font: New Computer Modern

Contractor and Client Profiles

Invoices can either snapshot contractor/client data or reference reusable profile files.

Reusable profiles live in:

workspace/contractors/acme.yml
workspace/clients/globex.yml

Snapshot mode is the default. It resolves profiles and copies their current values into the invoice YAML:

ivce new standard 2026-08 --contractor acme --client globex

Reference mode keeps the invoice smaller and resolves profiles when validating, rendering, or emailing:

ivce new standard 2026-08 --contractor acme --client globex --reference-profiles

That creates invoice fields like:

contractor_ref: acme
client_ref: globex

Profile references are profile names, not paths. Receipt paths may be absolute or relative to the selected workspace.

Emailing With Gmail

Client email settings live in each invoice under client:

client:
  name: Globex Corporation
  billing_email: accounts@example.com
  cc:
    - manager@example.com
  email_from: you@example.com

Send through Gmail SMTP with a Gmail app password:

export GMAIL_USER="you@example.com"
export GMAIL_APP_PASSWORD="your-app-password"
ivce email workspace/invoices/2026-06.yml

By default, ivce email attaches workspace/dist/YYYY-MM.pdf. Use --pdf or --receipt-bundle to override or add attachments.

For non-default workspaces, pass --workspace to validate, render, and email so referenced profiles, receipts, and default output paths resolve from that workspace.

Privacy and Safety

Invoice data is stored in local YAML files. Generated PDFs, Typst outputs, receipt bundles, and the default workspace/ directory are intended to stay private and are ignored by this repository.

Email is sent only when ivce email is run without --dry-run. Always validate and render an invoice before sending it.

Data Model

Currency is a string field, so USD is supported without hardcoding the tool to USD only. Monetary amounts are decimal values and are formatted with two fractional digits.

Due dates are optional. Set due_date directly on an invoice, or set defaults.payment_terms_days to generate one automatically. If neither is present, the PDF and default email body omit the due date.