How to Use the Command 'hledger balance' (with Examples)

The hledger balance command is a powerful tool within the hledger suite, geared towards generating comprehensive financial reports. Whether you need to track balance changes over various periods, understand budget performance, or assess unrealised capital gains, this versatile command has options to tailor the output for any accounting situation. Its purpose is to make sense of numeric data found across different accounts by summarizing it in flexible, accessible formats.

Use Case 1: Show the Balance Change in All Accounts from All Postings Over All Time

Code:

hledger balance

Motivation:
This simple use case is aimed at providing a general overview of your financial situation by calculating the ending balance changes for all accounts globally. It is an essential starting point for anyone looking to grasp an overall picture of their financial flows without focusing on a specific period or account.

Explanation:
The command without any additional arguments defaults to summarizing all financial data available, giving a straightforward snapshot of the balance changes across all accounts. This command doesn’t apply any filters or conditions; hence, it is broad but informative.

Example Output:

          Assets: Cash          $500.00
          Expenses: Food       $-200.00
          Income: Salary        $700.00
---------------------------------------
                          Total: $500.00

Use Case 2: Show the Balance Change in Accounts Named *expenses*, as a Tree, Summarising the Top Two Levels Only

Code:

hledger balance expenses --tree --depth 2

Motivation:
Users looking to understand how their expenses are distributed across different categories will find this use case extremely beneficial. By filtering and organizing expenses into a tree structure, it allows for a clear visualization of how high-level expenses are spread across various subcategories.

Explanation:

• expenses: This argument scopes the balance report to only include accounts with “expenses” in their names.
• --tree: It structures the accounts hierarchically, displaying a more visually organized report.
• --depth 2: Limits the depth of the tree to the top two levels, providing a summary without excessive detail.

Example Output:

Expenses                            
  Food                              $100.00
  Transport                         $150.00
----------------------------------------
                                    $250.00

Use Case 3: Show Expenses Each Month, and Their Totals and Averages, Sorted by Total; and Their Monthly Budget Goals

Code:

hledger balance expenses --monthly --row-total --average --sort-amount --budget

Motivation:
This use case is designed for users who need a detailed analysis of their monthly expenses, including how close they are to meeting predefined budget targets. Regular tracking of expenses against budget goals is crucial for effective financial planning.

Explanation:

• --monthly: Breaks down the report by month.
• --row-total: Adds a total for each row, summarizing each account’s cumulative amount over the periods.
• --average: Computes averages, aiding comparison against monthly amounts.
• --sort-amount: Sorts accounts by the total amount, placing the largest at the top for easy identification.
• --budget: Integrates budget goals into the report, highlighting areas where spending aligns with or deviates from the plans.

Example Output:

      Jan    Feb    Mar   Total Avg   Budget
Food $100 $150 $50   $300 $100 $120
Transport $60 $70 $80 $210 $70 $75

Use Case 4: Similar to the Above, Shorter Form, Matching Accounts by Expense Type, as a Two-Level Tree Without Squashing Boring Accounts

Code:

hledger bal type:X -MTAS --budget -t -2 --no-elide

Motivation:
Users focusing on trimmed yet comprehensive data regarding specific account types will benefit from this example. It offers a concise report with controlled verbosity, ensuring that even less significant accounts are included if they exist.

Explanation:

• type:X: Matches all accounts of type “Expense”.
• -M: Induces monthly breakdown.
• -T, -A, -S: Respectively enable top account tree structure, averaging, and sorting by total.
• --budget: Includes budget comparison.
• -t -2: Specifies a two-level tree structure.
• --no-elide: Avoids hiding low-activity (boring) accounts.

Example Output:

Expense:Food 
  Monthly 
    $200  
  Average 
    $100 
  Budget 
    $110
Expense:Transport
  Monthly 
    $180  
  Average 
    $90 
  Budget 
    $100

Use Case 5: Show End Balances (Including from Postings Before the Start Date), Quarterly in 2024, in Accounts Named *assets* or *liabilities*

Code:

hledger balance --historical --period 'quarterly in 2024' assets liabilities

Motivation:
This example serves users who need a periodic view of end balances, particularly useful for assessing financial health at multiple points throughout the year, and accounting for all historical postings.

Explanation:

• --historical: Considers past postings for end balance calculations, extending the report to a full financial history.
• --period 'quarterly in 2024': Aggregates the data into quarterly segments for the year 2024.
• assets liabilities: Limits accounts to those with ‘assets’ or ’liabilities’ in the name, reflecting balance sheet components.

Example Output:

Assets
  Q1 $1500
  Q2 $1450
Liabilities
  Q1 $1000
  Q2 $950

Use Case 6: Similar to the Above, Shorter Form; Also Show Zero Balances, Sort by Total and Summarise to Three Levels

Code:

hledger bal -HQ date:2024 type:AL -ES -3

Motivation:
This example appeals to users needing a succinct report similar to Use Case 5 but requiring detailed insights even on dormant accounts.

Explanation:

• -H: Displays historical data.
• -Q: Segments the report quarterly.
• date:2024: Operates within the year 2024.
• type:AL: Includes only ‘asset’ and ’liability’ types.
• -ES: Enables zero balances and sorts by total values.
• -3: Limits tree depth to three levels for controlled elaboration.

Example Output:

Assets
  Sub1
    Q1 $1500
    Q2 $1450
Liabilities
  Sub1
    Q1 $1000
    Q2 $950

Use Case 7: Show Investment Assets’ Market Value in Base Currency at the End of Each Quarter

Code:

hledger bal -HVQ assets:investments

Motivation:
Useful for investment portfolio oversight, this use case delivers insight into the market valuation of investments, a critical factor for strategic planning in investments.

Explanation:

• -H: Compiles historical data.
• -V: Converts market values into a base currency.
• -Q: Reports quarterly.
• assets:investments: Limits report to investment-related asset accounts.

Example Output:

Investments
  Q1 $3000
  Q2 $3200

Use Case 8: Show Unrealised Capital Gains/Losses from Market Price Changes in Each Quarter, for Non-Cryptocurrency Investment Assets

Code:

hledger bal --gain -Q assets:investments not:cryptocurrency

Motivation:
This example is imperative for investors keen on monitoring potential gains or losses, enabling timely financial decisions related to market conditions affecting traditional investments.

Explanation:

• --gain: Calculates unrealized capital gains/losses due to market price changes.
• -Q: Dissects data quarterly.
• assets:investments: Involves only traditional investment assets.
• not:cryptocurrency: Explicitly excludes cryptocurrency assets.

Example Output:

Investments
  Q1 $200 gain
  Q2 $180 loss

Conclusion:

The hledger balance command offers a myriad of options adaptable to various accounting needs, from broad financial overviews to detailed budget and investment analyses. Its flexibility through the use of arguments makes it suitable for personal finance management as well as comprehensive business strategies, empowering users with the tools to make informed decisions based on precise financial data.