1LEDGER(1) General Commands Manual LEDGER(1)
2
6 ledger - command-line accounting
7
9 ledger [options] command [acct-regex]... [-- payee-regex...]
10
12 Ledger is a command-line accounting tool with the moxie to exist. It
13 provides no bells or whistles, and returns the user to the days before
14 user interfaces were even a twinkling in their father's CRT.
15
17 This man page is a summary of the command-line usage of ledger along
18 with a short example of a Ledger data file. For more complete documen‐
19 tation see the Ledger Reference Manual, (via the info ledger command or
20 otherwise).
21
23 All commands require a Ledger data file which can be specified with
24 -f filename or via the LEDGER_FILE environment variable.
25 The balance and register commands provide the primary functionality of
27 Ledger and are used most frequently:
28 bal, balance [REGEXP]...
30 Reports the current balance of all matching accounts. If an
31 account contains multiple types of commodities, each commod‐
32 ity's total is reported separately.
33 reg, register [REGEXP]...
35 Displays all the transactions occurring in the matching
36 accounts, line by line. The output from register is very close
37 to what a typical checkbook, or single-account ledger, would
38 look like. It also shows a running balance. The final running
39 balance of any register should always be the same as the cur‐
40 rent balance of that account.
41 Several commands are effectively variants of register. These commands
43 accept the same options and display the same transactions as register
44 and differ only in the format of the output:
45 print [REGEXP]...
47 Displays transactions in a format that can be parsed by Ledger.
48 They will be properly formatted and output in the most economic
49 form possible. The print command can be a handy way to clean
50 up a Ledger file whose formatting has gotten out of hand.
51 xml [REGEXP]...
53 Displays transactions in an XML format that can then be read
54 and processed by external tools. Use the --totals option to
55 include the running total with each transaction.
56 emacs [REGEXP]...
58 Displays transactions in a format that can be read directly by
59 Emacs Lisp.
60 The remaining commands are each useful in particular circumstances:
62 equity [REGEXP]...
64 Prints out account balances as if they were entries. This
65 makes it easy to establish the starting balances for accounts,
66 (such as when beginning a new Ledger file to then archive pre‐
67 vious years).
68 prices [REGEXP]...
70 Displays the price history for matching commodities. The -A
71 option is useful with this report to display the average run‐
72 ning price, or -D to show each price's deviation from that
73 average.
74 pricedb [REGEXP]...
76 Produces the same information as prices but in a format that
77 can be parsed by Ledger.
78 entry DATE PAYEE AMOUNT
80 Output a derived entry, based on the arguments and an account
81 matching PAYEE in the transacation history. If Ledger does not
82 succeed in generating a new entry, an error is printed and the
83 exit code is set to 1.
84
86 Basic options
89 -h, --help
90 Print a summary of the basic options and commands. This help
91 screen is also printed if ledger is run without a command.
92 -H, --full-help
94 Print a help message including all command-line options.
95 -v, --version
97 Prints the current version of Ledger and exits. This is useful
98 for sending bug reports, to let the author know which version of
99 Ledger you are using.
100 -f, --file FILE
102 Reads FILE as a Ledger file. This option may be specified multi‐
103 ple times. FILE may also be a list of file names separated by
104 colons. Typically, the environment variable LEDGER_FILE is set
105 rather than using this command-line option.
106 -o, --output FILE
108 Redirects output from any command to FILE. By default, all out‐
109 put goes to standard output.
110 -i, --init-file FILE
112 Causes FILE to be read by ledger before any other Ledger file.
113 This file may not contain any transactions, but it may contain
114 option settings. To specify options in the init file, use the
115 same syntax as the command-line. Option settings on the com‐
116 mand-line or in the environment always take precedence over set‐
117 tings in the init file. The default init file is ~/.ledgerrc.
118 --cache FILE
120 Identifies FILE as the default binary cache file. That is,
121 whenever a command is finished a binary copy of the input files
122 will be written to the specified cache, to speed up the loading
123 time of subsequent queries. This filename can also be given
124 using the environment variable LEDGER_CACHE or by putting the
125 option into your init file.
126 --no-cache
128 Causes Ledger to always ignore the binary cache.
129 -a, --account NAME
131 Specifies the default account which QIF file transactions are
132 assumed to relate to.
133 Report filtering options
135 These options change which transactions affect the outcome of a report,
136 in ways other than just using regular expressions:
137 -c, --current
139 Displays only entries occurring on or before the current date.
140 -b, --begin DATE
142 Constrains the report to entries on or after DATE. Only entries
143 after that date will be calculated, which means that the running
144 total in the balance report will always start at zero with the
145 first matching entry. Note: This is different from using --dis‐
146 play to constrain what is displayed.
147 -e, --end DATE
149 Constrains the report so that entries on or after DATE are not
150 considered. The ending date is inclusive.
151 -p, --period STR
153 Sets the reporting period to STR. This will subtotal all match‐
154 ing entries within each period separately, making it easy to see
155 weekly, monthly, quarterly, etc. transaction totals. A period
156 string can even specify the beginning and end of the report
157 range, using simple terms like last june or next month. For
158 more using period expressions, see the Period Expressions sec‐
159 tion of the Ledger Reference Manual.
160 --period-sort EXPR
162 Sorts the transactions within each reporting period using the
163 value expression EXPR. This is most often useful when reporting
164 monthly expenses. For example, to view the highest expense cat‐
165 egories at the top of each month use:
166 ledger -M --period-sort -At reg ^Expenses
168 -C, --cleared
170 Displays only transactions whose entry has been marked cleared
171 (by placing an asterix to the right of the date).
172 -U, --uncleared
174 Displays only transactions whose entry has not been marked
175 cleared (i.e., if there is no asterix to the right of the date).
176 -R, --real
178 Displays only real transactions, not virtual. A virtual trans‐
179 action is indicated by surrounding the account name with paren‐
180 theses or brackets, (see the Ledger Reference Manual for more on
181 using virtual transactions).
182 -L, --actual
184 Displays only actual transactions, and not those created due to
185 automated transactions.
186 -r, --related
188 Displays transactions that are related to whichever transactions
189 would otherwise have matched the filtering criteria. In the
190 register report, this shows where money went to, or the account
191 it came from. In the balance report, it shows all the accounts
192 affected by entries having a related transaction.
193 --budget
195 Display budgeted transactions only.
196 --add-budget
198 Shows both budgeted and unbudgeted transactions. This option is
199 useful for displaying how close your actual transactions meet
200 your budget.
201 --unbudgeted
203 Show only unbudgeted transactions.
204 --forecast EXPR
206 Projects your budget into the future, (while EXPR is true),
207 showing how it will affect future balances.
208 -l, --limit EXPR
210 Calculate only transactions matching EXPR. (See the Value
211 Expressions section of Ledger Reference Manual for more details
212 on possible values of EXPR for this and other options.)
213 -t, --amount EXPR
215 Sets the value expression used to calculate the value column in
216 the register report, the account totals in the balance report,
217 and the values printed in the equity report.
218 -T, --total EXPR
220 Sets the value expression used for the totals column in the reg‐
221 ister and balance reports. EXPR to calculate the displayed
222 total.
223 Output customization options
225 -n, --collapse
226 Causes entries in a register report with multiple transactions
227 to be collapsed into a single, subtotaled entry.
228 -s, --subtotal
230 Causes all entries in a register report to be collapsed into a
231 single, subtotaled entry.
232 -P, --by-payee
234 Reports subtotals by payee.
235 -x, --comm-as-payee
237 Changes the payee of every transaction to be the commodity used
238 in that transaction. This can be useful when combined with
239 other options, such as -s, --sort.
240 -E, --empty
242 Includes even empty accounts in the balance report.
243 -W, --weekly
245 reports transaction totals by the week. The week begins on
246 whichever day of the week begins the month containing that
247 transaction. To set a specific begin date, use a period string,
248 such as --period weekly from DATE.
249 -M, --monthly
251 Reports transaction totals by month.
252 -Y, --yearly
254 Reports transaction totals by year.
255 --dow Reports transactions totals for each day of the week. This is
257 an easy way to see if weekend spending is more than on weekdays.
258 -S, --sort EXPR
260 Sorts a report by comparing the values determined using the
261 value expression EXPR. For example, using --sort date will sort
262 by date, (useful if included files cover different date ranges),
263 and --sort -UT in the balance report will sort account balances
264 from greatest to least, using the absolute value of the total.
265 For more on how to use value expressions, see the Value Expres‐
266 sions section of the Ledger Reference Manual.
267 -w, --wide
269 Causes the default register report to assume 132 columns instead
270 of 80.
271 --head COUNT
273 Show only the first COUNT entries. If a negative amount is
274 given, it will invert the meaning of the flag (instead of the
275 first five entries being printed, for example, it would print
276 all but the first five).
277 --tail COUNT
279 Show only the last COUNT entries. If a negative amount is
280 given, it will invert the meaning of the flag (instead of the
281 last five entries being printed, for example, it would print all
282 but the last five).
283 --pager PAGER
285 Tells ledger to pass its output to the given pager pro‐
286 gram---very useful when the output is especially long. This
287 behavior can be made the default by setting the LEDGER_PAGER
288 environment variable.
289 -A, --average
291 Reports the average transaction value.
292 -D, --deviation
294 Reports each transaction's deviation from the average. It is
295 only meaningful in the register and prices reports.
296 -%, --percentage
298 Shows account subtotals in the balance report as percentages of
299 the parent account.
300 --totals
302 Include running total information in the xml report.
303 -j, --amount-data
305 Changes the register report so that it outputs nothing but the
306 date and the value column, and the latter without commodities.
307 This is only meaningful if the report uses a single commodity.
308 This data can then be fed to other programs, which could plot
309 the date, analyze it, etc.
310 -J, --total-data
312 Changes the register report so that it outputs nothing but the
313 date and totals column, without commodities.
314 -d, --display EXPR
316 Limits which transactions or accounts or actually displayed in a
317 report. They might still be calculated, and be part of the run‐
318 ning total of a register report, for example, but they will not
319 be displayed.
320 -y, --date-format STR
322 Changes the basic date format used by reports. The default uses
323 a date like 2004/08/01, which represents the default date format
324 of %Y/%m/%d. To change the way dates are printed in general,
325 the easiest way is to put --date-format FORMAT in the Ledger
326 initialization file ~/.ledgerrc (or the file referred to by
327 LEDGER_INIT).
328 -F, --format STR
330 Sets the reporting format for whatever report ledger is about to
331 make. See the Format Strings section of the Ledger Reference
332 Manual for details.
333 Commodity price options
335 These options affect how commodity values are displayed:
336 --price-db FILE
338 Sets the file that is used for recording downloaded commodity
339 prices. It is always read on startup, to determine historical
340 prices. The default file is ~/.pricedb.
341 -L, --price-exp MINS
343 Sets the expected freshness of price quotes, in minutes. That
344 is, if the last known quote for any commodity is older than this
345 value---and if --download is being used---then the internet will
346 be consulted again for a newer price. Otherwise, the old price
347 is still considered to be fresh enough. (Default value is 1440
348 minutes.)
349 -Q, --download
351 Causes quotes to be automatically downloaded, as needed, by run‐
352 ning a script named getquote and expecting that script to return
353 a value understood by ledger. A sample implementation of a
354 getquote script, implemented in Perl, is provided in the distri‐
355 bution. Downloaded quote price are then appended to the price
356 database, usually specified using the environment variable
357 LEDGER_PRICE_DB.
358 Commodity reporting options
360 There are several different ways that ledger can report the totals it
361 displays. The most flexible way to adjust them is by using value
362 expressions and the -t and -T options. However, there are also several
363 standard reports, which will satisfy most users' basic reporting needs:
364 -O, --quantity
366 Reports commodity totals (this is the default).
367 -B, --basis
369 Reports the cost basis for all transactions.
370 -V, --market
372 Reports the last known market value for all commodities.
373 -g, --performance
375 Reports the net gain/loss for each transaction in a register
376 report.
377 -G, --gain
379 Reports the net gain/loss for all commodities in the report that
380 have a price history.
381
383 Every option to ledger may be set using an environment variable. If an
384 option has a long name such as --this-option then setting the environ‐
385 ment variable LEDGER_THIS_OPTION will have the same effect as specify‐
386 ing that option on the command-line. Options on the command-line
387 always take precedence over environment variable settings, however.
388 Note that you may also permanently specify option values by placing
389 option settings in the file ~/.ledgerrc by default, (or the file speci‐
390 fied by the LEDGER_INIT_FILE environment variable).
391 Of special note is the LEDGER_FILE environment variable which almost
393 all users of Ledger will find convenient:
394 LEDGER_FILE
396 Set to a file, (or a colon-separated list of files), to be read
397 by the ledger command. This avoids the requirement to pass
398 --file FILE to every invocation of ledger.
399
401 Here is sample data file (ledger.dat from the distribution) demonstrat‐
402 ing most of the features of the ledger data-file format. These include
403 comments (;), automated transactions (=), virtual transactions (
404 (account-name) ), periodic (budget) transactions (~), cleared transac‐
405 tions (*), commodity transactions (SYMBOL @), and check numbers ( (NUM‐
406 BER) ).
407 ; Sample file ledger.dat
409 ; An automated transaction to a virtual account
411 = /^Expenses:Books/
412 (Liabilities:Taxes) -0.10
413 ; A periodic (budget) transaction
415 ~ Monthly
416 Assets:Bank:Checking $500.00
417 Income:Salary
418 ; A cleared transaction
420 2004/05/01 * Checking balance
421 Assets:Bank:Checking $1,000.00
422 Equity:Opening Balances
423 ; A transaction involving multiple commodities
425 2004/05/01 * Investment balance
426 Assets:Brokerage 50 AAPL @ $30.00
427 Equity:Opening Balances
428 2004/05/14 * Pay day
430 Assets:Bank:Checking $500.00
431 Income:Salary
432 2004/05/27 Book Store
434 Expenses:Books $20.00
435 Liabilities:MasterCard
436 ; A transaction with a check number
438 2004/05/27 (100) Credit card company
439 Liabilities:MasterCard $20.00
440 Assets:Bank:Checking
441
444 The Ledger Reference Manual available via info ledger if ledger and
445 info are properly installed.
446 The ledger homepage: http://wiki.github.com/jwiegley/ledger
448Ledger 2.6.2 2009-08-06 LEDGER(1)