hledger-balance

Show the balance change in all accounts from all postings over all time

$ hledger [[bal|balance]]

$ hledger [[bal|balance]] [expenses] [[-t|--tree]] [[-2|--depth 2]]

$ hledger [[bal|balance]] [expenses] [[-M|--monthly]] [[-T|--row-total]] [[-A|--average]] [[-S|--sort-amount]] --budget

$ hledger [[bal|balance]] type:[X] [[-MTAS|--monthly --row-total --average --sort-amount]] --budget [[-t|--tree]] [[-2|--depth 2]] --no-elide

$ hledger [[bal|balance]] [[-H|--historical]] [[-p|--period]] '[quarterly in 2024]' [assets] [liabilities]

$ hledger [[bal|balance]] [[-HQ|--historical --quarterly]] date:[2024] type:[AL] [[-ES|--empty --sort-amount]] [[-3|--depth 3]]

$ hledger [[bal|balance]] [[-HVQ|--historical --market --quarterly]] [assets:investments]

$ hledger [[bal|balance]] --gain [[-Q|--quarterly]] [assets:investments] not:[cryptocurrency]

hledger balance [OPTIONS...] [QUERY...]

--file=FILE, -fFILE
    Specify the journal file(s) to read. Defaults to ~/.hledger.journal or ./.hledger.journal.

--begin=DATE, -bDATE
    Start date for transactions. Only transactions on or after this date are included.

--end=DATE, -eDATE
    End date for transactions. Only transactions on or before this date are included.

--period=PERIODEXPR, -pPERIODEXPR
    Filter transactions by a specific period expression (e.g., 'last month', '2023', '2023/1/1-2023/3/31').

--daily, -D
    Show daily balances. Useful with --begin/--end or --period.

--monthly, -M
    Show monthly balances.

--yearly, -Y
    Show yearly balances.

--empty, -E
    Include accounts with zero balances in the report.

--extended, -x
    Show an extended balance report including opening, closing, and change balances.

--tree, -T
    Display accounts in a hierarchical tree structure, reflecting their full names.

--depth=N
    When using tree view, limit the depth of displayed accounts (e.g., --depth=2 shows only top two levels).

--pretty, -P
    Format output more prettily, aligning columns and adding visual separation.

--no-total, -N
    Do not show the grand total line at the bottom of the report.

--sort=FIELD, -sFIELD
    Sort accounts by a specified field (e.g., 'name', 'balance', 'last-date').

--sort-amounts, -S
    Sort accounts by their total balance amount in descending order.

--cost
    Show balances using transaction costs instead of market values.

--value
    Show balances using market values at the report's end date, requiring price entries.

--pivot=FIELD
    Pivot the balance report by a transaction field (e.g., 'tag', 'payee'), creating columns for each value.

QUERY...
    Optional query expressions to filter accounts or transactions (e.g., 'Expenses', 'account:Assets', 'tag:home').

hledger-balance is a core command of the hledger plain text accounting system. It computes and displays the current or historical balances of accounts defined in your hledger journal files. This command is essential for understanding your financial position, tracking assets, liabilities, income, and expenses over various periods. It supports filtering by account name or transaction properties, aggregating balances by day, month, or year, and presenting the data in various formats including a hierarchical tree view. hledger-balance provides a flexible way to generate financial reports directly from your human-readable ledger data.

hledger-balance's performance can degrade with very large journal files or complex queries, especially when date-range filters are applied on every command execution against the entire journal. While highly flexible, generating intricate custom reports may sometimes require piping output to other command-line tools like grep, awk, or sort. Revalued balances (using --value) rely on accurate and complete price entries in the journal file; their accuracy directly depends on the quality of this data.

The `QUERY` arguments allow powerful filtering of accounts and transactions. For example, `hledger balance expenses` shows only expense accounts, `hledger balance tag:rent` shows balances for transactions tagged 'rent', and `hledger balance assets 2023/01/01` shows asset balances at the start of 2023.

Beyond basic formatting with --tree and --pretty, hledger-balance offers advanced options like --balance-format and --balance-columns for fine-grained control over the output columns and their display. This enables users to create highly specific and customized balance report layouts to suit their analytical needs.

hledger was created as an independent, Haskell-based reimplementation of ledger, aiming for improved code clarity, ease of development, and different design choices while maintaining compatibility with the plain text ledger file format. hledger-balance is one of its fundamental commands, mirroring the functionality of ledger's `balance` command, and has been a core part of hledger since its early development. It has continuously evolved with new features like pivot tables and enhanced formatting options to meet diverse reporting needs.

hledger(1): The main hledger program and its general options., hledger-register(1): Displays a detailed transaction list (register) for specified accounts., hledger-cashflow(1): Calculates and displays cash flow statements from journal data., ledger(1): The original command-line accounting system written in C++, a predecessor to hledger.