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

The hledger accounts command is a versatile tool that helps users to manage and view accounts in their financial journal files. It is part of the hledger suite, which is a lightweight yet powerful tool for personal or small business accounting. The command provides various options for listing account names, giving users the ability to organize, filter, and display account details from their financial records with precision and customization.

Use case 1: Show all accounts used or declared in the default journal file

Code:

hledger accounts

Motivation:

This basic usage of the hledger accounts command is essential for anyone who is just getting started with financial record-keeping in hledger. By running this command, users can quickly see a complete list of all accounts either used or declared within their default journal file. This is useful for gaining an overview of the existing accounts and supports easy verification and review.

Explanation:

• hledger: The core command suite for accounting.
• accounts: Subcommand that specifically deals with listing account names.

Example Output:

assets:bank:checking
expenses:utilities
income:salary
liabilities:credit_card

Use case 2: Show accounts used by transactions

Code:

hledger accounts --used

Motivation:

Users often want to focus on accounts that are actively being used in transactions, rather than seeing every single account declared. This command filters out accounts that are not associated with any transactions, making it easier to identify where financial activities are occurring and to focus on relevant financial data.

Explanation:

• --used: This flag filters the results to show only accounts that have been actively used in recorded transactions.

Example Output:

assets:bank:savings
expenses:groceries
income:freelancing

Use case 3: Show accounts declared with account directives

Code:

hledger accounts --declared

Motivation:

This option is particularly useful for users who meticulously plan their accounts in advance by declaring them without yet using them in transactions. It allows them to list accounts that have been set up but not necessarily used, enabling strategic planning or auditing of financial structure.

Explanation:

• --declared: This argument shows only the accounts explicitly declared in the journal file.

Example Output:

assets:investments:stock
expenses:education

Use case 4: Add new account directives, for accounts used but not declared, to the journal

Code:

hledger accounts --undeclared --directives >> 2024-accounts.journal

Motivation:

This is incredibly useful for users who need to update their journal files by adding accounts that have been used in transactions but were never formally declared. It helps maintain consistency and completeness in the financial records by ensuring all active accounts are properly documented in the journal.

Explanation:

• --undeclared: It identifies accounts that are used but not declared.
• --directives: Generates account directives for those undeclared accounts.
• >> 2024-accounts.journal: Appends the new account directives to the specified journal file.

Example Output:

Appending the following to 2024-accounts.journal:
account liabilities:loans
account expenses:healthcare

Use case 5: Show accounts with ‘asset’ in their name, and their declared/inferred types

Code:

hledger accounts asset --types

Motivation:

For users managing complex financial account structures, it’s useful to filter and specifically list accounts related to assets while also viewing their types. This helps in organizing and verifying asset-related accounts while distinguishing between declared and inferred account types.

Explanation:

• asset: This searches for accounts containing the term ‘asset’ in the account name.
• --types: Displays both the declared and inferred types of the accounts.

Example Output:

assets:bank:checking (declared)
assets:investment:real_estate (inferred)

Use case 6: Show accounts of the ‘Asset’ type

Code:

hledger accounts type:A

Motivation:

This usage is perfect for those who want to isolate and focus primarily on asset accounts, allowing efficient review and management of all accounts classified under this type. It’s beneficial to know exactly which accounts are related to assets for future investment planning or evaluations.

Explanation:

• type:A: Filters the results to include only accounts of the asset type.

Example Output:

assets:property
assets:bank:savings

Use case 7: Show the first two levels of the accounts hierarchy

Code:

hledger accounts --tree --depth 2

Motivation:

Users who manage a hierarchically structured account system might need to view the top-level organization of their accounts. This command allows for a concise view of the account structure up to a specified depth, helping users understand and navigate the hierarchy more efficiently.

Explanation:

• --tree: Outputs the accounts in a hierarchical tree format.
• --depth 2: Limits the display to the first two levels of the account hierarchy.

Example Output:

assets
  bank
  investments
expenses
  groceries
  utilities

Use case 8: Short form of showing the first two levels of the accounts hierarchy

Code:

hledger acc -t -2

Motivation:

This short form provides the same functionality as the previous use case but with less typing. It’s a convenient way for users who frequently perform this operation, saving time and effort while ensuring the same high-level view of accounts hierarchy is obtained.

Explanation:

• acc: Abbreviated form of the accounts subcommand.
• -t: Short form of the --tree option.
• -2: Short form of the --depth 2 option.

Example Output:

assets
  bank
expenses
  entertainment

Conclusion:

The hledger accounts command is a powerful utility within the hledger toolkit, offering a diverse set of functionalities for managing and exploring financial accounts. By using the various options and filters, users can tailor their experience to suit their specific needs, whether it be auditing their complete list of accounts, focusing on active or planned accounts, or understanding the hierarchical structure of their financial records.