Man Linux: Main Page and Category List

NAME

       ledger - command-line accounting

SYNOPSIS

       ledger [options] command [acct-regex]... [-- payee-regex...]

DESCRIPTION

       Ledger  is  a command-line accounting tool with the moxie to exist.  It
       provides no bells or whistles, and returns the user to the days  before
       user interfaces were even a twinkling in their father’s CRT.

NOTE

       This  man  page  is a summary of the command-line usage of ledger along
       with a short  example  of  a  Ledger  data  file.   For  more  complete
       documentation  see  the  Ledger  Reference Manual, (via the info ledger
       command or otherwise).

COMMANDS

       All commands require a Ledger data file which  can  be  specified  with
       -f filename or via the LEDGER_FILE environment variable.

       The  balance and register commands provide the primary functionality of
       Ledger and are used most frequently:

           bal, balance [REGEXP]...
               Reports the current balance of all matching  accounts.   If  an
               account   contains   multiple   types   of   commodities,  each
               commodity’s total is reported separately.

           reg, register [REGEXP]...
               Displays  all  the  transactions  occurring  in  the   matching
               accounts, line by line.  The output from register is very close
               to what a typical checkbook, or  single-account  ledger,  would
               look like.  It also shows a running balance.  The final running
               balance of any register  should  always  be  the  same  as  the
               current balance of that account.

       Several  commands are effectively variants of register.  These commands
       accept the same options and display the same transactions  as  register
       and differ only in the format of the output:

           print [REGEXP]...
               Displays transactions in a format that can be parsed by Ledger.
               They will be properly formatted and output in the most economic
               form  possible.   The print command can be a handy way to clean
               up a Ledger file whose formatting has gotten out of hand.

           xml [REGEXP]...
               Displays transactions in an XML format that can  then  be  read
               and  processed  by  external tools.  Use the --totals option to
               include the running total with each transaction.

           emacs [REGEXP]...
               Displays transactions in a format that can be read directly  by
               Emacs Lisp.

       The remaining commands are each useful in particular circumstances:

           equity [REGEXP]...
               Prints  out  account  balances  as  if they were entries.  This
               makes it easy to establish the starting balances for  accounts,
               (such  as  when  beginning  a  new  Ledger file to then archive
               previous years).

           prices [REGEXP]...
               Displays the price history for matching  commodities.   The  -A
               option  is  useful  with  this  report  to  display the average
               running price, or -D to show each price’s deviation  from  that
               average.

           pricedb [REGEXP]...
               Produces  the  same  information as prices but in a format that
               can be parsed by Ledger.

           entry DATE PAYEE AMOUNT
               Output a derived entry, based on the arguments and  an  account
               matching  PAYEE in the transacation history. If Ledger does not
               succeed in generating a new entry, an error is printed and  the
               exit code is set to 1.

OPTIONS


   Basic options
       -h, --help
              Print  a  summary  of the basic options and commands.  This help
              screen is also printed if ledger is run without a command.

       -H, --full-help
              Print a help message including all command-line options.

       -v, --version
              Prints the current version of Ledger and exits.  This is  useful
              for sending bug reports, to let the author know which version of
              Ledger you are using.

       -f, --file FILE
              Reads FILE as a  Ledger  file.  This  option  may  be  specified
              multiple times.  FILE may also be a list of file names separated
              by colons.  Typically, the environment variable  LEDGER_FILE  is
              set rather than using this command-line option.

       -o, --output FILE
              Redirects  output  from  any  command  to FILE.  By default, all
              output goes to standard output.

       -i, --init-file FILE
              Causes FILE to be read by ledger before any other  Ledger  file.
              This  file  may not contain any transactions, but it may contain
              option settings.  To specify options in the init file,  use  the
              same  syntax  as  the  command-line.   Option  settings  on  the
              command-line or in the environment always take  precedence  over
              settings   in   the   init  file.   The  default  init  file  is
              ~/.ledgerrc.

       --cache FILE
              Identifies FILE as the default  binary  cache  file.   That  is,
              whenever  a command is finished a binary copy of the input files
              will be written to the specified cache, to speed up the  loading
              time  of  subsequent  queries.   This filename can also be given
              using the environment variable LEDGER_CACHE or  by  putting  the
              option into your init file.

       --no-cache
              Causes Ledger to always ignore the binary cache.

       -a, --account NAME
              Specifies  the  default  account which QIF file transactions are
              assumed to relate to.

   Report filtering options
       These options change which transactions affect the outcome of a report,
       in ways other than just using regular expressions:

       -c,  --current
              Displays only entries occurring on or before the current date.

       -b, --begin DATE
              Constrains the report to entries on or after DATE.  Only entries
              after that date will be calculated, which means that the running
              total  in  the balance report will always start at zero with the
              first matching  entry.   Note:  This  is  different  from  using
              --display to constrain what is displayed.

       -e, --end DATE
              Constrains  the  report so that entries on or after DATE are not
              considered.  The ending date is inclusive.

       -p, --period STR
              Sets the reporting  period  to  STR.   This  will  subtotal  all
              matching  entries  within each period separately, making it easy
              to see weekly, monthly, quarterly, etc. transaction  totals.   A
              period  string  can  even  specify  the beginning and end of the
              report range, using simple terms like last june or  next  month.
              For  more  using  period expressions, see the Period Expressions
              section of the Ledger Reference Manual.

       --period-sort EXPR
              Sorts the transactions within each reporting  period  using  the
              value expression EXPR.  This is most often useful when reporting
              monthly expenses.  For example,  to  view  the  highest  expense
              categories at the top of each month use:

              ledger -M --period-sort -At reg ^Expenses

       -C, --cleared
              Displays  only  transactions whose entry has been marked cleared
              (by placing an asterix to the right of the date).

       -U, --uncleared
              Displays only transactions  whose  entry  has  not  been  marked
              cleared (i.e., if there is no asterix to the right of the date).

       -R, --real
              Displays  only  real  transactions,  not  virtual.   A   virtual
              transaction  is  indicated  by surrounding the account name with
              parentheses or brackets, (see the Ledger  Reference  Manual  for
              more on using virtual transactions).

       -L, --actual
              Displays  only actual transactions, and not those created due to
              automated transactions.

       -r, --related
              Displays transactions that are related to whichever transactions
              would  otherwise  have  matched  the filtering criteria.  In the
              register report, this shows where money went to, or the  account
              it  came from.  In the balance report, it shows all the accounts
              affected by entries having a related transaction.

       --budget
              Display budgeted transactions only.

       --add-budget
              Shows both budgeted and unbudgeted transactions.  This option is
              useful  for  displaying  how close your actual transactions meet
              your budget.

       --unbudgeted
              Show only unbudgeted transactions.

       --forecast EXPR
              Projects your budget into the  future,  (while  EXPR  is  true),
              showing how it will affect future balances.

       -l, --limit EXPR
              Calculate  only  transactions  matching  EXPR.   (See  the Value
              Expressions section of Ledger Reference Manual for more  details
              on possible values of EXPR for this and other options.)

       -t, --amount EXPR
              Sets  the value expression used to calculate the value column in
              the register report, the account totals in the  balance  report,
              and the values printed in the equity report.

       -T, --total EXPR
              Sets  the  value  expression  used  for the totals column in the
              register and balance reports.  EXPR to calculate  the  displayed
              total.

   Output customization options
       -n, --collapse
              Causes  entries  in a register report with multiple transactions
              to be collapsed into a single, subtotaled entry.

       -s, --subtotal
              Causes all entries in a register report to be collapsed  into  a
              single, subtotaled entry.

       -P, --by-payee
              Reports subtotals by payee.

       -x, --comm-as-payee
              Changes  the payee of every transaction to be the commodity used
              in that transaction.  This can  be  useful  when  combined  with
              other options, such as -s, --sort.

       -E, --empty
              Includes even empty accounts in the balance report.

       -W, --weekly
              reports  transaction  totals  by  the  week.  The week begins on
              whichever day of the  week  begins  the  month  containing  that
              transaction.  To set a specific begin date, use a period string,
              such as --period weekly from DATE.

       -M, --monthly
              Reports transaction totals by month.

       -Y, --yearly
              Reports transaction totals by year.

       --dow  Reports transactions totals for each day of the week.   This  is
              an easy way to see if weekend spending is more than on weekdays.

       -S, --sort EXPR
              Sorts a report by comparing  the  values  determined  using  the
              value expression EXPR.  For example, using --sort date will sort
              by date, (useful if included files cover different date ranges),
              and  --sort -UT in the balance report will sort account balances
              from greatest to least, using the absolute value of  the  total.
              For  more  on  how  to  use  value  expressions,  see  the Value
              Expressions section of the Ledger Reference Manual.

       -w, --wide
              Causes the default register report to assume 132 columns instead
              of 80.

       --head COUNT
              Show  only  the  first  COUNT  entries.  If a negative amount is
              given, it will invert the meaning of the flag  (instead  of  the
              first  five  entries  being printed, for example, it would print
              all but the first five).

       --tail COUNT
              Show only the last COUNT  entries.   If  a  negative  amount  is
              given,  it  will  invert the meaning of the flag (instead of the
              last five entries being printed, for example, it would print all
              but the last five).

       --pager PAGER
              Tells   ledger   to   pass   its   output  to  the  given  pager
              program---very useful when the output is especially long.   This
              behavior  can  be  made  the default by setting the LEDGER_PAGER
              environment variable.

       -A, --average
              Reports the average transaction value.

       -D, --deviation
              Reports each transaction’s deviation from the  average.   It  is
              only meaningful in the register and prices reports.

       -%, --percentage
              Shows  account subtotals in the balance report as percentages of
              the parent account.

       --totals
              Include running total information in the xml report.

       -j, --amount-data
              Changes the register report so that it outputs nothing  but  the
              date  and  the value column, and the latter without commodities.
              This is only meaningful if the report uses a  single  commodity.
              This  data  can  then be fed to other programs, which could plot
              the date, analyze it, etc.

       -J, --total-data
              Changes the register report so that it outputs nothing  but  the
              date and totals column, without commodities.

       -d, --display EXPR
              Limits which transactions or accounts or actually displayed in a
              report.  They might still be calculated,  and  be  part  of  the
              running  total  of a register report, for example, but they will
              not be displayed.

       -y, --date-format STR
              Changes the basic date format used by reports.  The default uses
              a date like 2004/08/01, which represents the default date format
              of %Y/%m/%d.  To change the way dates are  printed  in  general,
              the  easiest  way  is  to put --date-format FORMAT in the Ledger
              initialization file ~/.ledgerrc (or  the  file  referred  to  by
              LEDGER_INIT).

       -F, --format STR
              Sets the reporting format for whatever report ledger is about to
              make.  See the Format Strings section of  the  Ledger  Reference
              Manual for details.

   Commodity price options
       These options affect how commodity values are displayed:

       --price-db FILE
              Sets  the  file  that is used for recording downloaded commodity
              prices.  It is always read on startup, to  determine  historical
              prices.  The default file is ~/.pricedb.

       -L, --price-exp MINS
              Sets  the  expected freshness of price quotes, in minutes.  That
              is, if the last known quote for any commodity is older than this
              value---and if --download is being used---then the internet will
              be consulted again for a newer price.  Otherwise, the old  price
              is  still considered to be fresh enough.  (Default value is 1440
              minutes.)

       -Q, --download
              Causes quotes to be  automatically  downloaded,  as  needed,  by
              running  a  script  named  getquote and expecting that script to
              return a value understood by ledger.  A sample implementation of
              a  getquote  script,  implemented  in  Perl,  is provided in the
              distribution.  Downloaded quote price are then appended  to  the
              price database, usually specified using the environment variable
              LEDGER_PRICE_DB.

   Commodity reporting options
       There are several different ways that ledger can report the  totals  it
       displays.   The  most  flexible  way  to  adjust them is by using value
       expressions and the -t and -T options.  However, there are also several
       standard reports, which will satisfy most users’ basic reporting needs:

       -O, --quantity
              Reports commodity totals (this is the default).

       -B, --basis
              Reports the cost basis for all transactions.

       -V, --market
              Reports the last known market value for all commodities.

       -g, --performance
              Reports the net gain/loss for each  transaction  in  a  register
              report.

       -G, --gain
              Reports the net gain/loss for all commodities in the report that
              have a price history.

ENVIRONMENT

       Every option to ledger may be set using an environment variable.  If an
       option  has  a  long  name  such  as  --this-option  then  setting  the
       environment variable LEDGER_THIS_OPTION will have the  same  effect  as
       specifying  that  option  on the command-line.  Options on the command-
       line  always  take  precedence  over  environment  variable   settings,
       however.   Note  that you may also permanently specify option values by
       placing option settings in the file ~/.ledgerrc  by  default,  (or  the
       file specified by the LEDGER_INIT_FILE environment variable).

       Of  special  note  is the LEDGER_FILE environment variable which almost
       all users of Ledger will find convenient:

       LEDGER_FILE
              Set to a file, (or a colon-separated list of files), to be  read
              by  the  ledger  command.   This  avoids the requirement to pass
              --file FILE to every invocation of ledger.

EXAMPLE

       Here  is  sample  data  file   (ledger.dat   from   the   distribution)
       demonstrating  most  of  the  features  of the ledger data-file format.
       These  include  comments  (;),  automated  transactions  (=),   virtual
       transactions  (  (account-name)  ), periodic (budget) transactions (~),
       cleared transactions (*), commodity transactions (SYMBOL @), and  check
       numbers ( (NUMBER) ).

           ; Sample file ledger.dat

           ; An automated transaction to a virtual account
           = /^Expenses:Books/
             (Liabilities:Taxes)             -0.10

           ; A periodic (budget) transaction
           ~ Monthly
             Assets:Bank:Checking          $500.00
             Income:Salary

           ; A cleared transaction
           2004/05/01 * Checking balance
             Assets:Bank:Checking        $1,000.00
             Equity:Opening Balances

           ; A transaction involving multiple commodities
           2004/05/01 * Investment balance
             Assets:Brokerage              50 AAPL @ $30.00
             Equity:Opening Balances

           2004/05/14 * Pay day
             Assets:Bank:Checking          $500.00
             Income:Salary

           2004/05/27 Book Store
             Expenses:Books                 $20.00
             Liabilities:MasterCard

           ; A transaction with a check number
           2004/05/27 (100) Credit card company
             Liabilities:MasterCard         $20.00
             Assets:Bank:Checking

SEE ALSO

       The  Ledger  Reference  Manual  available via info ledger if ledger and
       info are properly installed.

       The ledger homepage: http://wiki.github.com/jwiegley/ledger