ledger.md

   1 ---
   2 title: Ledger CLI
   3 category: Ledger
   4 layout: 2017/sheet
   5 updated: 2020-05-23
   6 weight: -5
   7 ---
   8
   9 ### Basic usage
  10
  11 ```bash
  12 $ ledger bal
  13 $ ledger reg
  14 ```
  15
  16 ```bash
  17 $ ledger reg grocery  # show entries for 'grocery'
  18 $ ledger bal assets   # check if i'm broke
  19 ```
  20
  21 ```bash
  22   -b 01/01   # --begin
  23   -e 01/31   # --end
  24   -S date    # --sort
  25   -S amount
  26 ```
  27
  28 ### Examples
  29
  30 ```bash
  31 # any/all matches
  32   ledger bal Rent Transportation  # any
  33   ledger bal Income and Job       # all
  34   ledger bal Expenses and not (Drinks or Food)
  35 ```
  36
  37 ```bash
  38 # what did I spend on most? (--sorted)
  39   ledger reg Expenses -S amount
  40 ```
  41
  42 ```bash
  43 # how much did I have at this date? (--end)
  44   ledger bal -e 01/15 ^Assets ^Liabilities
  45 ```
  46
  47 ```bash
  48 # how much did I spend and earn this month?
  49   ledger bal ^Expenses ^Income --invert
  50 ```
  51
  52 ```bash
  53 # how much was spent over the course of 3 days? (totalled)
  54   ledger reg -b 01/25 -e 01/27 --subtotal
  55   ledger reg -b 01/25 -e 01/27 --subtotal grocery
  56 ```
  57
  58 Format
  59 ------
  60
  61 ### Basic format
  62
  63 ```
  64 2013/01/03 * Rent for January
  65   Expenses:Rent   $600.00
  66   Assets:Savings
  67 ```
  68
  69 `*` = cleared, `!` = pending
  70
  71 ### Secondary dates
  72
  73 ```
  74 2008/01/01=2008/01/14 Client invoice
  75 ```
  76
  77 It can mean anything you want, eg, for the estimated date you'll be paid.
  78
  79 ### Balance assertions
  80
  81 ```
  82 2008/01/01 * KFC
  83   Expenses:Food    $20
  84   Assets:Cash     $-20  = $500
  85 ```
  86 {: data-line="3"}
  87
  88 `Cash $X = $500` ensures Cash is at $500 after the transaction.
  89
  90 ### Balance assignment
  91
  92 ```bash
  93 2008/01/01 * Cash balance
  94   Assets:Cash              = $500
  95   Equity:Adjustments
  96
  97 2008/01/01 * KFC
  98   Expenses:Food            $20
  99   Assets:Cash              = $500
 100 ```
 101 {: data-line="2,7"}
 102
 103 `ACCOUNT = $500` figures out what's needed to make it $500.
 104
 105 ### Payables
 106
 107 ```bash
 108 2008/04/25 * Rent
 109   (Assets:Checking)  -$200
 110   Expenses:Rent
 111 ```
 112 {: data-line="2"}
 113
 114 ### Commodities
 115
 116 ```bash
 117 ; cost per item
 118 2010/05/31 * Market
 119   Assets:Fridge                35 apples @ $0.42
 120   Assets:Cash
 121 ```
 122 {: data-line="3"}
 123
 124 ```bash
 125 ; total cost
 126 2010/05/31 * Market
 127   Assets:Fridge                35 apples @@ $14.70
 128   Assets:Cash
 129 ```
 130 {: data-line="3"}
 131
 132 ```bash
 133 ; fixed lot prices
 134 2010/05/31 * Gas
 135   Expenses:Gasoline             11 GAL {=$2.299}
 136   Assets:Cash
 137 ```
 138 {: data-line="3"}
 139
 140 ### Commodity definitions
 141
 142 ```
 143 commodity $
 144   note American Dollars
 145   format $1,000.00
 146   nomarket
 147   default
 148 ```
 149
 150 ### Budgeting
 151
 152 ```
 153 ~ Monthly
 154   Expenses:Rent  $500
 155   Expenses:Food  $100
 156   Expenses        $40 ; everything else
 157   Assets
 158
 159 ~ Yearly
 160 ```
 161
 162 ```bash
 163 ledger bal --budget Expenses
 164 ledger bal --unbudgeted Expenses
 165 ```
 166 {: .-setup}
 167
 168 ### Comments
 169
 170     ; line comment
 171     # also line comment
 172     % also line comment
 173     | also line comment
 174     * also line comment
 175
 176 Querying
 177 --------
 178
 179 ### Periods
 180
 181 ```
 182 [interval] [begin] [end]
 183 ```
 184
 185 ```
 186 interval:
 187   every day|week|month|quarter|year
 188   every N days|weeks|...
 189   daily|weekly|...
 190 ```
 191
 192 ```
 193 begin:
 194   from <spec>
 195 end:
 196   to <spec>
 197 ```
 198
 199 ```
 200 spec:
 201   2004
 202   2004/10/1
 203 ```
 204
 205 ```bash
 206 $ ledger bal|reg --period "until aug"
 207 $ ledger bal|reg --period "last oct"
 208 $ ledger bal|reg --period "every week"
 209 ```
 210 {: .-setup}
 211
 212 ### Register
 213
 214 ```bash
 215 $ ledger reg
 216 ```
 217 {: .-setup}
 218
 219 ```bash
 220   -D, --daily
 221   -W, --weekly
 222   -M, --monthly
 223       --quarterly
 224   -Y, --yearly
 225   -s, --subtotal
 226   --start-of-week monday
 227 ```
 228
 229 ```bash
 230   -S, --sort date
 231   -S, --sort amount
 232 ```
 233
 234 ### Filters
 235
 236 ```bash
 237 -b, --begin DATE
 238 -e, --end DATE
 239
 240 -d payee =~ /pioneer/
 241
 242 -C, --cleared    # (with *)
 243 -U, --uncleared  # (no *)
 244     --pending    # (with !)
 245
 246 -R, --real       # ignore virtual postings (eg: "(Cash)  $-400")
 247 -L, --actual     # no automated postings (eg: "= /^Income/")
 248
 249 -r, --related   # show the other side
 250                 # "reg -r savings" shows where it comes from)
 251 ```
 252
 253 ### Queries
 254
 255     ^regex$
 256     @payee
 257     %tag
 258     %tag=value
 259     =note
 260     #code
 261     term and term
 262     term or term
 263     not term
 264     \( term \)
 265
 266 Example:
 267
 268     ledger r ^expenses and @Denny's
 269     ledger r food and @Starbucks and not dining
 270
 271 ### Display
 272
 273 ```bash
 274 -n, --collapse       # [register] collapse entries
 275                      # [balance] no grand total
 276 -s, --subtotal       # [balance] show sub-accounts
 277                      # [other] show subtotals
 278 --flat
 279 ```
 280
 281 ### Effective dates
 282
 283 ```bash
 284 2008/01/01=2008/01/14 Client invoice  ;  estimated date you'll be paid
 285   Assets:Accounts Receivable            $100.00
 286   Income: Client name
 287 ```
 288 {: data-line="1"}
 289
 290 Say you're in business. If you bill a customer, you can enter something like above.
 291 Then, when you receive the payment, you change it to:
 292
 293 ```bash
 294 2008/01/01=2008/01/15 Client invoice ;  actual date money received
 295   Assets:Accounts Receivable            $100.00
 296   Income: Client name
 297 ```
 298 {: data-line="1"}
 299
 300 ## References
 301 {: .-one-column}
 302
 303 * <http://ledger-cli.org/3.0/doc/ledger3.html>
 304 * <https://gist.github.com/agaviria/3317397>
 305 {: .-also-see}