Puffin

Terminal dashboard to manage personal finances. Built with hledger and bubbletea.

💫 Features
- 📈 View reports
- 🔎 Filter reports
🤖 Installation
📝 Configuration
- Keys

💫 Features

All hledger reports are viewable using Puffin. Some of them are natively supported, others are displayed in a simple scrollable view.

📈 View reports

Puffin supports the following reports natively:

assets
expenses
revenue
liabilities
register
accounts
commodities

The following reports are also easily viewable:

income statement
balance sheet

🔎 Filter reports

The data can be filtered by:

account name
start/end date
displayed periodically - weekly, monthly, quaterly, yearly
change account depth

🤖 Installation

Download binaries

If you just want to use it, you can download the binary from here.

Install from source

Pre-requisites

hledger is required for puffin to work.
make
Go compiler (>=1.17)

Build

Clone this repo
Run the command make build. This creates the binary puffin.

Run demo

Clone this repo
Run make debug

Run with your own journal file

Use make start

Run using make build && ./puffin

It uses your hledger setup as it is. So there is no need to setup journal files if you are already using hledger.

Configuration

Puffin can use a config file written in json. It is not required though. Without a config file Puffin will use sane defaults.

The default config:

"reports": [
    {
        "name": "register",
        "cmd": "hledger register"
    },
    {
        "name": "expenses",
        "cmd": "hledger balance type:x"
    },
    {
        "name": "assets",
        "cmd": "hledger balance type:a"
    },
    {
        "name": "revenue",
        "cmd": "hledger balance type:r"
    },
    {
        "name": "liabilities",
        "cmd": "hledger balance type:l"
    },
    {
        "name": "income statement",
        "cmd": "hledger incomestatement"
    },
    {
        "name": "balance sheet",
        "cmd": "hledger balancesheet"
    },
    {
        "name": "accounts",
        "cmd": "hledger accounts --tree",
        "locked": true,
    }
]

name represents the name of the report, as displayed in the left sidebar
cmd is the hledger command to be run
locked: if true, filters will not be applied to the report

Note about locked reports A report is considered "locked" if the locked field is set to true. A locked report remains unaffected by the filters. This means that they cannot be filtered by date, period, account name etc.

Locked reports are useful for 2 purposes

Reports where filters don't make sense, such as a list of accounts or commodities
Reports that you want to remain static. Such as a report with more a complex hledger command or other custom modifications.

See config.debug.json for more ideas.

Keys

Show this help with ?

siddhantac/puffin