hledger-import

Import new transactions from bank.csv, using bank.csv.rules to convert

$ hledger import [path/to/bank.csv]

$ hledger import [path/to/bank1.csv] [path/to/bank2.csv] --dry-run

$ hledger import --rules-file [common.rules] *.csv

$ watchexec -- hledger [[-f|--file]] [path/to/bank.csv] print

$ hledger import --catchup [path/to/bank.csv]

$ rm [[-f|--force]] .latest.bank.csv

hledger-import [OPTION...] [FILE...]

-f FILE, --file=FILE
    Specify the main journal file to read and write. Defaults to ~/.hledger.journal or .hledger.journal.

-r FILE, --rules-file=FILE
    Load import rules from the specified file. This is essential for customizing how transactions are parsed and assigned.

-p, --print
    Instead of adding entries to the journal file, print the generated entries to standard output. Useful for testing rules.

-i, --interactive
    Run in interactive mode. This is the default if neither --auto nor --add is specified. It prompts the user for confirmation or input for each transaction.

-a, --auto
    Run in automatic (non-interactive) mode. Transactions are processed according to rules without user intervention. Existing entries are skipped.

--add
    Run in automatic mode and add entries directly to the journal. Implies --auto and overrides --interactive.

--dry-run
    Process transactions but do not make any changes to the journal file. Shows what would happen if the command were run normally.

--ignore-existing
    Do not skip entries that already exist in the journal. By default, hledger-import tries to avoid duplicating transactions.

--infer-rules
    Attempt to infer import rules from the input data. This can help in generating a starting point for a rules file (experimental).

--write-rules-file=FILE
    Write inferred rules to the specified file. Useful when combined with --infer-rules.

-v, --verbose
    Show more detailed output, including debug information about the parsing process.

--rules=TEXT
    Provide import rules directly as a string on the command line instead of from a file.

--data=TEXT
    Provide input data directly as a string on the command line instead of from a file.

hledger-import is a crucial utility within the hledger plaintext accounting system.
It streamlines the process of importing financial transactions from various external data sources, such as CSV, OFX, and QIF files, directly into your hledger journal. The command operates by applying a set of user-defined rules, typically specified in a .rules file, to parse and transform the raw financial data.
These rules dictate how to identify transaction dates, amounts, descriptions, and assign accounts, enabling highly customized and repeatable import workflows. It supports both interactive modes for manual review and adjustment, and fully automatic modes for batch processing, significantly reducing the effort of manual data entry and ensuring data consistency in your financial records.

Effective use of hledger-import heavily relies on well-crafted .rules files, which can have a significant learning curve.
These rules are crucial for correctly parsing diverse financial data formats and mapping them to your desired hledger accounts. Be mindful of potential data inconsistencies from source files, which may require rule adjustments or manual intervention to ensure accurate financial records.

The power of hledger-import lies in its declarative rules files. A rules file contains directives that instruct hledger-import how to parse specific data files.
Rules define patterns to match lines in the input data (e.g., CSV columns, OFX fields), extract relevant information like date, amount, description, and assign them to hledger entries. They also specify posting accounts, commodities, and apply transformations or conditions to automate account assignments.
This allows for highly flexible and automated categorization of transactions.

When running hledger-import, you can choose between interactive and automatic modes.
In interactive mode (default, or with -i), the command will prompt you for confirmation or allow you to edit each proposed transaction before adding it to your journal. This is useful for initial setup or when dealing with unfamiliar transactions.
In automatic mode (with -a or --add), hledger-import processes transactions without user intervention, relying entirely on the defined rules. This is ideal for batch processing recurring imports once your rules are well-tested.

hledger-import is an integral part of the hledger project, an open-source plain text accounting system. hledger itself was created by Simon Michael around 2008 as a modern, Haskell-based alternative to the original Ledger command-line accounting tool.
Over the years, hledger-import has evolved significantly, adding support for various data formats (CSV, OFX, QIF) and sophisticated rule-based parsing, becoming a cornerstone for automating transaction workflows for its users.

hledger(1), hledger-add(1), hledger-print(1), hledger-web(1)