finance-cli

name	finance-cli
description	Personal finance CLI for tracking income, expenses, accounts, budgets, and savings goals. Use when the user wants to manage personal finances, track spending, set budgets, or analyze financial data. Install via npx finance-cli. All commands support --json for structured output.
compatibility	Requires Node.js 18+ (for npx). No other dependencies.
metadata	{"author":"przbadu","version":"0.1.0","category":"finance"}

finance-cli

Personal finance management from the terminal. Track accounts, transactions, budgets, savings goals, and generate reports. Designed for both human use and AI agent operation.

Quick Start

# Install and verify
npx finance-cli --version

# Check database status
npx finance-cli status --json

Global Flags

Flag	Description
--json	Output structured JSON instead of human-readable tables
--db-path <path>	Use a specific SQLite database file (default: ~/.finance-cli/finance.db)

Environment variable FINANCE_CLI_DB can also set the database path.

JSON Response Envelope

All --json responses follow this structure:

{
  "status": "success",
  "data": { ... },
  "message": "Human-readable description"
}

On error:

{
  "status": "error",
  "message": "What went wrong"
}

Important: All monetary amounts in JSON are stored as integer cents (e.g., 150000 = $1,500.00). Divide by 100 for display.

Commands Overview

Command	Alias	Description
account create	acc create	Create a new account (bank, cash, credit)
account list	acc list	List all accounts with balances
account edit <id>	acc edit	Edit account name or type
account delete <id>	acc delete	Delete an account
account balance <id>	acc balance	Show computed balance for an account
account transfer	acc transfer	Transfer between accounts
category create	cat create	Create a spending category
category list	cat list	List all categories
category edit <id>	cat edit	Edit a category name
category delete <id>	cat delete	Delete a category
transaction add	tx add	Add income or expense transaction
transaction list	tx list	List transactions with filters
transaction edit <id>	tx edit	Edit a transaction
transaction delete <id>	tx delete	Delete a transaction
budget set		Set monthly budget for a category
budget status		Show budget vs actual spending
budget compare		Compare budget vs actual (detailed)
budget list		List all budgets
budget delete		Delete a budget
goal create		Create a savings goal
goal list		List all goals with progress
goal status <id>		Detailed goal status
goal contribute <id>		Contribute to a goal (creates real transaction)
goal edit <id>		Edit a savings goal
goal delete <id>		Delete a savings goal
recurring create	rec create	Create a recurring transaction
recurring list	rec list	List recurring transactions
recurring edit <id>	rec edit	Edit a recurring transaction
recurring delete <id>	rec delete	Delete a recurring transaction
recurring process	rec process	Process all due recurring transactions
report summary		Monthly financial summary
report categories		Category spending breakdown
report balances		All account balances overview
import csv		Import transactions from CSV file
export csv		Export transactions to CSV
export json		Export all data as structured JSON
backup create		Create SQLite database backup
backup restore		Restore database from backup
status		Show CLI and database status

Common Workflows

1. Set Up Accounts and Track First Expense

# Create a checking account
npx finance-cli account create --name "Checking" --type bank --balance 2500.00 --json

# Create a spending category
npx finance-cli category create --name "Groceries" --json

# Record an expense (use account ID and category ID from above)
npx finance-cli transaction add --type expense --amount 45.50 --account 1 --category 1 --note "Weekly groceries" --json

2. Monthly Budget Check

# Set a budget for a category
npx finance-cli budget set --category 1 --limit 500.00 --month 2026-03 --json

# Check budget status
npx finance-cli budget status --month 2026-03 --json

# Get full monthly summary
npx finance-cli report summary --month 2026-03 --json

3. Import Bank Data

# Preview import (dry run)
npx finance-cli import csv --file bank-export.csv --date-col 0 --amount-col 2 --note-col 1 --default-account 1 --dry-run --json

# Execute import
npx finance-cli import csv --file bank-export.csv --date-col 0 --amount-col 2 --note-col 1 --default-account 1 --json

4. Savings Goal Tracking

# Create a savings goal linked to an account
npx finance-cli goal create --name "Emergency Fund" --target 10000.00 --deadline 2026-12-31 --account 2 --json

# Contribute to goal (creates a real expense transaction)
npx finance-cli goal contribute 1 --amount 500.00 --json

# Check progress
npx finance-cli goal status 1 --json

Reference

For full parameter details, JSON response schemas, and all flag options for every command, see references/commands.md.