---
name: invoice-gen
description: Generate professional invoice PDFs from a JSON spec or CLI args. Includes header (logo + business info), bill-to block, itemized line table with quantity/rate/total, subtotal/tax/grand-total summary, due date, payment instructions, and optional notes. Built-in clean editorial style. Pure Python via reportlab — no LaTeX, no Office. Use when the user asks for an invoice PDF, billing statement, freelance invoice, or wants a one-shot "make me an invoice for $X" tool.
---


# invoice-gen

Minimal, clean invoice PDF generator. Drop in a JSON spec or pass CLI args; get a polished editorial-style PDF you can send to a client.

## Quick start (JSON)

```bash
python3 scripts/gen.py --from-json invoice.json --output out.pdf
```

`invoice.json`:

```json
{
  "number": "INV-001",
  "date": "2026-04-25",
  "due_date": "2026-05-25",
  "from": {
    "name": "Studio X",
    "email": "hi@studiox.co",
    "address": "123 Main St\nBrooklyn, NY 11211"
  },
  "to": {
    "name": "Client Y",
    "email": "ap@clienty.com",
    "address": "500 5th Ave\nNew York, NY 10110"
  },
  "items": [
    {"description": "Logo design", "quantity": 1, "rate": 1500},
    {"description": "Brand guidelines (hours)", "quantity": 8, "rate": 150}
  ],
  "tax_rate": 0.08875,
  "currency": "USD",
  "notes": "Net 30. Wire to ACH 021000021 / acct 12345678. Thanks!"
}
```

## Quick start (CLI args)

```bash
python3 scripts/gen.py \
  --number INV-002 \
  --date 2026-04-25 \
  --due 2026-05-25 \
  --from-name "Studio X" --from-email hi@studiox.co \
  --to-name "Client Y" --to-email ap@clienty.com \
  --items "Logo design|1|1500;Brand guidelines|8|150" \
  --tax-rate 0.08875 \
  --currency USD \
  --notes "Net 30. Thanks!" \
  --output out.pdf
```

## Flags

| Flag | Description |
|------|-------------|
| `--from-json PATH` | Load full invoice spec from JSON. Overrides other flags. |
| `--number STR` | Invoice number (e.g. `INV-001`) |
| `--date YYYY-MM-DD` | Issue date (defaults to today) |
| `--due YYYY-MM-DD` | Due date |
| `--from-name`, `--from-email`, `--from-address` | Sender block |
| `--to-name`, `--to-email`, `--to-address` | Bill-to block |
| `--items "desc\|qty\|rate;desc\|qty\|rate"` | Line items, semicolon-separated |
| `--tax-rate FLOAT` | e.g. `0.08` for 8%. Default 0. |
| `--currency STR` | ISO code, default `USD` |
| `--notes STR` | Footer notes / payment instructions |
| `--output PATH` | Output PDF path (default `invoice.pdf`) |

## Layout

- Top bar: `INVOICE` wordmark + invoice number + issue date
- Left: From block (name, email, address)
- Right: Bill-to block
- Itemized table: Description | Qty | Rate | Amount
- Summary block (right-aligned): Subtotal, Tax, Total
- Due date callout
- Notes block at bottom

## Dependencies

Auto-installs `reportlab` on first run.