invoicr

A TypeScript CLI tool that generates DOCX and PDF invoices from JSON configuration files, with optional email integration for macOS.

Features

• Generate professional invoices in DOCX and PDF formats
• Multi-language support (German & English)
• Flexible billing: hourly, daily, or fixed rates
• Multiple currencies (EUR, USD)
• Email drafts with PDF attachment (macOS Mail.app)
• Separate email language from invoice language
• Interactive client creation wizard
• NEW in 1.6.0:
  • Bulk generation via CLI args: invoicr-bulk acme:40 other:10
• In 1.5.0:
  • ESM modules (modern JavaScript module system)
  • Unit tests with Vitest (217 tests, 96% coverage)
• In 1.4.0:
  • Custom invoice templates (default, minimal, detailed)
  • invoicr-export - Export invoice history to CSV/JSON
  • invoicr-bulk - Generate multiple invoices at once
• In 1.3.0:
  • Multiple line items per invoice
  • Tax/VAT calculation with configurable rates
  • Logo support in invoice header
• In 1.2.0:
  • invoicr-init - Interactive setup wizard for new workspaces
  • invoicr-list - List all available clients
  • --dry-run - Preview invoice without generating files
  • Due date calculation based on payment terms
  • Invoice history tracking (history.json per client)
  • Config validation with helpful error messages

Prerequisites

• Node.js (v18+)
• LibreOffice (for PDF conversion)
• Mail.app (for email feature, macOS only)

# Install LibreOffice on macOS
brew install --cask libreoffice

Installation

From npm (global)

npm install -g invoicr

From source

git clone https://github.com/LeanerCloud/invoicr.git
cd invoicr
npm install
npm run build
cp provider.example.json provider.json  # Edit with your details

Usage

Generate Invoice

# If installed globally
invoicr <client-folder> <quantity> [options]

# If running from source
npm run invoice -- <client-folder> <quantity> [options]

Options

Option	Description
--month=MM-YYYY	Generate invoice for a specific month
--email	Create email draft in Mail.app with PDF attached
--test	Send email to provider instead of client (for testing)
--dry-run	Preview invoice details without generating files

Examples

# Generate invoice using example templates (no client setup needed)
invoicr acme-hourly 40        # 40 hours @ $150/hr
invoicr acme-daily 5          # 5 days @ €1,200/day
invoicr acme-fixed 15000      # Fixed $15,000

# Generate invoice for a past month
invoicr acme-hourly 80 --month=10-2025

# Generate invoice and create email draft
invoicr acme-daily 2 --email

# Test email (sends to your email instead of client)
invoicr acme-daily 2 --email --test

# Preview invoice without generating files
invoicr acme-hourly 40 --dry-run

# Use your own client (after creating with invoicr-new)
invoicr myclient 10

Initialize Workspace

Set up a new invoicing workspace with provider details:

invoicr-init

This interactive wizard will:

1. Create provider.json with your business details
2. Optionally create a sample client

List Clients

View all available clients in your workspace:

invoicr-list

Create New Client

# If installed globally
invoicr-new
invoicr-new --from=acme-hourly  # Use example template
invoicr-new --from=myclient     # Use existing client as template

# If running from source
npm run new-client
npm run new-client -- --from=acme-daily

Available Templates

Template	Billing	Description
acme-hourly	Hourly	USD, English, 30-day payment terms
acme-daily	Daily	EUR, German invoice + English email, translated descriptions
acme-fixed	Fixed	USD, custom bank account, payment upon receipt
acme-multiservice	Mixed	Multiple line items with tax (1.3.0+)
acme-minimal	Hourly	Minimal template style (1.4.0+)
acme-detailed	Daily	Detailed template style (1.4.0+)

The command will prompt for:

• Client folder name
• Company name & address
• Invoice/email language
• Invoice prefix
• Project reference (optional)
• Service description, billing type, rate, currency
• Payment terms
• Bank details (optional)
• Email recipients (To/CC)

Workspace Layout

your-workspace/
├── provider.json           # Your business details
├── clients/
│   └── <client>/
│       ├── <client>.json   # Client configuration
│       └── history.json    # Invoice history (auto-generated)
└── invoices/               # Generated invoices (DOCX/PDF)

Configuration

provider.json

Copy provider.example.json to provider.json and fill in your business details:

{
  "name": "Your Name",
  "address": {
    "street": "Street 123",
    "city": "12345 City, Country"
  },
  "phone": "+49 123 456789",
  "email": "[email protected]",
  "bank": {
    "name": "Bank Name",
    "iban": "DE00 0000 0000 0000 0000 00",
    "bic": "BICCODE"
  },
  "taxNumber": "12/345/67890",
  "vatId": "DE123456789"
}

Client JSON

Create a folder for each client with a JSON file inside (e.g., acme/acme.json). See examples/ for complete templates.

Hourly Billing (examples/acme-hourly.json)

{
  "name": "Acme Corp",
  "address": {
    "street": "123 Main Street",
    "city": "New York, NY 10001"
  },
  "language": "en",
  "invoicePrefix": "AC",
  "nextInvoiceNumber": 1,
  "projectReference": "Website Redesign",
  "service": {
    "description": "Frontend Development Services",
    "billingType": "hourly",
    "rate": 150,
    "currency": "USD"
  },
  "paymentTermsDays": 30,
  "email": {
    "to": ["Jane Smith <[email protected]>"],
    "cc": ["Accounting <[email protected]>"]
  }
}

Daily Billing with Translated Descriptions (examples/acme-daily.json)

{
  "name": "Acme GmbH",
  "address": {
    "street": "Musterstraße 42",
    "city": "10115 Berlin"
  },
  "language": "de",
  "emailLanguage": "en",
  "invoicePrefix": "ACM",
  "nextInvoiceNumber": 1,
  "projectReference": "Cloud Migration Project",
  "service": {
    "description": {
      "de": "Cloud-Infrastruktur & DevOps Beratung",
      "en": "Cloud Infrastructure & DevOps Consulting"
    },
    "billingType": "daily",
    "rate": 1200,
    "currency": "EUR"
  },
  "paymentTermsDays": 14,
  "email": {
    "to": ["Max Mustermann <[email protected]>"],
    "cc": ["Buchhaltung <[email protected]>"]
  }
}

Fixed Amount with Custom Bank (examples/acme-fixed.json)

{
  "name": "Acme Industries Ltd",
  "address": {
    "street": "100 Business Park Drive",
    "city": "London, EC1A 1BB"
  },
  "language": "en",
  "invoicePrefix": "AI",
  "nextInvoiceNumber": 1,
  "projectReference": "Mobile App Development - Phase 2",
  "service": {
    "description": "Software Development - Milestone Payment",
    "billingType": "fixed",
    "rate": 0,
    "currency": "USD"
  },
  "bank": {
    "name": "Revolut",
    "iban": "GB00 REVO 0000 0000 0000 00",
    "bic": "REVOGB21"
  },
  "paymentTermsDays": null,
  "email": {
    "to": ["John Doe <[email protected]>"]
  }
}

Notes:

• emailLanguage: Use a different language for emails than the invoice
• service.description: Can be a string or an object with de/en translations
• bank: Optional. Overrides provider's bank details for this client
• paymentTermsDays: Set to null for "payable upon receipt"

Configuration Options

Field	Description
language	Invoice language: "de" (German) or "en" (English)
emailLanguage	Optional. Email language if different from invoice
invoicePrefix	Prefix for invoice numbers (e.g., "AC" for AC-1, AC-2)
billingType	"hourly", "daily", or "fixed"
currency	"EUR" or "USD"
rate	Rate per hour/day (ignored for fixed billing)
bank	Optional. Overrides provider's bank details
paymentTermsDays	Optional. If null, shows "payable upon receipt"
projectReference	Optional. Shown in invoice details
service.description	String or object with de/en translations
email.to	Array of recipient email addresses
email.cc	Optional. Array of CC email addresses
lineItems	Optional. Array of line items (1.3.0+). Overrides single-service mode
taxRate	Optional. Tax rate as decimal (e.g., 0.19 for 19%) (1.3.0+)
template	Optional. Invoice template: "default", "minimal", or "detailed" (1.4.0+)

Multiple Line Items (1.3.0+)

For invoices with multiple services, use the lineItems array instead of the CLI quantity:

{
  "name": "Multi-Service Client",
  "lineItems": [
    { "description": "Development", "quantity": 40, "rate": 150, "billingType": "hourly" },
    { "description": "Code Review", "quantity": 8, "rate": 175, "billingType": "hourly" },
    { "description": "Setup Fee", "quantity": 500, "rate": 1, "billingType": "fixed" }
  ],
  "taxRate": 0.19
}

When lineItems is present, the CLI quantity is ignored and all line items from the config are used.

Logo Support (1.3.0+)

Add a logo to your invoices by specifying logoPath in provider.json:

{
  "name": "Your Company",
  "logoPath": "logo.png"
}

Supported formats: PNG, JPG, GIF, BMP. The path can be absolute or relative to the current working directory.

Invoice Templates (1.4.0+)

Choose from three invoice styles by setting template in your client config:

Template	Description
default	Full-featured layout with all details (default)
minimal	Clean, compact design with inline info
detailed	Extended layout with emphasized payment info

{
  "name": "My Client",
  "template": "minimal"
}

Export History (1.4.0+)

Export your invoice history to CSV or JSON:

invoicr-export                           # Export all to CSV (stdout)
invoicr-export --format=json             # Export all to JSON
invoicr-export --client=acme-hourly      # Export specific client
invoicr-export --output=invoices.csv     # Export to file

Bulk Generation (1.4.0+)

Generate multiple invoices at once using CLI arguments or a config file:

# CLI mode (1.6.0+)
invoicr-bulk acme:40 other:10
invoicr-bulk acme:40 other:10 --month=11-2025 --email
invoicr-bulk acme:40 other:10 --dry-run

# Config file mode
invoicr-bulk batch.json
invoicr-bulk batch.json --dry-run

Config file format:

{
  "invoices": [
    { "client": "acme-hourly", "quantity": 40 },
    { "client": "acme-daily", "quantity": 5, "month": "10-2025" },
    { "client": "acme-fixed", "quantity": 15000, "email": true }
  ]
}

Each invoice entry supports:

• client (required): Client folder name
• quantity (required): Quantity/amount for invoice
• month (optional): Billing month (MM-YYYY format)
• email (optional): Create email draft (true/false)

Email Feature

When using the --email flag, the tool creates a draft email in Mail.app with:

• From: Provider's email address
• To/CC: Pre-filled from client config (supports "Name " format)
• Subject: Invoice number and month (e.g., "Invoice AC-1 (November 2025) - Your Name")
• Body: Localized template with service description and amount
• Attachment: PDF invoice

Email Languages

Set emailLanguage in the client config to use a different language for emails than the invoice. This is useful when:

• Invoice must be in German (for accounting)
• Client prefers English communication

Test Mode

Use --test to send the email to yourself (provider email) instead of the client:

invoicr acme-daily 2 --email --test

The subject will be prefixed with [TEST].

Output

Invoices are generated in the client's folder:

• Rechnung_AC-1_November_2025.docx / .pdf (German)
• Invoice_AC-1_November_2025.docx / .pdf (English)

The nextInvoiceNumber in the client JSON is automatically incremented after each invoice.

Development

# Run invoice without building (using tsx)
npm run dev -- acme-hourly 8

# Build TypeScript
npm run build

# Run tests
npm test

# Run tests in watch mode
npm run test:watch

Scripts

Script	Description
npm run build	Compile TypeScript to JavaScript
npm run invoice	Generate an invoice
npm run new-client	Create a new client interactively
npm run init	Initialize a new workspace
npm run list	List available clients
npm run dev	Run invoice.ts directly with tsx
npm test	Run unit tests with Vitest
npm run test:watch	Run tests in watch mode

License

MIT

Shameless Plug

This tool is brought to you by LeanerCloud. We help companies reduce their AWS costs using a mix of services and tools such as AutoSpotting.

Are you a freelancer with clients running workloads on AWS and notice cost optimization opportunities unrelated to your work? If you refer a client to us, we'll give you 50% of our first cost optimization invoice from that client.

Get in touch!