Code Monkey home page Code Monkey logo

quickledger's Introduction


Entry creation utility for ledger.


  1. Download the archive
  2. Run chmod +x ql
  3. Move ql to /usr/local/bin/ or somewhere else in $PATH

Configuration File

ql keeps all data in $HOME/.qlrc


The ledger_file section under [file] is created automatically during the first run wizard.


Optional account section can be used to create a nickname for accounts. When specifying an account either via -a/--account or interactively, ql will attempt to match the entry with the nicknames in this section. If no match is found the literal input will be used. The default_account should be set to the nickname of the desired default account.

[merchant] & [category]

The optional merchant and category section can be used to create nicknames and default categories for merchants. When specifying the merchant with either The ~/.qlrc file can be manually edited to include [merchant] nicknames. Additionally, adding a [category] section will use the matching category for that merchant nickname.

Sample ~/.qlrc

$> cat ~/.qlrc  
ledger_file = /home/robotmachine/doc/Ledger.dat  
default_account = cheq 
cheq = Assets:MyCreditUnion:Chequing  
save = Assets:MyCreditUnion:Savings  
sm = Supermercado del Sol
gas = Joe's Fuel

sm = Expenses:Groceries  
gas = Expenses:Auto:Fuel  


ql requires an account, a merchant name, a category, and an amount at minimum. The date will always be set to today if no date option is selected. If any required information is missing from the command line, ql will enter interactive mode and prompt the user for the missing data.

Only one of -e/--expense or -c/--category is needed. The -e/--expense option will prepend Expenses: to the category name to save you typing. In interactive mode Expenses is prepended automatically as well.

Similarly, only one of -d/--date or -r/--rdate is needed. The -d/--date option takes a YYYY-MM-DD formatted date to use as the transaction date. -r/--rdate will use today's date and then offset the provided whole positive or negative integer. A positive value goes backward and a negative value goes forward. Ie. 1 is yesterday and -1 is tomorrow.

The -s/--split option will take the -t amount as the total (or prompt for one) and prompt through splitting the transaction between multiple categories (see example). ql does its best to make sure the transaction will balance and will add the total as a negative balance which will cause an error in Ledger if the amounts do not reconcile. Entering a 0 for any of the splits will use the remainder of the balance.

The -x/--not-cleared option will use a ! instead of * between the date and the merchant as per the Ledger documentation to mark the transaction as not cleared. Please see Ledger documentation on how this works. Note: You will need to manually edit your ledger.dat file to mark it as cleared. Re-running ql without the -x will not mark the transaction as cleared-- it will only add an additional entry for the same amount.


Everyone loves examples.

Interactive Mode

Running ql with no options will enter an interactive mode.

$> ql
Merchant name:
        Supermercardo del Sol
Amount: $40.21

Wrote entry to /home/robotmachine/doc/Ledger.dat:
2016-02-01 * Supermercado del Sol
        Expenses:Food:Groceries                 $40.21

Using Arguments

The same transaction as above, but using arguments instead of interactive. Both lines are equivalent using the long and short version of the arguments.

$> ql --merchant "Supermercado del Sol" --expense "Food:Groceries" --amount 40.21
$> ql -m "Supermercado del Sol" -e "Food:Groceries" -t 40.21
Wrote entry to /home/robotmachine/doc/Ledger.dat:
2016-02-01 * Supermercado del Sol
        Expenses:Food:Groceries                 $40.21

Using Nicknames

The above sample .qlrc file is used for the next example.

$> ql -m sm -t 40.21
Wrote entry to /home/robotmachine/doc/Ledger.dat:
2016-02-01 * Supermercado del Sol
        Expenses:Food:Groceries                 $40.21


Relative date:
(Current date in example is 2016-02-01)

$> ql -m sm -t 40.21 -r 1
Wrote entry to /home/robotmachine/doc/Ledger.dat:
2016-01-31 * Supermercado del Sol
        Expenses:Food:Groceries                 $40.21

Manual date:

$> ql -m "Bob's Groceries" -e "Food:Groceries" -t 40.21 -d 2016-01-15
Wrote entry to /home/robotmachine/doc/Ledger.dat:
2016-01-15 * Supermercado del Sol
        Expenses:Food:Groceries                 $40.21

Split Transaction

$> ql -m sm -t 100 --split
Total is $100.00  
Enter '0' for the remainder.  
Enter amount for split number 1:        $75  
Enter category for split number 1:      Expenses:Expenses:Groceries  
$25.00 remaining.  
Enter amount for split number 2:        $0  
Enter category for split number 2:      Expenses:Healthcare:Supplements  
Wrote entry to /home/robotmachine/doc/Ledger.dat:  
2016-02-01 * Supermercado del Sol
        Expenses:Healthcare:Supplements        $25.00    
        Expenses:Groceries                     $75.00  
        Assets:MyCreditUnion:Chequing          $-100.00  


Use -a/--account for where funds are coming from and -c/--category for where the funds are going to.
Note: Account nicknames from .qlrc do not work with -c/--category

$> ql -m Transfer -a save -c Assets:MyCreditUnion:Chequing -t 100
Wrote entry to /home/robotmachine/doc/Ledger.dat:  
2016-02-01 * Transfer
	Assets:MyCreditUnion:Chequing		$100.00

Other Examples

Credit Card Payment

$> ql -m "My Credit Union" -c "Liabilities:Credit:CU Visa" -t 100
Wrote entry to /home/robotmachine/doc/Ledger.dat:  
2016-02-01 * My Credit Union
        Liabilities:Credit:CU Visa                      $100.00

Income: Getting Paid

$> ql -m "My Employer" -a Income:Salary:Employer -c Assets:MyCreditUnion:Chequing -t 2140.23
Wrote entry to /home/robotmachine/doc/Ledger.dat:  
2016-02-01 * My Employer
	Assets:MyCreditUnion:Chequing			$2140.23

Built-In Help

$> ql -h
usage: ql [-h] [-f LEDGER_FILE] [-a ACCOUNT] [-m MERCHANT] [-c CATEGORY]
          [-e EXPENSE] [-t AMOUNT] [-r RDATE] [-d DATE] [-s] [-x] [--list]
          [--set-acct] [--set-merch] [--set-cat] [--config ALT_CONFIG] [-v]

QuickLedger: Entry creation utility for

optional arguments:
  -h, --help            show this help message and exit
                        Specify Ledger data file.
  -a ACCOUNT, --account ACCOUNT
                        Specify account.
  -m MERCHANT, --merchant MERCHANT
                        Set merchant.
  -c CATEGORY, --category CATEGORY
                        Set transaction category.
  -e EXPENSE, --expense EXPENSE
                        Set expense category. (Prepends 'Expenses:')
  -t AMOUNT, --amount AMOUNT
                        Set transaction amount.
  -r RDATE, --rdate RDATE
                        Set number of days ago transaction occurred. Positive
                        value for days in the past, negative value for days in
                        the future. Overrides --date.
  -d DATE, --date DATE  Set date of transaction. Format is YYYY-MM-DD.
  -s, --split           Split payment.
  -x, --not-cleared     Mark transaction as not-cleared/pending.
  --list                List settings in config file.
  --config ALT_CONFIG   Specify alternate config file.
  -v, --version         Print version.

quickledger's People


 avatar  avatar  avatar



quickledger's Issues


ql -m "Store Name"
ql --merchant "Store Name"

Uses the set merchant name instead of prompting for one interactively.


Option for accounts() and for merchants() instead of weird query thing.


Usage: ql -c "Liabilities:Salad"
Produces category as entered: Liabilities:Salad

See #13

Merchant Nicknames

Merchant nicknames in qlrc.

ql -n SD
Merchant: Sundance
Category: Expenses:Groceries

Setup Merchant Bug

If N is entered when prompted to setup a default category:

Would you like to enter a default category for this merchant? [y/N] n
Traceback (most recent call last):
  File "/home/brian/.bin/ql", line 364, in <module>
  File "/home/brian/.bin/ql", line 118, in main
  File "/home/brian/.bin/ql", line 265, in merchants
    if merchcat:
UnboundLocalError: local variable 'merchcat' referenced before assignment

Expense category.

Example: ql -e "Bills:Electricity"
Prefaces entered category with 'Expenses:'
Produces Expenses:Bills:Electricity in the ledger entry.

See #10 for just category.

Fix tools


Split payment

Usage: ql -s
Default = NA
Example = ql -s

Amount: $10
Category for split 1: Expenses:Food:Cheese
Amount: $2
Category for split 2: Expenses:Tips
Amount $0      ; Amount of zero stops prompt for splitting.
Prints as:  
2014-12-04 * Cheese Shoppe
               Expenses:Food:Cheese       $10
               Expenses:Tips                      $2
               Accounts:Bank:Chequing     -$12

if amount is not None:
The -t is the total and the split amount entered interactively go to the default or specified category if it exists. If a 0 is entered then the remainder is put in to a second category.
Example: ql -m SD -t 50 -s
print(Split #1: $) [user enters 35]
print(Split #2: $) [user enters 0]
print(Category for split #2: ) [User enters Expenses:Supplements]
Prints as:

2014-12-04 * Sundance
                Expenses:Groceries              $35
                Expenses:Supplements         $15
                Assets:Bank:Chequing           -$50


Usage: `ql -t "nn.nn"
Bypasses the amount prompt. Uses same input sanitising as created in #3.

Error when running ql with no .qlrc file.

~ [[email protected]]% ql

Looks like your default ledger file is

Use this file for ql? [y/n] y
Traceback (most recent call last):
File "/home/brian/.bin/ql", line 161, in
File "/home/brian/.bin/ql", line 40, in main
read_config(ledger_file=args.ledger_file, account=args.account, nick=args.nickname)
File "/home/brian/.bin/ql", line 77, in read_config
File "/home/brian/.bin/ql", line 116, in set_config
read_config(led_file, account)
TypeError: read_config() missing 1 required positional argument: 'nick'

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    ๐Ÿ–– Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. ๐Ÿ“Š๐Ÿ“ˆ๐ŸŽ‰

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google โค๏ธ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.