Build status codecov crates.io Crates.io dependency status

Dinero (spanish for money) is a command line tool that can deal with ledger files, as defined by John Wiegley's wonderful ledger-cli.

Quickstart

Install

If Rust and cargo are available in your system, the easiest way to get dinero-rs is by installing the crate:

cargo install dinero-rs
  • Installation for Windows
  • Installation for Mac
  • Installation for Linux

First steps

Dinero uses double entry accounting. Store your journal files in ledger files. The main item is a transaction, which in its basic form looks something like this:

; This is a comment
; A date followed by a description identifies the beginning of a transaction
2021-02-01 Buy fruit
     Expenses:Groceries          7.92 EUR
     Assets:Checking account             ; you can leave this blank, dinero balances the transactions for you

After that, you can issue all the commands you want and combine them with options to have complete control over your finances!

The most basic ones are:

# Get a balance report: How much is there in every account 
dinero bal -f myledger.ledger

# Get a list of transactions
dinero reg -f myledger.ledger

Features

Currently supported are:

  • Balance reports
  • Register reports
  • Account and payees reports
  • Automated transactions
  • Multicurrency transactions
  • Currency conversion

Report filtering by account name and by date.

Motivation

I use ledger-cli extensively for my personal finances. My goal is to be able to run all the commands I use the most with my own tool while at the same time learning Rust.

Run dinero --help for a list of available commands and options.

If you use this software and want to say thanks, feel free to buy me a coffee.

The journal file(s)

Work in progress

Dinero derives its reports from a journal file (or files). The most important feature of this file format is its readibility. Unlike other computer-friendly formats such as comma separated values or a binary database, journal files actually make sense to a human.

Dinero follows the principles of double entry accounting, where the main information is the transaction.

A transaction contains two or more postings, which are actual movements in an account, which is another important concept. In bookkeeping, money always comes from and goes to an account.

Developers

The full syntax accepted by dinerocan be found in the grammar specification. It is a formal grammar.

Differences with ledger-cli

Although dinero is completely inspired by ledger-cli and implements a subset of its features, it has been written form scratch, it is not a port.

Some behaviors are intentionally different. Other things are just bugs: if you find one, feel free to add an issue in the development repository.

dinero is developed in Rust, while ledger is developed in C. This is completely transparent to the end user, it does at least theoretically provide some advantages for developers, with Rust being a newer language with the same speed as C but more memory safety. Again, this at least theory

The next table presents a summary of differences, with the most important ones being commented later.

Whatledgerdinero
Programming languageCRust
Feature seta lot of options for each commandjust some options for each command
Transaction sorting for balance assertionwithin file?global
Speedextremely fastnot quite as fast (yet)
End with newlinefiles must end with a blank lineno need to do that
Regular expressionsassume ignore casenot always (it is well known when)
Unicodenot everywhere€ is a valid currency

Balance assertions

Balance assertions have the same syntax in both languages, but the way they are handled is different.

In ledger it is very difficult (for me) to add balance assertions to all the transactions, in particular when you have several ledger files linked together. The balance assertions are processed more or less as they appear in the files, which depends in the order you read the files with the include directive.

In dinero every transaction is read, then they are sorted by date (without altering the original order in ties) and finally tha balance is checked.

The practical consequence for me (Claudio) in particular is that rather than doing this:

include past/201701.ledger
include past/201702.ledger
; ...
include past/202103.ledger

I can do this instead:

include past/*.ledger

This results in a much shorter file, easier on the eyes (I like my master.ledger file to be complete yet simple). ledger does not guarantee the order in which the files are read and that affects balance assertions. dinero doesn't guarantee it either, but the extra ordering step means it doesn't matter (though arguably it makes it somewhat slower)

The register report

Work in progress

The register report shows a list of postings. It can be invoked with dinero register or the shorter dinero reg

Options

--collapse

The collapse only shows one posting per account and transaction. For example:

2021-09-01 * A lot of fees
    Expenses:Travel    200 EUR
    Expenses:Fees        1 EUR
    Expenses:Fees        3 EUR
    Assets:Checking Account

dinero reg --collapse will print out:

2021-09-01  A lot of fees    Expenses:Travel              200 EUR      200 EUR
                             Expenses:Fees                  4 EUR      204 EUR
                             Assets:Checking Account     -204 EUR        0 EUR

REPL mode

Since 0.29.0 dinero-rs comes with a REPL mode (read-eval-print-loop) or interactive mode:

```dinero -f myjournal.ledger````

Once inside the REPL mode, the ledger is parsed and cached so that any subsequent operations are faster than their regular CLI counterparts.

Working inside the interactive mode

The commands behave just like in the normal mode but:

  • they are faster
  • the dinero executable is elided, you can write either dinero reg or reg

Special commands

To exit the REPL type exit or quit.

reload loads the journal again, which is useful if it has been changed externally.