Finance CLI

A powerful, privacy-focused command-line tool for personal finance tracking

Track expenses, import bank statements, and generate insightful reports—all from your terminal. Your financial data stays on your computer, under your control.

---

✨ Features

• 💰 Track Expenses: Add, view, and manage expenses with detailed categorization
• 📥 Smart Import: Import transactions from CSV/JSON with automatic format detection
• 📊 Rich Reports: Category summaries, monthly trends, and top expense analysis
• 📤 Easy Export: Export your data to CSV or JSON for backups or spreadsheets
• 🔒 Privacy-First: All data stored locally in SQLite—no cloud, no tracking
• 🎨 Beautiful CLI: Color-coded output with ASCII charts and tables
• 🧪 Well-Tested: 91 passing tests ensure reliability

---

🚀 Quick Start

Get up and running in 5 minutes:

# Install
git clone https://github.com/PSthelyBlog/finance-cli.git
cd finance-cli
npm install && npm run build

# Add your first expense
npm run cli -- add -a 5.50 -c coffee --description "Morning latte"

# View your expenses
npm run cli -- list

# See spending breakdown
npm run cli -- report category

➡️ Full Quick Start Guide - Get started in 5 minutes

---

📖 Documentation

• Quick Start Guide - Fast setup for new users (5 min read)
• User Guide - Comprehensive documentation (30 min read)
• Architecture Review - Technical architecture (for developers)
• Development Guide - Patterns and anti-patterns (for contributors)

---

💡 Common Use Cases

Daily Expense Tracking

finance add -a 12.50 -c lunch --description "Burrito bowl"
finance add -a 45.99 -c groceries --description "Weekly shopping"

Import Bank Statements

# Preview first
finance import bank_statement.csv --dry-run

# Import transactions
finance import bank_statement.csv --date-format US --skip-duplicates

Monthly Review

# Category breakdown
finance report category --from 2025-10-01 --to 2025-10-31

# Monthly trends
finance report monthly --limit 12

# Top expenses
finance report top --limit 10

Export for Tax Season

finance export 2025_expenses.csv --from 2025-01-01 --to 2025-12-31

---

🎯 Key Commands

Command	Purpose	Example
add	Add an expense	finance add -a 50 -c groceries
list	View expenses	finance list --category groceries --from 2025-10-01
delete	Remove expense	finance delete a3d5e7f9
import	Import CSV/JSON	finance import bank_statement.csv
report category	Spending by category	finance report category
report monthly	Monthly trends	finance report monthly --limit 6
report top	Largest expenses	finance report top --limit 10
export	Export data	finance export backup.csv

See all options: finance <command> --help

---

🛠️ Installation

Requirements

• Node.js 18.0.0 or higher
• npm or yarn

Setup

# Clone repository
git clone https://github.com/PSthelyBlog/finance-cli.git
cd finance-cli

# Install dependencies
npm install

# Build
npm run build

# Verify installation
npm run cli -- --help

Optional: Global Installation

npm link
# Now use "finance" directly instead of "npm run cli --"
finance --help

---

📊 Example Output

Category Report

=== Category Summary ===

Groceries     ████████████████████ 45.5%
Utilities     ████████████ 25.2%
Dining        ██████ 15.3%
Transport     ████ 10.0%
Other         █ 4.0%

Total: $2,898.66

Monthly Trends

=== Monthly Spending Report ===

Trend: ▁▃▅▇█▇▅▃▂

October 2025
Total: $2,898.66 | Transactions: 73
Top categories:
  Groceries       $1,234.56 ████████████████████ 42.5%
  Utilities         $689.90 ████████████ 23.8%
  Coffee            $523.50 ████████ 18.0%

Top Expenses

=== Top 10 Expenses ===

#  | Date       | Amount       | Category     | Description
-------------------------------------------------------------
1. | 2025-10-15 | $1,200.00   | rent         | Monthly rent 🥇
2. | 2025-10-20 | $450.00     | insurance    | Car insurance 🥈
3. | 2025-10-08 | $289.99     | shopping     | Winter coat 🥉

---

🔐 Privacy & Security

• ✅ Local-only: All data stored on your computer
• ✅ No tracking: No analytics or telemetry
• ✅ No cloud: No remote servers or accounts
• ✅ Open source: Audit the code yourself
• ✅ Encrypted backups: Use OS encryption for backups

Your data location: ~/.finance-cli/data.db

---

🧪 Development

Run Tests

npm test                 # Run all tests
npm run test:watch       # Watch mode
npm run test:coverage    # Coverage report

Test Status: 91 passing tests

• Integration tests with real database
• Unit tests for all utilities
• Fixture-based CSV import tests

Architecture

CLI Layer (Commander.js)
  ↓
Service Layer (Business Logic)
  ↓
Data Layer (SQLite + Models)

See Architecture Review for detailed analysis.

---

🤝 Contributing

Contributions welcome! Please read:

1. Development Guide - Patterns and anti-patterns
2. Architecture Review - System design
3. Submit issues for bugs or feature requests
4. Submit pull requests with tests

Development Patterns

See CLAUDE.md for critical patterns:

• Date handling (UTC storage, date-fns)
• Currency handling (integer cents)
• Validation (early validation, specific errors)
• Error handling (context-rich errors)

---

📝 Roadmap

Current: v0.1.0 - Core functionality complete

Planned:

• 📊 Budget tracking with alerts
• 🔄 Recurring expense templates
• 🏷️ Smart category suggestions
• 📈 Advanced visualizations
• 💱 Multi-currency support with conversion
• 📱 Mobile companion app
• ☁️ Optional cloud sync

---

🐛 Troubleshooting

Common Issues

Import not working?

# Try specifying date format explicitly
finance import file.csv --date-format US  # or EU or ISO

# Preview first
finance import file.csv --dry-run

Command not found?

# Use npm run cli instead
npm run cli -- add -a 10 -c lunch

# Or link globally
npm link

More help: See User Guide - Troubleshooting

---

📄 License

MIT License - see LICENSE file for details

---

🙏 Acknowledgments

Built with:

• Commander.js - CLI framework
• better-sqlite3 - SQLite database
• date-fns - Date utilities
• PapaParse - CSV parsing
• chalk - Terminal colors
• inquirer - Interactive prompts

---

📬 Contact

• Issues: GitHub Issues
• Discussions: GitHub Discussions

---

Take control of your finances. Start tracking today.

Quick Start • User Guide • GitHub