hledger-iadd: A terminal UI as drop-in replacement for hledger add

[ bsd3, console, finance, library, program ] [ Propose Tags ]

This is a terminal UI as drop-in replacement for hledger add.

It improves in the following ways on hledger's add command:

[Skip to Readme]
Versions [faq] 1.1, 1.1.1, 1.1.2, 1.1.3, 1.1.4, 1.2, 1.2.1, 1.2.2, 1.2.3, 1.2.4, 1.2.5, 1.2.6, 1.3.0, 1.3.1, 1.3.2, 1.3.3, 1.3.4, 1.3.5, 1.3.6, 1.3.7, 1.3.8, 1.3.9, 1.3.10, 1.3.11, 1.3.12 (info)
Change log ChangeLog.md
Dependencies base (>=4.8 && <5), brick (>=0.14 && <0.16), containers, directory, free (>=4.12.4), hledger-iadd, hledger-lib (==1.0.*), megaparsec (>=5.0 && <5.2), microlens, optparse-applicative, text, text-format, text-zipper, time (>=1.5), transformers (>=0.3), unordered-containers, vector, vty (>=5.4), xdg-basedir [details]
License BSD-3-Clause
Copyright 2016 Hans-Peter Deifel
Author Hans-Peter Deifel <hpd@hpdeifel.de>
Maintainer Hans-Peter Deifel <hpd@hpdeifel.de>
Revised Revision 1 made by hpdeifel at 2016-12-11T14:10:35Z
Category Finance, Console
Home page https://github.com/hpdeifel/hledger-iadd#readme
Bug tracker https://github.com/hpdeifel/hledger-iadd/issues
Source repo head: git clone https://github.com/hpdeifel/hledger-iadd.git
Uploaded by hpdeifel at 2016-12-11T14:08:29Z
Distributions NixOS:1.3.12
Executables hledger-iadd
Downloads 14737 total (23 in the last 30 days)
Rating (no votes yet) [estimated by Bayesian average]
Your Rating
  • λ
  • λ
  • λ
Status Hackage Matrix CI
Docs available [build log]
Last success reported on 2016-12-11 [all 1 reports]




Note: This package has metadata revisions in the cabal description newer than included in the tarball. To unpack the package including the revisions, use 'cabal get'.

Maintainer's Corner

For package maintainers and hackage trustees

Readme for hledger-iadd-1.1.1

[back to package description]


An interactive terminal UI as drop-in replacement for hledger add.



This project improves in the following ways on hledger's add command:

  • Interactive as-you-type completion for account names and descriptions with optional fuzzy matching (see below).

  • Integrated calculator: Amounts can be written as simple sums with real-time feedback on the result.

  • All actions while entering a transaction can be undone

  • Configurable format for date input. Instead of y/m/d it is also possible to use other formats like the german d.m.y.



The easiest method would be stack: Install the stack program, cd to hledger-iadds source directory and type:

stack install

To build and install all Haskell dependencies locally and install hledger-iadd to ~/.local/bin. See stack --help for more options. You may get asked to install the GHC Haskell compiler locally. To do that, type stack setup.


First, install the GHC Haskell compiler and the cabal install, alex and happy build tools, possibly from your distribution or the haskell platform.

Since cabal builds regularly break in non-isolated environments, the recommended next step is to create a cabal sandbox where all dependencies will be installed in:

cd hledger-iadd
cabal sandbox init

You can now download and install all dependencies locally with

cabal install --only-dependencies

And finally you're ready to build and install hledger-iadd:

cabal configure --bindir ~/bin
cabal build
cabal copy


You can start the program either with

hledger iadd

or simply hledger-iadd.

The following command line options are available:

  • -f/--file/: Path to the journal file. (Default: ~/.hledger.journal)
  • --date-format: Format for parsing dates. (Default: [[%y/]%m/]%d, the usual ledger date format). Brackets can be used to specify optional parts. E.g the german date format would be %d[.[%m[.[%y]]]]
  • --completion-engine: Algorithm for account name completion. Can be substrings or fuzzy.
  • --dump-default-config: Print the example config file to stdout and exit

The UI is partitioned in 4 regions:

Current Transaction (view of your work in progress)
Question: [ text area                             ]
Context information (e.g. list of accounts)

Message area

For each transaction, you will get asked the following questions in order:

  1. Date?
  2. Description?
  3. Account name?
  4. Amount?
  5. The last two questions are repeated until you enter the empty account
  6. Do you want to add this transaction to the journal?

To accept the default answer, immediately press <kbd>Return</kbd> at a promt.

While you type, the context area shows possible completions. Pressing <kbd>Return</kbd> answers the question with the currently selected completion. You can select differnt completions with <kbd>C-n</kbd> and <kbd>C-p</kbd>.

The following keyboard shortcuts are available:

| Key | Function | | ------------------------------- | ----------------------------------------------------------------------------- | | <kbd>C-c</kbd>, <kbd>C-d</kbd> | Quit the program without saving the current transaction | | <kbd>Esc</kbd> | Abort the current transaction or exit when at toplevel | | <kbd>Ret</kbd> | Accept the currently selected answer | | <kbd>Alt-Ret</kbd> | Accept the current answer verbatim from the text area, ignoring the selection | | <kbd>C-z</kbd> | Undo the last action | | <kbd>Tab</kbd> | Insert the currently selected answer into the text area | | <kbd>C-n</kbd>,<kbd>↓</kbd> | Select the next context item | | <kbd>C-p</kbd>,<kbd>↑</kbd> | Select the previous context item | | <kbd>F1</kbd>,<kbd>Alt-?</kbd> | Show help dialog |

Default Currency

To make entry easier it is recommended that you set a default commodity in your ledger file if you haven't already done so. That way when entering amounts, hledger-iadd will add the symbols for you. You can do this by adding a line like below to the top of your ledger file:

; sets the default commodity symbol and placement, thousands separator, and decimal symbol
D $1,000.00

Configuration File

hledger-iadd is optionally configurable through a configuration file in ${XDG_CONFIG_HOME}/hledger-iadd/config.conf. This file consists of simple

key = value

assignments on individual lines with whitespace or comments starting with # between them. The default config can be obtained by passing --dump-default-config to hledger-iadd.

The following options are currently available:

  • file: Path to the journal file.
  • date-format: The date format. See the documentation for --date-format for details.
  • completion-engine: Algorithm used to find completions for account names. Possible values are:
    • substrings: Every word in the search string has to occur somewhere in the account name
    • fuzzy: All letters from the search string have to appear in the name in the same order