https://github.com/siddhantac/puffin
A beautiful terminal dashboard for hledger 💰
https://github.com/siddhantac/puffin
bubbletea finance golang hledger ledger ledger-cli tui
Last synced: 2 months ago
JSON representation
A beautiful terminal dashboard for hledger 💰
- Host: GitHub
- URL: https://github.com/siddhantac/puffin
- Owner: siddhantac
- License: mit
- Created: 2022-11-01T02:05:26.000Z (about 3 years ago)
- Default Branch: main
- Last Pushed: 2025-09-13T05:44:24.000Z (3 months ago)
- Last Synced: 2025-09-13T07:21:13.684Z (3 months ago)
- Topics: bubbletea, finance, golang, hledger, ledger, ledger-cli, tui
- Language: Go
- Homepage:
- Size: 20.4 MB
- Stars: 419
- Watchers: 3
- Forks: 8
- Open Issues: 11
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
- awesome-hledger - puffin - A bubbletea based TUI to manage personal finances using hledger (TUI - Terminal User Interface to view, add and manage journal files)
- awesome-cli-apps-in-a-csv - Puffin - A beautiful TUI dashboard for hledger. (<a name="financial"></a>Financial tools)
- charm-in-the-wild - puffin - A TUI for hledger to manage your finances. (_built with Bubble Tea_) (Applications / Finance)
- awesome-cli-apps - Puffin - A beautiful TUI dashboard for hledger. (<a name="financial"></a>Financial tools)
- awesome-tuis - Puffin
README
# Puffin
Terminal dashboard to manage personal finances. Built with [hledger](https://hledger.org/) and [bubbletea](https://github.com/charmbracelet/bubbletea).
# Table of Contents
- [📢 V3 announcement](#📢-v3-announcement)
- [💫 Features](#💫-features)
- [📈 View reports](#📈-view-reports)
- [🔎 Filter reports](#🔎-filter-reports)
- [🤖 Installation](#🤖-installation)
- [📝 Configuration](#📝-configuration)
- [Keys](#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
```shell
./puffin -v3
```
Please note, **v3 uses a simple config file with only the `journalFile` field**. So if you are using a config file with v2 then it won't be used with v3. However, you *can* modify the journal file to be used with v3.
## Demo
### Screenshots
Home
Reports
## V3 roadmap
- [x] Accounts table
- [x] Balance table
- [x] Register table
- [x] Income statement
- [x] 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
```bash
brew install siddhantac/puffin/puffin
```
## Download binaries
If you just want to use it, you can download the binary from [here](https://github.com/siddhantac/puffin/releases).
## Install from source
### Pre-requisites
- [hledger](https://hledger.org/) 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:
```json
"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](config.debug.json) for more ideas.
## Keys
Show this help with `?`
