InvoiceNinja Summary CLI

A command-line tool to analyze and summarize uninvoiced task times from your self-hosted InvoiceNinja instance. This tool provides the aggregations that the InvoiceNinja GUI lacks, specifically:

• Uninvoiced task time by project - See total hours for each project that haven't been invoiced yet
• Uninvoiced task time by date range - Filter and analyze task times within specific time periods

Features

• 🔍 Fetch uninvoiced tasks from your InvoiceNinja instance via API
• 📊 Aggregate by project - See total time and task count per project
• 📅 Date range filtering - Filter by specific date ranges or number of days back
• 📁 Project filtering - Focus on specific projects
• 🎨 Multiple output formats - Table (default), JSON, or CSV
• ⚡ Built with Bun - Fast TypeScript runtime

Prerequisites

• Bun installed on your system
• Self-hosted InvoiceNinja instance with API access
• InvoiceNinja API token

Installation

1. Clone or download this project

2. Install dependencies:

   bun install
   

3. Configure environment variables:

   cp .env.example .env
   

   Edit .env and set your InvoiceNinja instance details:

   INVOICE_NINJA_URL=https://your-invoice-ninja-instance.com
   INVOICE_NINJA_TOKEN=your_api_token_here
   DEFAULT_DAYS_BACK=30
   

Getting Your API Token

1. Log into your InvoiceNinja instance
2. Go to Settings → Account Management → Integrations → API Tokens
3. Create a new token with appropriate permissions
4. Copy the token to your .env file

Usage

Basic Summary

Show uninvoiced task time summary for all projects:

bun start summary

Date Range Filtering

Last N days:

bun start summary --days 7          # Last 7 days
bun start summary --days 30         # Last 30 days

Specific date range:

bun start summary --from 2024-01-01 --to 2024-01-31

From a specific date:

bun start summary --from 2024-01-01

Project Filtering

Filter by specific project:

bun start summary --project PROJECT_ID

List all projects to find IDs:

bun start projects

Output Formats

Table format (default):

bun start summary

JSON format:

bun start summary --format json

CSV format:

bun start summary --format csv

Combining Options

# Last 14 days for a specific project in JSON format
bun start summary --days 14 --project abc123 --format json

# Date range for all projects in CSV format
bun start summary --from 2024-01-01 --to 2024-01-31 --format csv

Commands

summary

Analyze and display uninvoiced task time aggregations.

Options:

• -d, --days <days> - Number of days back to include
• -f, --from <date> - Start date (YYYY-MM-DD format)
• -t, --to <date> - End date (YYYY-MM-DD format)
• -p, --project <id> - Filter by specific project ID
• --format <format> - Output format: table, json, or csv (default: table)

projects

List all projects with their IDs and names.

Example Output

Table Format

📊 Uninvoiced Task Time Summary
================================

By Project:
  Project ABC: 15h 30m (8 tasks)
  Project XYZ: 22h 45m (12 tasks)
  No Project: 3h 15m (2 tasks)

📈 Total: 41h 30m (22 tasks)
📅 Date range: Last 30 days (2024-01-01 to 2024-01-31)

JSON Format

{
  "totalTime": 149400,
  "projectSummary": {
    "Project ABC": {
      "totalTime": 55800,
      "taskCount": 8
    },
    "Project XYZ": {
      "totalTime": 81900,
      "taskCount": 12
    }
  },
  "taskCount": 22
}

CSV Format

Project,Hours,Minutes,Tasks
"Project ABC",15,30,8
"Project XYZ",22,45,12
"No Project",3,15,2

Development

Run in development mode with auto-reload:

bun run dev

Run with specific command:

bun run src/index.ts summary --days 7

Troubleshooting

Common Issues

"Missing required environment variables"

• Make sure .env file exists and contains INVOICE_NINJA_URL and INVOICE_NINJA_TOKEN

"API request failed: 401 Unauthorized"

• Check that your API token is correct and has proper permissions
• Verify the InvoiceNinja URL is correct (include https://)

"API request failed: 404 Not Found"

• Ensure your InvoiceNinja instance URL is correct
• Check that the API endpoints are available (some older versions may differ)

"No uninvoiced tasks found"

• Verify that you have tasks with time entries that haven't been invoiced
• Try expanding the date range with --days option
• Check if tasks are properly recorded in InvoiceNinja

Debug Mode

For more detailed error information, you can check the network requests and responses by modifying the client code or running with additional logging.

API Compatibility

This tool is designed to work with InvoiceNinja v5.x API. It may require adjustments for other versions.

Contributing

Feel free to submit issues and enhancement requests!

License

MIT License - feel free to modify and use as needed.