|
| 1 | +<h1 align="center">ngtonic</h1> |
| 2 | +<h3 align="center">Personal finances on your terminal</h2> |
| 3 | + |
| 4 | +<p align="center"> |
| 5 | +<a href="https://pypi.org/project/ngtonic/"> |
| 6 | +<img alt="CI" src="https://img.shields.io/pypi/v/ngtonic?logo=pypi&logoColor=white"> |
| 7 | +</a> |
| 8 | +<img alt="PyPI - License" src="https://img.shields.io/pypi/l/ngtonic"> |
| 9 | +<img alt="Linux" src="https://img.shields.io/badge/Linux-FCC624?logo=linux&logoColor=black"> |
| 10 | +<img alt="PyPI - Python Version" src="https://img.shields.io/pypi/pyversions/ngtonic"> |
| 11 | +</p> |
| 12 | + |
| 13 | +## 🌟 Motivation and Description |
| 14 | + |
| 15 | +Ngtonic is a small tool created to manage personal finances directly from the terminal, avoiding the need to share sensitive financial data with third-party apps. It's tailored for my specific needs. Currently, Ngtonic only supports ING bank, leveraging its automatic categorization of movements. |
| 16 | + |
| 17 | +I also created it as an example of building a project "the right way" on GitHub. |
| 18 | + |
| 19 | +## 🤔 Why Use Ngtonic? |
| 20 | + |
| 21 | +Consider using Ngtonic if you: |
| 22 | + |
| 23 | + - Prefer not to use apps like Fintonic |
| 24 | + - Primarily use ING for personal expenses |
| 25 | + - Want a simple, terminal-based tool to check your finances |
| 26 | + - Value privacy and keeping your financial data local |
| 27 | + |
| 28 | +For those seeking more advanced features or a GUI, [Firefly III](https://www.firefly-iii.org) might be a better option. |
| 29 | + |
| 30 | +## 👨💻 Getting started |
| 31 | + |
| 32 | +1. Install using [pipx](https://pipx.pypa.io/stable/installation/) (recommended) or pip: |
| 33 | + |
| 34 | +```bash |
| 35 | +pipx install ngtonic |
| 36 | +``` |
| 37 | + |
| 38 | +2. Download your ING account movements as an Excel file. |
| 39 | + |
| 40 | +3. Import the movements: |
| 41 | + |
| 42 | +```bash |
| 43 | +ngtonic import movements.xls |
| 44 | +``` |
| 45 | + |
| 46 | +Your data is now stored locally in `.ngtonic/movements.json`. You can import multiple files; Ngtonic will automatically deduplicate the data. |
| 47 | + |
| 48 | +## 📊 Usage |
| 49 | + |
| 50 | +Ngtonic offers several commands: |
| 51 | + |
| 52 | +``` |
| 53 | +╭─ Commands ──────────────────────────────────────────────────────────────────────────────╮ |
| 54 | +│ import Import movements files to the internal storage (only ING is supported) │ |
| 55 | +│ list Show a table listing the movements with optional filtering │ |
| 56 | +│ balance-plot Plot the evolution of the balance over time │ |
| 57 | +│ month-plot Plot the movements grouped per month │ |
| 58 | +│ find-bills Use a simple heuristic to find regular bills, like subscriptions │ |
| 59 | +╰─────────────────────────────────────────────────────────────────────────────────────────╯ |
| 60 | +``` |
| 61 | + |
| 62 | +```bash |
| 63 | +# Use category filtering to list home expenses |
| 64 | +ngtonic list -c hogar |
| 65 | + |
| 66 | +# List leisure expenses by month |
| 67 | +ngtonic list -c ocio -m |
| 68 | + |
| 69 | +# Check Steam purchases by month |
| 70 | +ngtonic list -d steam -m |
| 71 | + |
| 72 | +# Use the integrated heuristic to find regular bills |
| 73 | +ngtonic find-bills |
| 74 | +``` |
| 75 | +The plot commands enable you to visualize movements grouped by month or track the balance over time. You can apply the same filters available in the list command to customize these plots. Below are some example graphs (y axis has been removed for privacy). |
| 76 | + |
| 77 | +```Bash |
| 78 | +# Income per mont (in my case, the payroll) |
| 79 | +ngtonic month-plot -i |
| 80 | +``` |
| 81 | +<img src="examples/payroll.png" width="600"> |
| 82 | + |
| 83 | +```Bash |
| 84 | +# Expenses on ocio category per month |
| 85 | +ngtonic month-plot -c ocio |
| 86 | +``` |
| 87 | +<img src="examples/ocio.png" width="600"> |
| 88 | + |
| 89 | +```Bash |
| 90 | +# The month-plot without any options is a good way to know your saving capacity |
| 91 | +ngtonic month-plot |
| 92 | +``` |
| 93 | +<img src="examples/month-plot.png" width="600"> |
| 94 | + |
| 95 | +```Bash |
| 96 | +# And the balance plot will give you a more detailed way to check your cash flow |
| 97 | +ngtonic balance-plot |
| 98 | +``` |
| 99 | +<img src="examples/full_balance.png" width="600"> |
| 100 | + |
| 101 | + |
| 102 | +## ⚙️ Configuration |
| 103 | + |
| 104 | +### Excluding Movements |
| 105 | + |
| 106 | +Sometimes you may want to exclude certain transactions from your analysis, such as: |
| 107 | + |
| 108 | + - Transfers between your own accounts or to other banks |
| 109 | + - Large one-time transactions that skew your graphs |
| 110 | + - Any movements you don't want to include in your financial overview |
| 111 | + |
| 112 | +You can exclude these movements using the configuration file located at `.ngtonic/config.yaml`. This file contains a list of filters; any movement matching these filters will be excluded from all commands. |
| 113 | + |
| 114 | +Example configuration: |
| 115 | + |
| 116 | +```yaml |
| 117 | +excluded_movements: |
| 118 | + - category: "Inversión" |
| 119 | + - subcategory: "Ingresos de otras entidades" |
| 120 | + - description: "Traspaso emitido Cuenta Nómina" |
| 121 | + - description: "steam" |
| 122 | + value: -675 # Excludes only this specific Steam transaction |
| 123 | +``` |
| 124 | +
|
| 125 | +## 🛠️ Development |
| 126 | +
|
| 127 | +```bash |
| 128 | +pdm install |
| 129 | +$(pdm venv activate) |
| 130 | +pre-commit install |
| 131 | +``` |
| 132 | + |
| 133 | +This command will create a virtual environment, install all dependencies (including Ngtonic itself), and set up helpful commit hooks. Any changes made to the code will take effect immediately without requiring reinstallation. |
| 134 | + |
| 135 | +You can also run manually the linter with `pdm lint` or the formatter with `pdm format`. |
| 136 | + |
| 137 | +## 📦 Releases |
| 138 | + |
| 139 | +The python packages are uploaded from the CI when creating a release, but you can create an whl locally with `pdm build`. |
0 commit comments