@invoicer/cli

Professional invoice generator with timesheet integration. Turn hours into polished PDF invoices and email them automatically—all from the command line.

• ⚡ Fast - Generate invoices in seconds
• 📋 Smart - Auto-fills client details from config
• 🔢 Auto-numbering - Tracks invoice numbers per month
• 📊 Multi-line items - Add services with different rates
• 📧 Email integration - Send via SMTP automatically
• 🌍 Open source - MIT licensed

Installation

npm install -g @invoicer/cli

Then run:

invoicer --help

Quick Start

1. Configure Your Details

Create or edit ~/.invoicer/config.json:

{
  "from": {
    "name": "Your Name",
    "email": "[email protected]",
    "address": "Your Address"
  },
  "client": [
    {
      "name": "Acme Corp",
      "email": "[email protected]",
      "address": "123 Business St",
      "currency": "USD",
      "defaultRate": 50,
      "payPeriodType": "Net 30"
    }
  ]
}

2. Generate an Invoice

invoicer

Interactive prompts will guide you through:

• Client selection
• Invoice number (auto-generated or custom)
• Hours worked
• Hourly rate
• Line item details
• Additional items (optional)

3. Output

PDF is saved to:

./out/{client-name}/Invoice_YYYYMM_01.pdf

Usage

Interactive Mode (Recommended)

invoicer

With CLI Arguments

# Specific month and hours
invoicer --month=2026-02 --hours=160 --rate=75

# Custom invoice number
invoicer --invoice=INV-202602-007

# Specific description for first item
invoicer --desc="Web Development Services"

Generate Current Month's Invoice

invoicer:month

This automatically fills the current month (YYYY-MM).

Features

Invoice Numbering

Auto-Generated Numbers

Format: {prefix}-{YYYYMM}-{sequence}

Example: INV-202602-001, INV-202602-002

Sequence numbers are tracked per month and per client, stored in data/last.json.

Interactive Prompt

When generating an invoice, you'll see:

? Use auto-generated invoice number (INV-202602-007)? (Y/n)

• Press Enter or Y to use the auto-generated number
• Press N to enter a custom number:

  ? Enter custom invoice number: INV-CUSTOM-001

Custom Number Validation:

• Must be 3-30 characters
• Can contain: letters, numbers, hyphens, underscores
• Cannot be empty

CLI Argument Override

Skip the prompt entirely:

invoicer --invoice=INV-202602-007
invoicer --invoice=CUSTOM-INV-001

The CLI argument takes precedence and bypasses the interactive prompt.

Multiple Line Items

Add as many services as needed:

• Description (e.g., "Development", "Design")
• Hours worked
• Hourly rate
• Period (from/to dates)

Running calculation shown after each item.

Email Integration (Optional)

After PDF generation, you'll be prompted:

Send invoice via email? (y/n)

Automatically:

• Attaches PDF
• Uses client email from config
• Professional subject and body
• Error handling if SMTP not configured

Configuration

config.json Structure

{
  "from": {
    "name": "string",           // Your name
    "email": "string",          // Your email
    "address": "string"         // Your business address
  },
  "client": [
    {
      "name": "string",         // Client name
      "email": "string",        // Client email
      "address": "string",      // Client address
      "currency": "string",     // USD, EUR, GBP, etc.
      "defaultRate": 50,        // Default hourly rate
      "payPeriodType": "Net 30" // Payment terms
    }
  ],
  "invoicePrefix": "INV"        // (Optional) Prefix for invoice numbers
}

Environment Variables (.env)

For email sending:

cp .env.example .env

SMTP_HOST=smtp.gmail.com
SMTP_PORT=465
[email protected]
SMTP_PASS=your-app-password
INVOICE_FROM=Your Name <[email protected]>

For Gmail:

1. Enable 2FA on your Google account
2. Create App Password: https://myaccount.google.com/apppasswords
3. Use the 16-character password in SMTP_PASS

Data Files

The CLI stores data locally:

~/.invoicer/
├── config.json              # Your configuration
├── data/
│   ├── last.json           # Last used hours/rate per client
│   ├── timesheet.json      # Time entries (optional)
│   └── active-timer.json   # Timer state (optional)
└── .env                    # SMTP credentials

Output

All PDFs saved to: ./out/{client-name}/

Example structure:

out/
├── Acme Corp/
│   ├── Invoice_202602_001.pdf
│   └── Invoice_202602_002.pdf
└── TechCorp/
    └── Invoice_202602_001.pdf

Development

# Build TypeScript
npm run build

# Run tests
npm test

# Build and run
npm run invoice

# Current month shortcut
npm run invoice:month

Links

• Website: https://invoicer.inbrief.sh/
• GitHub: https://github.com/miladezzat/InvoicePilot
• Issues: https://github.com/miladezzat/InvoicePilot/issues
• Desktop App: https://invoicer.inbrief.sh/ (cross-platform with timer)

License

MIT © 2026 Milad Fahmy

Support

For issues, questions, or suggestions:

• GitHub Issues: https://github.com/miladezzat/InvoicePilot/issues
• Website: https://invoicer.inbrief.sh/