Stop Wrestling with Spreadsheets! Puffin Is the Terminal Finance Dashboard You Need

Let me ask you something brutal: how many hours have you wasted this year clicking through bloated banking apps, wrestling with Excel formulas, or staring at plain-text hledger output that feels like reading a phone book? If you're a developer who already lives in the terminal, the idea of leaving your command-line sanctuary just to check if you can afford coffee next week should feel personally offensive.

Here's the dirty secret nobody talks about: personal finance tools are broken for technical people. GUIs are slow. Spreadsheets are fragile. And while hledger is undeniably powerful for plain-text accounting, staring at raw command output is nobody's idea of financial clarity. You built your entire workflow around keyboard-driven efficiency—then you abandon all of it the moment money enters the picture?

Enter Puffin.

This isn't another Electron app masquerading as "modern." This is a beautiful terminal dashboard built specifically for hledger, powered by Go and the legendary Bubble Tea framework from Charm. It transforms your financial data into an interactive, keyboard-navigable experience that feels as native as vim or tmux. No mouse required. No context switching. Just pure, data-dense financial clarity in the environment you already love.

In this deep dive, I'm exposing why developers everywhere are quietly switching to Puffin, how to get it running in under 5 minutes, and the exact configuration tricks that separate power users from tourists. Whether you're tracking crypto, managing freelance income, or just finally getting serious about where your money goes—this tool changes everything.

What Is Puffin? The Terminal Finance Tool Developers Actually Want

Puffin is an open-source terminal user interface (TUI) dashboard for managing personal finances through hledger, the robust plain-text accounting system. Created by developer Siddhanta Chatterjee, Puffin bridges the gap between hledger's raw power and the intuitive visual experience modern users expect.

Built with Go and Bubble Tea—the same TUI framework powering some of the most elegant CLI tools in the ecosystem—Puffin represents a growing movement: developers refusing to leave the terminal for essential tasks. It's not a replacement for hledger. It's the beautiful, interactive lens your financial data deserves.

Why It's Exploding Right Now

The timing isn't accidental. Three forces are converging:

1. The plain-text accounting renaissance — Developers are rejecting proprietary finance apps, embracing hledger/beancount for version-controlled, auditable money tracking.
2. TUI maturity — Bubble Tea and similar frameworks have made terminal interfaces genuinely gorgeous, not just "functional for nerds."
3. Financial anxiety meets technical competence — Post-2020 economic uncertainty pushed developers to track finances meticulously, but they refuse to use tools that insult their intelligence.

Puffin's V3 (released February 2026) represents a complete UI overhaul—though the author notes development is currently paused for personal reasons, with contributions actively welcomed. The V3 interface is already stable and, in the creator's words, "looks better than v2." The roadmap includes balance tables with periodic columns, enhanced config support, and custom reports.

Key Features: Where Puffin Destroys the Competition

Puffin isn't a thin wrapper around hledger commands. It's a purpose-built financial cockpit with features that reveal how deeply the creator understands developer workflows.

Native Report Visualization

Puffin doesn't just display hledger output—it restructures it for terminal consumption. Native support includes:

• Assets — Real-time net worth tracking with hierarchical account breakdown
• Expenses — Where your money bleeds, categorized and sortable
• Revenue — Income streams visualized with period comparisons
• Liabilities — Debt exposure that updates as you navigate
• Register — Transaction-level detail with instant filtering
• Accounts — Tree-structured account hierarchy (locked by default, since filtering accounts makes no sense)
• Commodities — Multi-currency support for crypto and forex traders

Additional reports like income statement and balance sheet render in clean, scrollable views—no more piping through less and losing your place.

Surgical Filtering Without Syntax Memorization

Here's where Puffin earns its keep. Instead of constructing complex hledger query strings, you interactively filter via keyboard:

• Account name filtering — Drill into specific expense categories instantly
• Date range selection — Start/end boundaries without remembering --begin/--end flags
• Periodic grouping — Toggle between weekly, monthly, quarterly, and yearly views with single keystrokes
• Account depth control — Expand or collapse hierarchy levels to see forest or trees

The killer detail? Locked reports. Mark any report as locked: true in config, and filters won't touch it. This means your complex custom hledger command stays pristine while you slice other reports dynamically.

Keyboard-First Navigation

Every action is a keystroke away. Press ? for the full keybinding reference—Puffin follows the vim/tmux convention of discoverable shortcuts. No reaching for the mouse. No menu diving. Just muscle memory and flow state.

Real-World Use Cases: When Puffin Becomes Irreplaceable

Scenario 1: The Freelance Income Archaeologist

You have 47 clients, payments arriving irregularly, and tax season approaching. Your hledger file is comprehensive but finding Q2 earnings from recurring clients requires constructing a query string you'll forget by next quarter. With Puffin: open revenue report, filter date range to Q2, group monthly, done. Thirty seconds. No documentation lookup.

Scenario 2: The Crypto-Native Expense Tracker

You're tracking multiple fiat currencies plus BTC and ETH. Standard finance apps choke on multi-commodity reporting. Puffin's commodities report plus hledger's robust currency handling means you see real purchasing power across your entire portfolio, not just dollar-denominated hallucinations.

Scenario 3: The Couple's Shared Finances

You and your partner maintain a joint hledger file in Git. Puffin runs against the same file—no "syncing" required. Each person filters to their relevant accounts without modifying the underlying data. The locked accounts report ensures your chart of accounts stays consistent regardless of who's viewing what.

Scenario 4: The Annual Review Power User

December 31st, you're preparing year-end summaries. Without Puffin: construct 12 separate hledger commands, pipe to files, compile in spreadsheet. With Puffin: navigate to income statement, toggle yearly grouping, screenshot the terminal. Your annual financial review becomes a 5-minute dashboard exploration instead of a weekend project.

Step-by-Step Installation & Setup Guide

Puffin respects your time with multiple installation paths. Choose your adventure:

Method 1: Homebrew (Fastest for Most Users)

# Add the tap and install in one motion
brew install siddhantac/puffin/puffin

Verify installation:

puffin --version

Method 2: Pre-built Binaries (No Package Manager Required)

Download directly from GitHub Releases. Extract and move to your $PATH:

# Example for Linux/macOS
wget https://github.com/siddhantac/puffin/releases/download/v3.x.x/puffin_Linux_x86_64.tar.gz
tar -xzf puffin_Linux_x86_64.tar.gz
mv puffin ~/.local/bin/  # or /usr/local/bin/

Method 3: Build from Source (Developers' Choice)

Prerequisites — Non-negotiable:

• hledger installed and in your $PATH
• make (standard on most Unix systems)
• Go compiler ≥1.17

# Clone the repository
git clone https://github.com/siddhantac/puffin.git
cd puffin

# Build the binary
make build
# Creates ./puffin in your current directory

# Run with your actual journal file
make start

# Or manually after build
./puffin

Pro tip for contributors: make debug runs Puffin with demo data, perfect for UI hacking without exposing your actual finances.

V3 Preview Activation

Want the cutting-edge interface? Puffin V3 is stable and gorgeous:

# After installing any version above
./puffin -v3

Critical V3 note: V3 uses a simplified config format with only the journalFile field. Your existing v2 config won't load—plan migration accordingly.

Environment Setup

Puffin auto-detects your hledger configuration. If hledger works from your shell, Puffin works. No additional journal file setup required for existing hledger users. The tool respects your LEDGER_FILE environment variable and standard hledger file locations.

REAL Code Examples: Puffin in Action

Let's dissect actual implementation patterns from Puffin's repository, showing how configuration and usage work in practice.

Example 1: Default Configuration Structure

Puffin's config file is JSON—explicit, version-controllable, and diff-friendly. Here's the exact default configuration from the repository:

{
  "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
    }
  ]
}

What's happening here? Each report object defines:

• "name": The human-readable label appearing in Puffin's sidebar
• "cmd": The raw hledger command executed when you select this report
• "locked" (optional): When true, filters are disabled—crucial for structural reports like account trees where filtering would destroy meaning

Notice the hledger type shortcuts: type:x for expenses, type:a for assets, etc. These are hledger's query language—Puffin doesn't abstract them away, it surfaces them beautifully.

Example 2: Custom Report with Complex Command

The repository's config.debug.json reveals advanced patterns. Here's how you'd construct a custom report with multiple hledger flags:

{
  "reports": [
    {
      "name": "monthly food analysis",
      "cmd": "hledger balance expenses:food --monthly --average --row-total",
      "locked": false
    },
    {
      "name": "investment accounts",
      "cmd": "hledger balance assets:investment --value --end today",
      "locked": true
    }
  ]
}

Why this matters: The first report uses --monthly for time-series analysis, --average for baseline comparison, and --row-total for running sums. Puffin renders this interactively—change date filters and watch the monthly breakdown recalculate instantly. The second report locks market-valued investment data, ensuring your portfolio snapshot stays consistent regardless of other filters.

Example 3: V3 Minimal Configuration

For V3's streamlined approach, configuration reduces to essentials:

{
  "journalFile": "/home/user/finance/2024.journal"
}

The philosophy shift: V3 trades configuration complexity for UI sophistication. You define where your data lives; Puffin handles the rest. This is ideal for users who want immediate visual gratification without tuning report definitions.

Example 4: Shell Integration for Daily Use

Smart developers alias their most common Puffin invocations. Add to your .zshrc or .bashrc:

# Quick daily financial check
alias fin='cd ~/finance && puffin -v3'

# Specific year review
alias fin2023='puffin --config ~/.config/puffin/2023.json'

# Demo mode for screenshots (no real data exposed)
alias fin-demo='cd ~/projects/puffin && make debug'

Workflow integration: These aliases collapse "navigate to finance directory, launch tool, select view" into two keystrokes. Your financial awareness becomes as frictionless as checking git status.

Advanced Usage & Best Practices

The Locked Report Strategy

Master Puffin's locked field. My recommended setup:

• Lock: Account trees, commodity lists, custom investment commands with --value
• Unlock: Balance reports, register views, income statements you want to slice dynamically

This creates a stable foundation with flexible analysis on top.

Git-Version Your Config

Your Puffin config is JSON—treat it like code:

git init ~/finance-config
cp ~/.config/puffin/config.json ~/finance-config/
cd ~/finance-config && git add . && git commit -m "Initial Puffin config"

Now report evolution is traceable. Added a new investment account filter? That's a commit with context.

Period Grouping for Trend Detection

Puffin's weekly/monthly/quarterly/yearly toggles aren't just display options—they're analytical lenses. Monthly for budget adherence. Quarterly for seasonal patterns. Yearly for life-stage transitions. Switch frequently; patterns hide at wrong granularities.

Terminal Multiplexer Integration

Run Puffin in a dedicated tmux window:

tmux new-session -d -s finance -n puffin 'puffin -v3'
tmux attach -t finance

Your financial dashboard becomes a persistent workspace, always one tmux switch-client -t finance away.

Comparison with Alternatives: Why Puffin Wins

The verdict: Puffin occupies a unique intersection—terminal-native like hledger CLI, visually structured like a GUI, with data ownership that web apps can't match. It's not for everyone (if you hate keyboards, flee now), but for developers already committed to text-based workflows, it's the missing piece.

FAQ: Developer Concerns Addressed

Does Puffin replace hledger?

Absolutely not. Puffin is a viewer and explorer—hledger remains the engine. You still journal transactions via your preferred method (direct editing, hledger add, or import tools). Puffin makes the output beautiful, not the input obsolete.

Can I use Puffin without existing hledger knowledge?

Technically yes, but practically you'll struggle. Puffin assumes hledger's data model: accounts with colon-separated names, transaction syntax, commodity declarations. Spend 30 minutes with hledger's tutorial first—the investment pays dividends.

Is V3 stable enough for daily use?

Per the creator's February 2026 update: V3 is stable but incomplete. Core reports (accounts, balances, register, income statement, balance sheet) work beautifully. Missing features (periodic balance columns, full config support) are roadmap items. For production use, evaluate whether missing features block your workflow.

How do I contribute to development?

The GitHub repository actively welcomes contributions. V3 development is paused for personal reasons—this is an opportunity to shape the tool's future. Go knowledge and Bubble Tea familiarity are relevant; financial domain expertise is equally valuable for UX decisions.

Can I run Puffin on Windows?

Go compiles cross-platform, and Bubble Tea supports Windows terminals. However, hledger's Windows support is less mature than Unix. WSL2 is your friend here—run hledger and Puffin in Linux compatibility layer for optimal experience.

What about automated imports from banks?

Puffin doesn't handle imports—that's hledger's domain. Use hledger import with CSV rules, then launch Puffin to explore the results. This separation of concerns is intentional: hledger handles data integrity, Puffin handles presentation.

How does Puffin compare to hledger's built-in web interface?

hledger's web mode (hledger web) provides browser-based exploration. Puffin is terminal-native, faster to launch, keyboard-driven, and integrates with your existing terminal workflow. Choose web for sharing with non-technical partners; choose Puffin for personal daily use.

Conclusion: Your Terminal Deserves Financial Superpowers

Here's what I believe after years of trying every personal finance tool imaginable: the best tool is the one you'll actually use daily. For terminal-dwelling developers, that means something fast, keyboard-native, and visually informative without being bloated.

Puffin delivers exactly this. It doesn't try to be a bank replacement or a tax accountant. It's a financial awareness tool that respects your existing hledger investment and your terminal-centric workflow. The V3 interface is genuinely gorgeous by TUI standards—proof that terminal tools need not sacrifice aesthetics for efficiency.

Is it perfect? No. V3's paused development needs community support. Config migration between versions requires attention. And if you've never touched hledger, there's a learning curve.

But the alternative—staying in spreadsheet hell or surrendering your data to proprietary clouds—is far worse.

My recommendation: Install via Homebrew today. Point it at your existing hledger file (or the demo data). Spend 15 minutes exploring the keyboard shortcuts. Notice how quickly you develop intuition for your financial patterns when the interface gets out of your way.

Then decide: is this the year your finances get as much engineering attention as your code?

Star the repository, open an issue with your use case, and consider contributing. The future of developer-centric personal finance tooling depends on communities recognizing that our terminals can handle more than just code—they can handle our most important resource.

👉 Get Puffin on GitHub — Your wallet will thank you. Your terminal already misses you.