How to use the command 'hledger add' (with examples)

The hledger add command is a powerful tool used within the hledger suite to record new financial transactions interactively via the console. It provides a streamlined way to create and manage journal entries using a system of prompts that guide the user through the process. The command is ideal for users who prefer a command-line interface to manage their financial records, offering flexibility and precision in documenting transactions.

Use case 1: Record new transactions, saving to the default journal file

Code:

hledger add

Motivation:

This use case is perfect for users who want to quickly add a new transaction to their financial records without specifying any additional parameters. By using the default journal file, users can maintain simplicity and efficiency, ensuring that their day-to-day transactions are promptly recorded.

Explanation:

• hledger add: This command initiates the interactive prompting process for adding a new transaction. When executed, hledger will automatically open the default journal file where all transactions are stored, prompting the user to enter details such as date, description, account names, and amounts.

Example Output:

Date: 2023/10/12
Description: Lunch at cafe
Account 1: expenses:food
Amount 1: $10
Account 2: assets:cash
Amount 2: -$10

Use case 2: Add transactions to 2024.journal, but also load 2023.journal for completions

Code:

hledger add --file path/to/2024.journal --file path/to/2023.journal

Motivation:

This option is especially useful for users managing multi-year financial data. By specifying multiple journal files, users can ensure that historical data from 2023 is available for references and auto-completions while adding new records for 2024. This is helpful in maintaining continuity and avoiding errors, as it leverages past records to guide the user.

Explanation:

• hledger add: Starts the transaction recording process.
• --file path/to/2024.journal: Specifies the target journal file for saving new transactions, focusing on the financial year 2024.
• --file path/to/2023.journal: Also loads the previous year’s journal, 2023, enabling data from this year to be used for auto-completion and reference purposes.

Example Output:

Adding transactions to 2024.journal, with completions from 2023.journal
Date: 2024/01/05
Description: Office supplies
Account 1: expenses:supplies
Amount 1: $45.00
Account 2: assets:bank
Amount 2: -$45.00

Use case 3: Provide answers for the first four prompts

Code:

hledger add today 'best buy' expenses:supplies '$20'

Motivation:

This example is tailored for advanced users who prefer speed and efficiency. By providing arguments directly in the command line, users can bypass the interactive prompts and quickly record a transaction. It’s especially useful for frequently-occurring transactions where the details are known in advance.

Explanation:

• hledger add: Initiates the transaction addition process.
• today: Automatically sets the transaction date to the current date.
• 'best buy': The description of the transaction, indicating a purchase at Best Buy.
• expenses:supplies: The account to debit, categorizing the transaction under expenses for supplies.
• '$20': The amount of the transaction, specifying it is a $20 expense.

Example Output:

Added to journal: 2023/10/10 best buy
  expenses:supplies $20
  assets:cash -$20

Use case 4: Show add’s options and documentation with $PAGER

Code:

hledger add --help

Motivation:

For new users or those needing a quick refresher, accessing the help documentation is crucial. This command provides a comprehensive list of all options and usage instructions related to hledger add, aiding users in understanding the full capabilities of the command.

Explanation:

• hledger add: Refers to the add functionality of the hledger suite.
• --help: Instructs hledger to display the help documentation, which will be shown using the system’s default pager (typically less or more), allowing users to scroll and read through the information easily.

Example Output:

usage: hledger add [OPTIONS]

Options:
  -f, --file=FILE     Use a different journal file.
  -h, --help          Show this help message and exit.
  ...

Use case 5: Show add’s documentation with info or man if available

Code:

hledger help add

Motivation:

This example serves advanced users or administrators who need detailed technical documentation for hledger add. Using a system’s info or man command, users can access the entire manual that includes deep insights into the command structure, examples, and customization options.

Explanation:

• hledger help: Fetches the help or manual documentation for a specific function within the hledger suite.
• add: Specifies that we want documentation related to the add functionality.

Example Output:

hledger add: Record transactions with interactive prompting

Synopsis
    hledger add [OPTION]...
    
Description
    Add is an interactive command for adding transactions to a hledger journal file...

Conclusion:

The hledger add command is a versatile tool within the hledger suite designed to streamline the process of adding financial transactions. Each use case offers unique features tailored to various user needs—whether simplicity, speed, historical data integration, or access to command documentation. Mastering these examples can significantly enhance your experience in managing financial records effectively through a command-line interface.