Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
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 2 years ago)
- Default Branch: main
- Last Pushed: 2024-09-12T02:15:53.000Z (4 months ago)
- Last Synced: 2024-09-12T12:08:03.369Z (4 months ago)
- Topics: bubbletea, finance, golang, hledger, ledger, ledger-cli, tui
- Language: Go
- Homepage:
- Size: 17.6 MB
- Stars: 238
- Watchers: 3
- Forks: 6
- Open Issues: 6
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
- awesome-tuis - Puffin
- awesome-hledger - puffin - A bubbletea based TUI to manage personal finances using hledger (TUI - Terminal User Interface to view, add and manage journal files)
- charm-in-the-wild - puffin - A TUI for hledger to manage your finances. (_built with Bubble Tea_) (Applications / Finance)
README
# Puffin
Terminal dashboard to manage personal finances. Built with [hledger](https://hledger.org/) and [bubbletea](https://github.com/charmbracelet/bubbletea).
# Table of Contents
- [💫 Features](#💫-features)
- [📈 View reports](#📈-view-reports)
- [🔎 Filter reports](#🔎-filter-reports)
- [🤖 Installation](#🤖-installation)
- [📝 Configuration](#📝-configuration)
- [Keys](#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](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 `?`
