Budget Woad CLI 🎯

A powerful, light-weight Command Line Interface (CLI) version of the budget-woad.vercel.app finance application. This tool allows you to log in and monitor your daily expenses, monthly incomes, and balance stats on the go directly from your terminal.

Features

• 👤 Interactive Greeting: Welcome screen for users.
• 🔑 Secure Authentication: Log in to your account with a CLI command. Credentials/Tokens are securely saved locally.
• 📊 Monthly Stats: Fetch and display monthly financial stats (Income, Expenses, and Balance) for any specified month and year.
• 🎨 Color-Coded Terminal: Styled outputs with chalk for quick visual readability of financial numbers.

Installation

You can install the CLI globally on your system using npm:

npm install -g budget-woad-cli

Usage Guide

Once installed, the CLI can be invoked anywhere in your terminal using the budget command.

1. Show Help & Options

To see the list of all available commands and arguments:

budget --help

2. Welcome Greeting

To verify the CLI is installed and running, run a greeting with your name:

budget <your-name>

Example:

budget whiteFox

3. Log In to Your Account

To authenticate your CLI and allow it to pull stats from your account, log in using your credentials:

budget login -u <username> -p <password>

Example:

budget login -u whiteFox -p 123456

How it works: The CLI requests a token from the backend API and stores it locally on your machine. You do not need to log in again for subsequent commands.

4. Fetch Budget Stats

Retrieve your income, expenses, and balance summary for a specific month and year:

budget stats -m <month> -y <year>

Example (for March 2026):

budget stats -m 3 -y 2026

Technical Stack & Dependencies

The project is built on Node.js using modern ESM (import/export) modules and leverages the following libraries:

• Commander.js: Used for building interactive command line parameters, subcommands, and generating help text.
• Chalk: Used for adding ANSI escape colors to console statements to highlight income (green), expenses (red), and balance (yellow).
• Axios: Handles HTTP communications with the remote budget server.
• Configstore: Safely saves and retrieves your session token locally without prompting for passwords repeatedly.

Local Development & Contribution

If you want to run the project locally or make changes to it:

1. Clone the repository.
2. Install dependencies:

   npm install

3. Link the package locally:

   npm link

4. Now, any changes you make in index.js or auth.js will immediately reflect when you run the budget command in your terminal.
5. To unlink:

   npm unlink -g