Simple Finance CLI

sfcli is a Command-line interface application for personal finance management.
It is a set of commands for managing monetary entries (incomes and expenses) through the terminal.

README em Português Brasileiro

Quick Start

pipx install simple-finance-cli

sfcli add income salary 2500
sfcli add expense rent 800
sfcli add expense groceries 150

sfcli show
sfcli balance

Table of Contents

• Installation
  • pipx
  • Download a Binary
  • Repo Cloning
• Usage
  • sfcli add
  • sfcli show
  • sfcli delete
  • sfcli balance
• Dependencies
• Tests and Build
• Author Notes

Installation

pipx

⚠️ Requirements: Python 3.10 or newer, pipx installed.

pipx handles installation and isolated environments.
With pipx installed, simply run:

pipx install simple-finance-cli

And then you're ready to go:

sfcli add e "New Expense" 100

Download a Binary

Skip the build step and grab a pre-built binary:

Download from GitHub Releases →

Choose the archive matching your operating system and you're ready to go.

⚠️ Windows users: if Windows Defender/SmartScreen blocks the executable, you may need to alter file permissions and properties, or disable Windows Defender/SmartScreen.

Repo Cloning

⚠️ Requirement: Python 3.10 or newer

You can install the project following these steps:

1. Clone the repository and enter directory:

git clone https://github.com/joao-antonio-la/simple-finance-cli.git
cd simple-finance-cli

2. Create a Python virtual environment:

• Windows:

python -m venv .venv

• macOS and Linux:

python3 -m venv .venv

3. Activate the venv:

• Windows:

.venv\Scripts\activate

• macOS and Linux:

source .venv/bin/activate

4. Install the CLI:

pip install .

5. Use the app:

sfcli add e "New Expense" 100

Usage

sfcli currently provides four commands for managing your finances:

• sfcli add: Create a new income or expense entry.
• sfcli show: Display all saved entries.
• sfcli delete: Delete one or all entries.
• sfcli balance: Calculate the current balance.

sfcli add

The add command creates and saves a new financial entry.

sfcli add <type> <name> <value> [options]

Positional Arguments

1. type: Determines whether the entry is an income or an expense.
   Possible values:

   • "income"
   • "inc"
   • "i"
   • "expense"
   • "exp"
   • "e"

2. name: The name or label of the entry.
   Examples:

   • "Rent"
   • "Internet Bill"
   • "Weekly Groceries"

3. value: Absolute monetary value.
   Use a positive number. sfcli determines whether it is added or subtracted based on type. Examples:

   • 67
   • 99.99
   • 56.4

⚠️ Values ​​with decimal places must be represented by a period ( . ), not a comma ( , ).

Optional Arguments

• -d | --date: Date of when the entry was received or spent.
  Dates should follow the YYYY-MM-DD format. You can also use the following aliases:

  • yesterday
  • today
  • tomorrow

  Examples:

  --date 2026-03-17
  --date 2026-08-05
  -d 2026-12-25
  -d today
  

If --date is omitted, sfcli uses the date on the user's system.
For example, if you execute an add command on January 21, 2026, the entry will be registered with the date "2026-01-21".

• -c | --comment: Additional information associated with the entry.
  Examples:
  • "10% bonus salary"
  • "Emergency groceries since being sick"
  • "Remember to pay John back"

Examples

sfcli add income "mama's gift" 50 --comment "random gift from mama"
sfcli add expense dinner 46.99
sfcli add inc salary 1560 --date today --comment "100 bonus"
sfcli add exp rent 600
sfcli add e "quick snack" 5
sfcli add i "found in street" 10 --date "2026-05-23"

sfcli show

The show command displays all saved entries in a formatted table.
By default, sfcli displays a shortened version of each entry's ID.
Use the --full-id or -I flag to display the complete ID.

sfcli show
sfcli show --full-id
sfcli show -I

sfcli delete

This command allows you to erase one or all saved entries.

Delete a specific entry

Provide the entry's ID to delete it:

sfcli delete 13055296-43a1-4ad6-8896-760a169bde5c

Delete all entries

Use "all" to erase all saved entries:

sfcli delete all

sfcli balance

The balance command calculates the total balance by taking both incomes and expenses into account.

sfcli balance

Dependencies

sfcli has the following dependencies:

• rich: Used to display formatted output, such as tables and colored text.
• platformdirs: Used to determine an appropriate location for storing application data.

Tests and Build

sfcli dev environment uses the following libs for testing and building:

• pytest: Used for writing and executing test cases.
• nox: Used for testing multiple Python versions automatically.

Additionally, in the CI workflow, it uses PyInstaller for generating the binary files.

Author Notes

Currently, sfcli has only four commands, but more features are already being planned.
More quality-of-life improvements are also on the way.
Stay tuned for future updates, and if you enjoy the project, consider giving it a star.

• License: MIT License
• Author: João Antônio