npm package: @invoicer/cli
Description: Professional invoice generator with timesheet integration and CLI support
Author: Milad Fahmy
Latest version: 2.1.2

# @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

```bash
npm install -g @invoicer/cli
```

Then run:
```bash
invoicer --help
```

## Quick Start

### 1. Configure Your Details

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

```json
{
  "from": {
    "name": "Your Name",
    "email": "you@example.com",
    "address": "Your Address"
  },
  "client": [
    {
      "name": "Acme Corp",
      "email": "billing@acme.com",
      "address": "123 Business St",
      "currency": "USD",
      "defaultRate": 50,
      "payPeriodType": "Net 30"
    }
  ]
}
```

### 2. Generate an Invoice

```bash
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)

```bash
invoicer
```

### With CLI Arguments

```bash
# 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

```bash
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:
```bash
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

```json
{
  "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:

```bash
cp .env.example .env
```

```
SMTP_HOST=smtp.gmail.com
SMTP_PORT=465
SMTP_USER=your@gmail.com
SMTP_PASS=your-app-password
INVOICE_FROM=Your Name <your@gmail.com>
```

**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

```bash
# 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/