{"id":13522349,"url":"https://github.com/siddhantac/puffin","last_synced_at":"2025-10-06T20:19:08.107Z","repository":{"id":63315457,"uuid":"560224372","full_name":"siddhantac/puffin","owner":"siddhantac","description":"A beautiful terminal dashboard for hledger 💰","archived":false,"fork":false,"pushed_at":"2025-09-13T05:44:24.000Z","size":21410,"stargazers_count":419,"open_issues_count":11,"forks_count":8,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-09-13T07:21:13.684Z","etag":null,"topics":["bubbletea","finance","golang","hledger","ledger","ledger-cli","tui"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/siddhantac.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2022-11-01T02:05:26.000Z","updated_at":"2025-09-13T05:44:27.000Z","dependencies_parsed_at":"2023-09-27T12:26:07.068Z","dependency_job_id":"68070ba4-7542-4df4-ba6b-bc7a0730167d","html_url":"https://github.com/siddhantac/puffin","commit_stats":null,"previous_names":[],"tags_count":23,"template":false,"template_full_name":null,"purl":"pkg:github/siddhantac/puffin","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/siddhantac%2Fpuffin","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/siddhantac%2Fpuffin/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/siddhantac%2Fpuffin/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/siddhantac%2Fpuffin/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/siddhantac","download_url":"https://codeload.github.com/siddhantac/puffin/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/siddhantac%2Fpuffin/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":278672127,"owners_count":26025842,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-06T02:00:05.630Z","response_time":65,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bubbletea","finance","golang","hledger","ledger","ledger-cli","tui"],"created_at":"2024-08-01T06:00:45.950Z","updated_at":"2025-10-06T20:19:08.100Z","avatar_url":"https://github.com/siddhantac.png","language":"Go","funding_links":[],"categories":["TUI - Terminal User Interface to view, add and manage journal files","Go","\u003ca name=\"financial\"\u003e\u003c/a\u003eFinancial tools","Applications","Table of Contents"],"sub_categories":["Finance"],"readme":"# Puffin\n\nTerminal dashboard to manage personal finances. Built with [hledger](https://hledger.org/) and [bubbletea](https://github.com/charmbracelet/bubbletea).\n\n\u003cp\u003e\n    \u003ca href=\"https://github.com/siddhantac/puffin/releases\"\u003e\u003cimg src=\"https://img.shields.io/github/release/siddhantac/puffin.svg\" alt=\"Latest Release\"\u003e\u003c/a\u003e\n    \u003ca href=\"https://github.com/siddhantac/puffin/actions/workflows/go.yml\"\u003e\u003cimg src=\"https://github.com/siddhantac/puffin/actions/workflows/go.yml/badge.svg\" alt=\"Build Status\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n    \n\u003ca href=\"./altscreen-toggle/main.go\"\u003e\n  \u003cimg width=\"750\" src=\"assets/demo.gif\" /\u003e\n\u003c/a\u003e\n\n# Table of Contents\n\n- [📢 V3 announcement](#📢-v3-announcement)\n- [💫 Features](#💫-features)\n    - [📈 View reports](#📈-view-reports)\n    - [🔎 Filter reports](#🔎-filter-reports)\n- [🤖 Installation](#🤖-installation)\n- [📝 Configuration](#📝-configuration)\n    - [Keys](#keys)\n\n# 📢 V3 announcement\n\nA 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.\n\nTo try V3, you can update to the latest version and run\n\n```shell\n./puffin -v3\n```\n\nPlease 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.\n\n## Demo\n\n![demo](assets/demo_v3.gif)\n\n### Screenshots\n\n\u003cdetails\u003e\n\u003csummary\u003eHome\u003c/summary\u003e\n\n![home](assets/screenshot_home_v3.png)\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eReports\u003c/summary\u003e\n\n![reports](assets/screenshot_reports_v3.png)\n\n\u003c/details\u003e\n\n## V3 roadmap\n- [x] Accounts table\n- [x] Balance table\n- [x] Register table\n- [x] Income statement\n- [x] Balance sheet\n- [ ] Balance table with periodic columns\n- [ ] Config file support\n- [ ] Custom reports\n\n# 💫 Features\n\nAll *hledger* reports are viewable using Puffin. Some of them are natively supported, others are displayed in a simple scrollable view. \n\n## 📈 View reports\n\nPuffin supports the following reports natively:\n- assets\n- expenses\n- revenue\n- liabilities\n- register\n- accounts\n- commodities\n\nThe following reports are also easily viewable:\n- income statement\n- balance sheet\n\n## 🔎 Filter reports\nThe data can be filtered by:\n- account name\n- start/end date\n- displayed periodically - weekly, monthly, quaterly, yearly\n- change account depth\n\n\n# 🤖 Installation\n\n## Homebrew\n\n```bash\nbrew install siddhantac/puffin/puffin\n```\n\n## Download binaries\nIf you just want to use it, you can download the binary from [here](https://github.com/siddhantac/puffin/releases).\n\n## Install from source\n### Pre-requisites\n\n- [hledger](https://hledger.org/) is required for puffin to work.\n- make\n- Go compiler (\u003e=1.17)\n\n### Build\n\n* Clone this repo\n* Run the command `make build`. This creates the binary `puffin`.\n\n### Run demo\n\n* Clone this repo\n* Run `make debug`\n\n### Run with your own journal file\n\n* Use `make start`\n\nor\n\n* Run using `make build \u0026\u0026 ./puffin`\n\nIt uses your hledger setup as it is. So there is no need to setup journal files if you are already using hledger.\n\n# Configuration\n\nPuffin can use a config file written in json. It is not required though. Without a config file Puffin will use sane defaults. \n\nThe default config:\n\n```json\n\"reports\": [\n    {\n        \"name\": \"register\",\n        \"cmd\": \"hledger register\"\n    },\n    {\n        \"name\": \"expenses\",\n        \"cmd\": \"hledger balance type:x\"\n    },\n    {\n        \"name\": \"assets\",\n        \"cmd\": \"hledger balance type:a\"\n    },\n    {\n        \"name\": \"revenue\",\n        \"cmd\": \"hledger balance type:r\"\n    },\n    {\n        \"name\": \"liabilities\",\n        \"cmd\": \"hledger balance type:l\"\n    },\n    {\n        \"name\": \"income statement\",\n        \"cmd\": \"hledger incomestatement\"\n    },\n    {\n        \"name\": \"balance sheet\",\n        \"cmd\": \"hledger balancesheet\"\n    },\n    {\n        \"name\": \"accounts\",\n        \"cmd\": \"hledger accounts --tree\",\n        \"locked\": true,\n    }\n]\n```\n\n- `name` represents the name of the report, as displayed in the left sidebar\n- `cmd` is the hledger command to be run\n- `locked`: if true, filters will **not be applied** to the report\n\n**Note about locked reports** \nA 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.\n\nLocked reports are useful for 2 purposes\n1. Reports where filters don't make sense, such as a list of accounts or commodities\n2. Reports that you want to remain static. Such as a report with more a complex hledger command or other custom modifications.\n\nSee [config.debug.json](config.debug.json) for more ideas.\n\n\n## Keys\n\nShow this help with `?` \n\n![keybindings](assets/keybindings.png)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsiddhantac%2Fpuffin","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsiddhantac%2Fpuffin","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsiddhantac%2Fpuffin/lists"}