Puffin

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

Table of Contents

• 📢 V3 announcement
• 💫 Features
  • 📈 View reports
  • 🔎 Filter reports
• 🤖 Installation
• 📝 Configuration
  • Keys

📢 V3 announcement

A new version of Puffin is under active development. This version completely revamps the UI and gives you a far better overview of your finances. Some features have been implemented, while others are still being built.

To try V3, you can update to the latest version and run

./puffin -v3

Please note, v3 does not use a config file yet. So if you are using a config file with v2 then it won't be used with v3.

V3 roadmap

• Accounts table
• Balance table
• Register table
• Income statement
• Balance sheet
• Balance table with periodic columns
• Config file support
• Custom reports

💫 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

Homebrew

brew install siddhantac/puffin/puffin

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

or

• 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

1. Reports where filters don't make sense, such as a list of accounts or commodities
2. 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 ?