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 dinero
can 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.
What | ledger | dinero |
---|---|---|
Programming language | C | Rust |
Feature set | a lot of options for each command | just some options for each command |
Transaction sorting for balance assertion | within file? | global |
Speed | extremely fast | not quite as fast (yet) |
End with newline | files must end with a blank line | no need to do that |
Regular expressions | assume ignore case | not always (it is well known when) |
Unicode | not 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 eitherdinero reg
orreg
Special commands
To exit the REPL type exit
or quit
.
reload
loads the journal again, which is useful if it has been changed externally.