Metadata-Version: 2.4
Name: simple-finance-cli
Version: 0.0.1
Summary: CLI application for personal finance management
Author: João Antônio
License-Expression: MIT
Requires-Python: <3.15,>=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: rich
Requires-Dist: platformdirs
Dynamic: license-file

# Simple Finance CLI

`sfcli` is a [Command-line interface](https://en.wikipedia.org/wiki/Command-line_interface) application for personal finance management.  
It is a set of commands for managing monetary entries (incomes and expenses) through the terminal.

![add](public/add.png)

![balance](public/balance.png)

[README em Português Brasileiro](README.pt-br.md)

## Quick Start

``` sh
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](#installation)
    - [pipx](#pipx)
    - [Download a Binary](#download-a-binary)
    - [Repo Cloning](#repo-cloning)
- [Usage](#usage)
    - [sfcli add](#sfcli-add)
    - [sfcli show](#sfcli-show)
    - [sfcli delete](#sfcli-delete)
    - [sfcli balance](#sfcli-balance)
- [Dependencies](#dependencies)
- [Tests and Build](#tests-and-build)
- [Author Notes](#author-notes)

## Installation

### pipx

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

[pipx](https://pipx.pypa.io/stable/) handles installation and isolated environments.  
With pipx installed, simply run: 

``` sh
pipx install simple-finance-cli
```

And then you're ready to go:

``` sh
sfcli add e "New Expense" 100
```

### Download a Binary

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

> **[Download from GitHub Releases →](https://github.com/joao-antonio-la/simple-finance-cli/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:

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

2. Create a Python virtual environment:

- Windows:
``` sh
python -m venv .venv
```

- macOS and Linux:
``` sh
python3 -m venv .venv
```

3. Activate the venv:

- Windows:
``` sh
.venv\Scripts\activate
```

- macOS and Linux:
``` sh
source .venv/bin/activate
```

4. Install the CLI:

``` sh
pip install .
```

5. Use the app:

``` sh
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

``` sh
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.

``` sh
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:

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

#### Delete all entries

Use *"all"* to erase all saved entries:

``` sh
sfcli delete all
```

### `sfcli balance`

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

``` sh
sfcli balance
```

## Dependencies

`sfcli` has the following dependencies:

- [rich](https://pypi.org/project/rich/): Used to display formatted output, such as tables and colored text.
- [platformdirs](https://pypi.org/project/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](https://pypi.org/project/pytest/): Used for writing and executing test cases.
- [nox](https://pypi.org/project/nox/): Used for testing multiple Python versions automatically.

Additionally, in the *CI workflow*, it uses [PyInstaller](https://pypi.org/project/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](LICENSE)
- Author: [João Antônio](https://github.com/joao-antonio-la)
