CLI Invoice

Generate professional PDF invoices, manage clients, and track payments — entirely from the terminal. Offline, scriptable, and version-control friendly.

$ inv create --client "Acme Corp" --item "Web development" --qty 40 --rate 150
  Invoice INV-0001 created. Total: $6,000.00. Due: Apr 13, 2026.

$ inv export INV-0001
  Exported to ./INV-0001-acme-corp.pdf

Quick Install

npm install -g cli-invoice

Requires Node.js 18 or later.

Quick Start

# 1. Set up your business details
inv init

# 2. Add a client
inv client add --name "Acme Corp" --email "[email protected]"

# 3. Create an invoice
inv create --client "Acme Corp" \
  --item "Web development" --qty 40 --rate 150 \
  --item "Code review" --qty 5 --rate 150

# 4. Export to PDF
inv export INV-0001

# 5. Track payment
inv status INV-0001 sent
inv status INV-0001 paid

Command Reference

Setup

| Command | Description | |---------|-------------| | inv init | Interactive setup wizard for your business profile | | inv config set <key> <value> | Update a config value (e.g., defaults.currency EUR) | | inv config show | Display current configuration |

Client Management

| Command | Description | |---------|-------------| | inv client add --name <n> --email <e> | Add a new client | | inv client list | List all clients with invoice counts and totals | | inv client edit <name> [--email <e>] | Edit client details | | inv client remove <name> | Remove a client |

Invoicing

| Command | Description | |---------|-------------| | inv create --client <name> [options] | Create a new invoice | | inv show <id> | Display full invoice details | | inv edit <id> [options] | Edit a draft invoice | | inv delete <id> | Delete a draft invoice | | inv list [--status <filter>] | List invoices (filter: draft, sent, paid, overdue) | | inv status <id> <status> | Update status (sent, paid) | | inv export <id> | Generate PDF | | inv summary [--year YYYY] | Revenue summary |

Line Items

Line items can be provided in two ways:

Repeated flags:

inv create --client "Acme" \
  --item "Development" --qty 40 --rate 150 \
  --item "Code review" --qty 5 --rate 150

From a JSON file:

inv create --client "Acme" --from items.json

Where items.json is:

[
  { "description": "Development", "quantity": 40, "unit_price": 150 },
  { "description": "Code review", "quantity": 5, "unit_price": 150 }
]

License & Pro

| Command | Description | |---------|-------------| | inv upgrade | Show Pro tier info and pricing | | inv activate <key> | Activate a Pro license key |

Free vs Pro

| Feature | Free | Pro | |---------|------|-----| | Clients | 3 | Unlimited | | Invoices per month | 5 | Unlimited | | PDF export | Yes | Yes | | Revenue summaries | Yes | Yes | | Priority support | -- | Yes |

Data Storage

All data is stored locally in ~/.config/cli-invoice/ (XDG-compliant):

~/.config/cli-invoice/
  config.toml        # Business profile and preferences
  data/
    clients.json     # Client records
    invoices.json    # Invoice records
    counter.json     # Invoice number counter

No cloud. No accounts. Your data stays on your machine.

Environment Variables

| Variable | Description | |----------|-------------| | XDG_CONFIG_HOME | Override config base directory (default: ~/.config) |

No API keys or secrets required.

Development

# Install dependencies
npm install

# Run in development mode
npx tsx bin/inv.ts --help

# Type check
npx tsc --noEmit

# Run tests
npx vitest run

# Build
npx tsup

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes with tests
4. Run npx tsc --noEmit && npx vitest run to verify
5. Submit a pull request

Disclaimer

CLI Invoice is a billing tool, not accounting software. Generated invoices are for informational purposes. Consult a qualified accountant for tax and financial matters. CLI Invoice is not responsible for errors in invoices or their legal enforceability in any jurisdiction.

License

MIT