Cashflow

CashFlow

CashFlow is a multi-purpose utility tool for tracking and managing data entries from the terminal. It provides a simple log-based system for adding, listing, searching, and exporting entries with timestamped records.

Commands

| Command | Description | |---------|-------------| | cashflow run | Execute the main function with given arguments | | cashflow config | Show configuration file location (config.json) | | cashflow status | Show current status (ready/not ready) | | cashflow init | Initialize the data directory | | cashflow list | List all entries in the data log | | cashflow add | Add a new dated entry to the data log | | cashflow remove | Remove an entry | | cashflow search | Search entries (case-insensitive grep) | | cashflow export | Export all data to stdout | | cashflow info | Show version and data directory path | | cashflow help | Show all available commands | | cashflow version | Show version number |

How It Works

CashFlow uses a flat-file approach. All entries are stored in data.log as dated lines (YYYY-MM-DD ). Every command also appends a timestamped record to history.log for auditing.

Data Storage

All data is stored locally in ~/.local/share/cashflow/ by default:

Override the storage location by setting the CASHFLOW_DIR environment variable:

export CASHFLOW_DIR="$HOME/my-data/cashflow"

Alternatively, XDG_DATA_HOME is respected if CASHFLOW_DIR is not set.

Requirements

When to Use

1. Quick data logging — Use cashflow add to rapidly log entries (expenses, tasks, notes) with automatic date stamps 2. Reviewing stored entries — Run cashflow list to see everything you've logged, or cashflow search to find specific entries 3. Exporting data for analysis — Use cashflow export > data.csv to dump all entries for import into spreadsheets or other tools 4. Project initialization — Run cashflow init to set up the data directory on a new machine or project 5. Checking tool status — Use cashflow status and cashflow info to verify the tool is ready and see version/path information

Examples

# Initialize the data directory
cashflow init
Add entries
cashflow add "Monthly rent payment 2500"
cashflow add "Freelance invoice received 8000"
cashflow add "Grocery shopping 350"
List all entries
cashflow list

# Search for specific entries
cashflow search rent
cashflow search invoice
Export data to a file
cashflow export > my-records.txt
Check status and info
cashflow status
cashflow info

# Run a custom operation
cashflow run process-monthly
View configuration location
cashflow config
Remove an entry
cashflow remove "old entry"
Show version
cashflow version

Output

All command output goes to stdout. The history log is always written to $DATA_DIR/history.log. Redirect output as needed:

cashflow list > all-entries.txt
cashflow export | grep "2026-03" > march-data.txt

Configuration

| Variable | Purpose | Default | |----------|---------|---------| | CASHFLOW_DIR | Override data/config directory | ~/.local/share/cashflow/ | | XDG_DATA_HOME | Fallback base directory | ~/.local/share/ |

Powered by BytesAgain | bytesagain.com | hello@bytesagain.com

# Initialize the data directory
cashflow init
Add entries
cashflow add "Monthly rent payment 2500"
cashflow add "Freelance invoice received 8000"
cashflow add "Grocery shopping 350"
List all entries
cashflow list

# Search for specific entries
cashflow search rent
cashflow search invoice
Export data to a file
cashflow export > my-records.txt
Check status and info
cashflow status
cashflow info

# Run a custom operation
cashflow run process-monthly
View configuration location
cashflow config
Remove an entry
cashflow remove "old entry"
Show version
cashflow version

| Variable | Purpose | Default | |----------|---------|---------| | CASHFLOW_DIR | Override data/config directory | ~/.local/share/cashflow/ | | XDG_DATA_HOME | Fallback base directory | ~/.local/share/ |

Powered by BytesAgain | bytesagain.com | hello@bytesagain.com