How to Use the Command 'hledger' (with Examples)
The ‘hledger’ command is a versatile, plain-text accounting tool that simplifies financial tasks and provides a robust platform for managing personal or business finances. It’s designed for those who appreciate the power of plain-text files and need a comprehensive system for accounting operations. Paired with complementary tools like hledger-ui
for terminal interface or hledger-web
for browser-based interaction, hledger becomes a powerful ally in financial management.
Use Case 1: Record New Transactions Interactively
Code:
hledger add
Motivation:
Recording financial transactions is a daily necessity for both individuals and businesses. The hledger add
command helps users effortlessly document these transactions, ensuring that no detail is overlooked. By using this command, users can interactively add new entries to their default journal file quietly and efficiently, making the process seamless.
Explanation:
hledger
: Invokes thehledger
program.add
: Launches an interactive mode where users can input new transactions, which the system appends to the default journal file, usually namedjournal
. This interactive mode ensures that the user is prompted for all necessary transaction details, reducing the risk of error.
Example Output:
Adding transactions to journal...
Date: 2023-10-01
Description: Grocery shopping
Amount: $50
Account: expenses:groceries
Account: assets:cash
Transaction recorded.
Use Case 2: Import New Transactions from CSV
Code:
hledger import path/to/bank.csv
Motivation:
Managing finance often involves handling data from various sources, like bank statements in CSV format. The hledger import
command is perfect for users who want to streamline this process by converting CSV data into hledger’s journal format, using conversion rules defined in another file.
Explanation:
hledger
: Calls thehledger
program.import
: Imports transactions from a CSV file into the journal.path/to/bank.csv
: Specifies the path to the CSV file containing new transactions. This file is examined using rules listed in a correspondingbank.csv.rules
file, ensuring accurate data transformation.
Example Output:
Importing transactions from bank.csv...
5 transactions imported.
Use Case 3: Print All Transactions from Multiple Journal Files
Code:
hledger print --file path/to/prices-2024.journal --file path/to/prices-2023.journal
Motivation:
Access to comprehensive financial records is crucial for various analysis and auditing tasks. By using the hledger print
command with multiple files, users can collate transaction details from different journals, ensuring precision in overview requirements.
Explanation:
hledger
: Executes thehledger
program.print
: Specifies the command to display all transactions.--file path/to/prices-2024.journal --file path/to/prices-2023.journal
: Lists the journal files to be read for collating transaction data. Each--file
option denotes a unique path for journal files that the command processes in sequence.
Example Output:
2023/01/01 Payment Received
assets:bank $2500
income:salary
2024/05/01 Car Repair Expense
expenses:auto $400
liabilities:credit_card
Use Case 4: Show All Accounts as a Hierarchy
Code:
hledger accounts --tree --types
Motivation:
Understanding the structure and types of accounts at a glance can aid significantly in financial analysis and category management. The hledger accounts
command provides a simple hierarchical view, which is especially beneficial for users needing clarity in account dependencies and relationships.
Explanation:
hledger
: Invokes thehledger
program.accounts
: Displays all available accounts.--tree
: Provides a hierarchical presentation, outlining sub-accounts under main accounts clearly.--types
: Includes the types of accounts in the output, which clarifies their purpose (e.g., asset, liability).
Example Output:
assets:bank:checking [Asset]
assets:bank:savings [Asset]
expenses
expenses:groceries [Expense]
expenses:utilities [Expense]
income [Income]
Use Case 5: Display Asset and Liability Account Balances
Code:
hledger balancesheet --empty --tree --no-elide
Motivation:
For a thorough review of current financial health, users need to see all balances, including zero balances. This command lists asset and liability balances hierarchically, providing users with comprehensive insights into financial standing.
Explanation:
hledger
: Calls thehledger
program.balancesheet
: Displays a balance sheet of assets and liabilities.--empty
: Includes accounts with zero balances, providing a complete overview.--tree
: Exhibits the account structure hierarchically.--no-elide
: Ensures that all details are displayed without abbreviation, offering full visibility to users.
Example Output:
Assets (Total: $3500)
bank:checking: $1000
bank:savings: $2500
Liabilities (Total: $0)
credit_card: $0
Use Case 6: View Monthly Incomes/Expenses Totals
Code:
hledger incomestatement --monthly --row-total --average --sort --depth 2
Motivation:
This command is particularly useful for observing financial trends on a monthly basis, aiding in budgeting and financial planning. By showing expenditures and income in summarized form, users can quickly identify patterns and focus areas.
Explanation:
hledger
: Launches thehledger
program.incomestatement
: Generates a report of income and expenses.--monthly
: Divides the report by each month.--row-total
: Adds a row for totals, facilitating an easy overview.--average
: Includes averages, allowing users to quickly assess financial patterns.--sort
: Sorts results, typically placing larger totals first for effective analysis.--depth 2
: Restricts details to 2 levels of the account hierarchy.
Example Output:
Month Income Expenses
January $5000 $3000
February $5100 $3100
Use Case 7: Show Transactions and Balance for a Specific Account
Code:
hledger aregister assets:bank:checking
Motivation:
Financial oversight demands particular attention to specific account movements. The hledger aregister
command allows users to focus on a single account’s transactional flow and balance, essential for targeted analysis or accountability.
Explanation:
hledger
: Initiates thehledger
program.aregister
: Produces a register report showing transactions and running balances.assets:bank:checking
: Indicates the account specific for reporting, targeting only transactions associated with this account.
Example Output:
2023/03/01 Payment assets:bank:checking $2000 $3000
2023/05/01 Groceries assets:bank:checking -$150 $2850
Use Case 8: Determine Spending on Food from Cash Account
Code:
hledger print assets:cash | hledger -f- -I aregister expenses:food
Motivation:
Analyzing specific expenditure categories such as ‘food’ can highlight spending habits and guide budget adjustments. This two-part command sequence adeptly filters and focuses on food-related spending sourced from cash transactions.
Explanation:
hledger
: Executes thehledger
program.print assets:cash
: Outputs all transactions associated with theassets:cash
account.- The
|
: Pipe operator, passes the output as input to the subsequent command. hledger -f- -I aregister expenses:food
: Reads the piped transactions (-f-
) and instantly registers (aregister
) only those involvingexpenses:food
, enabling precise analysis.
Example Output:
2023/02/15 Groceries expenses:food -$60 $540
2023/03/01 Dining expenses:food -$40 $500
Conclusion:
The hledger suite commands are complex but invaluable tools for any finance-oriented user looking to leverage plain-text accounting to its fullest potential. By understanding and applying each use case, users can effectively manage, analyze, and gain insights into their financial transactions and positions. Whether you’re importing data from various sources, scrutinizing specific accounts, or summarizing financial performance, hledger commands provide all the necessary functionality for comprehensive financial management.