hledger-add

Record new transactions, saving to the default journal file

$ hledger add

$ hledger add [[-f|--file]] [path/to/2024.journal] [[-f|--file]] [path/to/2023.journal]

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

$ hledger add [[-h|--help]]

$ hledger help add

hledger add []

-f FILE, --file=FILE
    Specifies the main journal file to use for adding the entry.

-o FILE, --output-file=FILE
    Writes the newly added entry to the specified file instead of the default journal file.

-i FILE, --input-file=FILE
    Reads the new entry content from the specified file rather than prompting interactively.

-u, --unbalanced
    Allows the creation of entries where total debits do not equal total credits.

-x, --external
    Opens the entry content in an external text editor for modification before saving.

--auto-balance
    Automatically calculates and applies the balancing amount to the last account entered.

--dry-run
    Prints the entry that would be added to standard output without actually writing it to the journal file.

--force
    Used with -o, it overwrites the output file if it already exists.

--no-history
    Disables the suggestion of past values for interactive prompts like description and account names.

--no-hints
    Suppresses the display of helpful hints during the interactive entry process.

--edit-entry
    Opens the newly added entry in an external editor immediately after it's saved.

--edit-last
    Opens the last saved entry in the journal file in an external editor.

--edit-last-path=PATH
    Specifies a particular file to open with --edit-last.

hledger-add is an interactive subcommand of the hledger command-line accounting system, designed to simplify the process of adding new financial transactions (journal entries) to your ledger file. It guides you through a series of prompts for essential transaction details, including the date, a descriptive narration (payee/description), and individual account postings with their respective amounts. The command intelligently suggests dates, descriptions, and account names based on past entries, significantly accelerating data input and reducing errors. It also ensures that entries are balanced (debits equal credits) before writing them to the journal file, enhancing the integrity of your financial records. This interactive, guided approach makes managing finances with hledger more accessible, particularly for users who prefer a structured input method over direct text file manipulation.

hledger-add is primarily designed for interactive use; scripting it directly without -i requires careful handling of standard input. The --input-file option fundamentally alters its behavior from interactive input to batch processing. It relies on a properly configured hledger environment, including a journal file. Errors in manually entered account names or amounts may lead to incorrect entries if not reviewed carefully during the interactive process.

hledger-add guides the user through a structured series of prompts for each part of a transaction:

1. Date: Defaults to the current date, with easy navigation for other dates.
2. Description: For payee or narration, often suggesting past descriptions.
3. Postings: Prompts for account names and amounts. It offers auto-completion for existing accounts and helps ensure entries balance.

By default, hledger-add enforces that each transaction entry is balanced, meaning the sum of all debits must equal the sum of all credits. If an entry is unbalanced during input, the command will prompt the user to correct it. Alternatively, the --unbalanced flag can be used to bypass this check, or the --auto-balance option can automatically calculate and apply the necessary balancing amount to the last entered posting.

hledger-add is a core component of the hledger plain text accounting system, which draws inspiration from the original Ledger software. Developed in Haskell, hledger aims to provide a robust, cross-platform solution for financial tracking. The add subcommand was introduced to offer a more user-friendly, interactive method for inputting transactions, addressing the demand for a guided data entry process that many users prefer over manual text file editing. Its ongoing development focuses on enhancing user experience through features like smart suggestions, auto-completion, and real-time balancing, making hledger more accessible to a wider user base.

hledger(1), hledger-edit(1), hledger-balance(1), hledger-print(1), hledger-register(1)