xpense 0.3.0

A beautiful CLI expense and income tracker

xpense

A beautiful CLI expense and income tracker with gorgeous terminal output.

Features

• Track expenses and income with ease
• Beautiful reports with category breakdowns
• Calculate balance (income - expenses)
• Color-coded output (green for income, red for expenses)
• Simple CSV storage at ~/.xpense/expenses.csv
• Powerful filtering by month and category
• Export transactions to CSV

Installation

From PyPI (recommended)

pip install xpense

From source

# Clone the repository
git clone https://github.com/Gabriel-Rockson/xpense.git
cd xpense

# Install with uv (recommended)
uv sync

# Or install with pip
pip install -e .

Usage

Add Transactions

Add an expense (default behavior):

# Quick syntax - amount, category, optional note
xpense 20 transport "to the office"
xpense 45.50 food "lunch at restaurant"
xpense 100 utilities "electricity bill"

Add income:

# Use 'add' subcommand for income
xpense add 2000 salary "from day job"
xpense add 500 freelance "web design project"

View Transactions

List all transactions:

xpense list

Filter by month:

xpense list --month 3  # March transactions

Filter by category:

xpense list --category food

Filter by type:

xpense list --type expense  # Only expenses
xpense list --type income   # Only income

Combine filters:

xpense list --month 3 --category food --type expense

Calculate Totals

Total of all transactions:

xpense total

Total for a specific month:

xpense total --month 3

Total for a specific category:

xpense total --category food

Check Balance

Balance (income - expenses):

xpense balance

Monthly balance:

xpense balance --month 3

Generate Reports

Detailed category breakdown:

xpense report

Monthly report:

xpense report --month 3

List Categories

All categories:

xpense categories

Only expense categories:

xpense categories --type expense

Only income categories:

xpense categories --type income

Export Data

Export to default filename (xpense_YYYYMMDD.csv):

xpense export

Export to custom file:

xpense export --output my_transactions.csv

Data Structure

Transactions are stored in CSV format at ~/.xpense/expenses.csv with the following structure:

date,type,amount,category,note
2025-09-29 10:30:00,expense,20.0,transport,to the office
2025-09-29 12:15:00,income,2000.0,salary,from day job

Fields

• date: ISO format timestamp (YYYY-MM-DD HH:MM:SS)
• type: "income" or "expense"
• amount: Positive float value
• category: Lowercase with underscores (automatically normalized)
• note: Optional description

Examples

# Track daily expenses
xpense 5 coffee "morning latte"
xpense 12.50 lunch "sandwich and drink"
xpense 50 gas "fuel for car"

# Record income
xpense add 3000 salary "monthly paycheck"
xpense add 150 freelance "side project"

# Check current month's balance
xpense balance --month $(date +%-m)

# Generate monthly report
xpense report --month $(date +%-m)

# See all food expenses
xpense list --category food --type expense

# Export data for analysis
xpense export --output transactions_2025.csv

Color Coding

• Green: Income (positive transactions)
• Red: Expenses (negative transactions)
• Cyan: Categories and headers

Project Structure

xpense/
├── pyproject.toml          # Project configuration
├── README.md               # This file
├── LICENSE                 # MIT License
└── xpense/
    ├── __init__.py         # Package initialization
    ├── main.py             # CLI entry point
    ├── cli.py              # Typer commands
    ├── storage.py          # CSV operations
    └── display.py          # Rich formatting

Development

# Install development dependencies
uv sync

# Run the CLI locally
uv run xpense --help

# Run with Python
python -m xpense.main

License

MIT License - See LICENSE file for details