pledger 0.5.0

A small personal expense ledger
pledger-0.5.0 is not a library.


license Build Status

A small personal expense ledger.

All pledger does is track monthly expenses.


pledger is a single command-line program. You can install it using cargo:

cargo install pledger

Or by building it locally:

git clone && cd pledger
cargo build


pledger takes only one input: a directory where monthly ledgers are stored:

pledger expenses/

Alternatively, you can use PLEDGER_DIR to pass the directory:

PLEDGER_DIR=expenses/ pledger

Ledgers are stored as structured text files with the filename YYYY-MM. Read about the pledger format below.

For example, here's a listing for a directory with three months of expenses:

$ ls expenses/

pledger ignores files that don't match the YYYY-MM format.

By default, pledger reports expenses for the current month.

To run pledger on a previous date, use pledger -d <spec> or pledger -l:

# do a report on january 2017
pledger -d 2017-01 expenses/

# the month name or single number is also enough for the current year
# do a report on april, then march
pledger -d april expenses/
pledger -d 3 expenses

# -l/--last is a shortcut for last month's ledger
pledger -l expenses/

pledger can also generate a report for all records with pledger --all.

By default, pledger outputs a plain text report. You can use the --json flag to output JSON instead, for consumption by other tools:

pledger --json expenses/ > monthly.json

Ledger format

pledger's ledgers are plain text files, with one entry per line. Debits begin with D, credits with C, and the rest of the format is mostly self-explanatory:

C 130.00 #bonus
D 8.00 burger and fries #weekday #lunch
D 27.00 saturday drinks #weekend #alcohol
D 20,000.12 new car #essential

Everything after the currency amount is the comment. The comment can include tags, which begin with # and can be alphanumeric + symbolic. pledger uses your tags to provide expense summaries; duplicate tags in a comment are removed.

Empty lines or lines that begin with # are ignored.