![](https://github.com/ebcrowder/rust-ledger/workflows/rust_ledger/badge.svg) [![Latest version](https://img.shields.io/crates/v/rust_ledger.svg)](https://crates.io/crates/rust_ledger) # rust_ledger command line accounting tool for Linux and macOS ### Summary - Spiritual port of [ledger](https://github.com/ledger/ledger) - Uses double-entry accounting paradigm - Supports all [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) currency formats - Uses `yaml` files as data store - Includes a tool to convert `csv` files to `yaml` format - Small feature set based on typical personal finance use cases ### Contributing - See `CODE_OF_CONDUCT.md` for guidelines - PRs, issues and feature requests are welcome and encouraged ### Install #### From Cargo `cargo install rust_ledger` #### Binaries for Linux and macOS We distribute binaries for the above platforms. See [releases](https://github.com/ebcrowder/rust_ledger/releases) for a complete list. #### Build from Source Alternatively, clone this repo and do the following: - If Rust is not installed on your machine, follow the instructions on how to do that here: https://www.rust-lang.org/tools/install - run `cargo build --release` to compile the binary - copy the `/target/release/rust_ledger` binary to `/usr/bin` or wherever your system maintains application binaries ## Test - `cargo test` ### Usage `rust_ledger --help` will provide a menu of all available commands and optional arguments. ```bash rust_ledger Eric Crowder USAGE: rust_ledger [SUBCOMMAND] FLAGS: -h, --help Prints help information -V, --version Prints version information SUBCOMMANDS: account account module balance balance module budget budget module csv csv module help Prints this message or the help of the given subcommand(s) register register module ``` ## rust_ledger `yaml` file format In lieu of the plain text ledger file format, this project uses a defined `yaml` schema. `yaml` has a relatively simple syntax and is able to represent useful data types, such as lists, quite easily. An example ledger `yaml` file can be found at `examples/example.yaml`. Further, parsing `yaml` via is trivial thanks to tools such as `serde`. This allowed me to skip writing a parser to support the `ledger` plain text file format and focus on implementing functionality. Additionally, modern formatting tools, such as [prettier](https://prettier.io) can be leveraged to maintain `yaml` files with ease as they are agnostic to the schema of the underlying file. The `ledger` tool has been rewritten in [many](https://github.com/ledger/ledger/wiki/Ports) programming languages. Almost all of these ports utilize the original `ledger` plain text format. Above all else, I view `rust_ledger` as an experiment in using a different ledger file format while maintaining the core feature set of the original tool. `rust_ledger` utilizes `yaml` files in the following format: ```yaml currency: USD accounts: - account: amount: transactions: - date: amount: description: account: offset_account: - date: description: transactions: - amount: account: - amount: account: ``` The ledger format schema is purposely lightweight. The only requirements are as follows: - the `currency` field should be a [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) currency code. - the `account` field should be expressed in the following format: `account_classification:account_name`. - the `amount` field should be a number. It can include up to two (2) decimal points. - the `date` field should be in the following format: `YYYY-MM-DD`. ## Transactions Transactions can be expressed in two different ways. One is a "simplified" format for transactions that only impact two accounts: ```yaml - date: 2020-01-01 amount: 200 offset_account: liability:cc_amex description: grocery store account: expense:expense_general ``` The sign (debit / credit) associated with the `offset_account` value is the opposite of the sign of the value contained in `amount` field. In the above example transaction, since `expense_general` was debited by 200, the `cc_amex` account will be credited by the same amount. Transactions that involve more than two accounts are expressed in the following manner: ```yaml - date: 2020-01-01 description: grocery store transactions: - amount: 20 account: expense:general - amount: 180 account: expense:grocery - amount: -200 account: liability:cc_amex ``` Transactions that only involve two accounts can also be expressed in the above format. ## Specifying the rust_ledger file path via environment variable Optionally, the ledger file path can be set via the environment variable `RUST_LEDGER_FILE` in lieu of specifying whenever the program is invoked. If `-f` is provided with a file path, the file provided will be used instead of any `RUST_LEDGER_FILE` set. ## API ### account Lists all accounts contained within the ledger file. ```bash rust_ledger-account account module USAGE: rust_ledger account [OPTIONS] --filename FLAGS: -h, --help Prints help information -V, --version Prints version information OPTIONS: -f, --filename location of ledger file ``` example output: ``` Account ---------------------------- asset:cash_checking asset:cash_savings liability:cc_amex equity:equity expense:grocery expense:general expense:mortgage income:general ``` ### balance Lists account balances to date. ```bash rust_ledger-balance balance module USAGE: rust_ledger balance [OPTIONS] --filename FLAGS: -h, --help Prints help information -V, --version Prints version information OPTIONS: -f, --filename location of ledger file ``` example output: ``` Account | Balance ---------------------+------------ asset | asset:cash_checking | $-400.00 asset:cash_savings | $1,000.00 liability | liability:cc_amex | $-455.00 equity | equity:equity | $-3,500.00 expense | expense:grocery | $635.00 expense:general | $1,020.00 expense:mortgage | $2,000.00 income | income:general | $-300.00 | check | 0 ``` ### register Lists general ledger transactions to date. The output can be filtered by any field via optional parameter. ```bash rust_ledger-register register module USAGE: rust_ledger register [OPTIONS] --filename FLAGS: -h, --help Prints help information -V, --version Prints version information OPTIONS: -f, --filename location of ledger file -g, --group group register output by value -o, --option