LEDGER(1)

📦
version 3.4.1 · 5 versions
, in alpine 3.24, arch rolling, fedora 43, fedora 44, nixos 26.05, nixpkgs unstable, ubuntu resolute

✨ LEDGER ✨ (the manual, part 1)

okay bestie, sit down, hydrate, because we're about to talk about the ledger command — yes that's the manual name, it's LEDGER, section 1 of the General Commands Manual, and it's giving ✨*command-line double-entry account reporting tool*✨ energy 💅

💖 NAME 💖

ledger — Command-line, double-entry account reporting tool

like. that's the whole name. short. iconic. no notes. 👑

🌸 SYNOPSIS 🌸

okay so here's the vibe check on how you actually call this thing:

ledger [options] [command] [arguments]

that's it, that's the shape of every invocation fr fr — you throw in some options, you pick a command, you hand it some arguments, and she goes 🦋

🎀 DESCRIPTION 🎀

ngl, ledger is a command-line accounting tool, and the way it works is built on the power and completeness of double-entry accounting 🔥 like, the real deal, the whole system, not a watered-down little baby version.

but here's the part that matters most, bestie, so listen up: ledger is only a reporting tool. that means it never modifies your data files. ever. not once. your data is safe, your data is untouched, your data is fine 💜 she just reads, she reports, she serves cunt and leaves. no cap.

and what does she give you in return? a large selection of reports 📊 plus, and this is the fun part, different ways to customize them to your needs — so you can make the output look however you want it to look, tailored to you, specifically, because you're the main character 🫶

lowkey the whole point: ledger reads your stuff, never writes to it, and then gives you a million ways to look at it. obsessed. 😭

more of this manual is on the way, we're just getting started, don't go anywhere 🧚

✨ COMMANDS ✨

okay so bestie, ledger accepts a whole bunch of top-level commands and each one generates a different kind of basic report 💖. Most of them take a report-query argument, so you can tell it exactly what should get reported. Wanna know how the syntax of a report-query works? Go read the “QUERIES” section, it's all in there. In its most basic form you just hand it one or more strings and boom 💥 — you get a report for every account containing those strings.

And here's the iconic part: if you give it no command at all, ledger enters a REPL, aka a command loop, so you can run several commands over the same dataset without reparsing everything. main character energy honestly 🫶

Here's the complete list of accepted reporting commands, no cap:

  • accounts [report-query] — Lists every account for postings that match the report-query. ✨
  • balance [report-query] — Prints a balance report showing totals for postings that match report-query, plus aggregate totals for the parents of those accounts. The options people reach for most with this one are:
    • --basis (-B) — Report in terms of cost basis, not amount or value. This is the only form of report guaranteed to always balance to zero when no report-query is specified. Only show totals for the top-most accounts.
    • --empty (-E) — Show accounts whose total is zero.
    • --flat — Instead of displaying a hierarchical tree, flatten the report so it only shows subtotals for accounts matching report-query.
    • --no-total — Suppress the summary total that shows at the bottom of the report.

The synonyms bal and b are also accepted.

  • budget [report-query] — A special balance report that throws in three extra columns: the amount budgeted during the reporting period, how spending differed from the budget, and the percentage of budget spent (it exceeds 100% if you go over budget 👀). Heads up though — budgeting requires one or more “periodic transactions” to be defined in your data file(s). See the manual for more info.
  • cleared [report-query] — A special balance report that adds two extra columns: the cleared balance for each account, and the date of the most recent cleared posting in that account. For this accounting to actually mean anything, the cleared flag must be set on at least one posting. See the manual for more info.
  • commodities [report-query] — Lists all commodities for postings matching the report-query.
  • convert — Reads data from a CSV (comma-separated values) file and generates ledger transactions. 🦋
  • csv [report-query] — A report of postings matching the report-query in CSV format (comma-separated values). Perfect for exporting your data into a spreadsheet for further analysis or charting. 💅
  • entry [entry-template] — Generates and displays a brand new, properly formatted ledger transaction by comparing the entry-template to the transactions in your data file(s). Want the full tea on draft templates and how to use this command to quickly create new transactions? See the “ENTRIES” section.

The synonym xact is also accepted.

  • emacs [query] — Outputs posting and transaction data in a format that's readily consumed by the Emacs editor, as a series of Lisp forms. This is what the Emacs ledger-mode uses to process reporting data from ledger.
  • equity [report-query] — Prints a transaction with a series of postings that balance the current totals for accounts matching the report-query, in a special account called Equity:Opening Balances. The whole point of this report is closing the books for a prior year, while using those equity postings to carry forward the balances. 👑
  • payees [report-query] — Lists all payees for postings matching the report-query.
  • pricemap — Produces a file you can use to generate a graph with graphviz, showing the relationship of commodities in the ledger file. 🌈
  • prices [report-query] — Reports prices for all commodities in postings matching the report-query. Prices are reported with the granularity of a single day.
  • pricedb [report-query] — Reports prices for all commodities in postings matching the report-query. Prices are reported down to the second, using the same format as the ~/.pricedb file. ⭐
  • print [report-query] — Prints out the full transactions of any matching postings using the same format as they would appear in a data file. Great for extracting subsets out of a ledger file to move into other files.
  • push [options] — In the REPL, pushes a set of command-line options so they'll apply to all subsequent reports.
  • pop — In the REPL, pops any option settings that have been pushed.
  • register [report-query] — Lists all postings matching the report-query. This is one of the most common commands and can give you a whole variety of useful reports. Options most commonly used with it are:
    • --average (-A) — Show the running average, rather than a running total.
    • --current (-c) — Don't show postings beyond the present day.
    • --exchange "COMMODITY [, COMMODITY, ...]" (-X) — Render all values in the given commodity, if a price conversion rate can be determined. If multiple commodities are given, values in a listed commodity will remain as-is, and others will be displayed in the first listed commodity they can be converted to. Rates are always displayed relative to the date of the posting they are calculated for. This means a register report is a historical value report. For current values, it may be preferable to use the balance report.
    • --gain (-G) — Show any gains (or losses) in commodity values over time.
    • --head number — Only show the top number postings.
    • --historical (-H) — Value commodities at the time of their acquisition.
    • --invert — Invert the value of amounts shown.
    • --market (-V) — Show current market values for all amounts. This is determined in a somewhat magical fashion 🧚. It's probably more straightforward to use the --exchange option.
    • --period time-period (-p) — Show postings only for the given time-period.
    • --related (-r) — Show postings that are related to those that would have been shown. It has the effect of displaying the "other side" of the postings.
    • --sort value-expression (-S) — Sort postings by evaluating the given value-expression. Note that a comma-separated list of expressions is allowed, in which case each sorting term is used in order to determine the final ordering. For example, to search by date and then amount, one would use:
ledger reg --sort 'date, amount'

The sort order may be controlled with the - sign. For example, to sort in reverse chronological order:

ledger reg --sort '-date'
  • --tail number — Only show the last number postings.
  • --uncleared (-U) — Only show uncleared (i.e., recent) postings.

the grouping options that are also kinda useful 💖

  • --by-payee (-P) — Group postings by common payee names.
  • --daily (-D) — Group postings by day.
  • --weekly (-W) — Group postings by week (starting on Sundays).
  • --start-of-week day — Set the start of each report grouped by week to the given day.
  • --monthly (-M) — Group postings by month.
  • --quarterly — Group postings by fiscal quarter.
  • --yearly (-Y) — Group postings by year.
  • --days-of-week — Group postings by the day of the week on which they took place.
  • --subtotal (-s) — Group all postings together. This is very similar to the totals shown by the balance report.

The synonyms reg and r are also accepted.

  • select [sql-query] — Lists all postings matching the sql-query. This command lets you generate SQL-like queries, e.g.:
ledger select date,amount from posts where
account=~/Income/
  • source — Parses a journal file and checks it for errors. ledger will return success if no errors are found. 🙈
  • stats [report-query] — Gives you summary info about all the postings matching report-query. It provides things like:
    • Time range of all matching postings
    • Unique payees
    • Unique accounts
    • Postings total
    • Uncleared postings
    • Days since last posting
    • Posts in the last 7 days
    • Posts in the last 30 days
    • Posts this month
  • xml [report-query] — Outputs data relating to the current report in XML format. It includes all accounts and commodities involved in the report, plus the postings and the transactions they're contained in. See the manual for more info. ✨

🎀 OPTIONS 🎀

  • --abbrev-len INT — Sets the minimum length an account can be abbreviated to if it doesn't fit inside the account-width. If INT is zero, then the account name will be truncated on the right. If INT is greater than account-width, then the account will be truncated on the left, with no shortening of the account names in order to fit into the desired width. 💀
  • --account EXPR — Prepend EXPR to literally every account you report. So --account "'Personal'" would tack Personal: onto the front, and --account "tag('VAT')" would tack the value of the VAT tag to the beginning of every account shown in a balance or register report. it's giving ✨personalized✨.
  • --account-width INT — Sets how wide the account column is in the register report, in characters. INT characters, periodt. 💅
  • --actual (-L) — Report only real transactions — no automated, no virtual ones sneaking in. just the genuine ones bestie. 🫶
  • --add-budget — Show only the postings that are un-budgeted. that's it. that's the whole vibe.
  • --align-intervals — Use the beginning of the reporting period as the start of your intervals, instead of the beginning of the week, month, quarter or year. lowkey a glow-up for your timelines. 📅
  • --amount EXPR (-t) — Applies the given value expression to the posting amount. So with --amount EXPR you can apply an arbitrary transformation to the postings — go off, main character energy. 💫
  • --amount-data (-j) — On a register report, prints only the dates and the amount of the postings. so so useful for graphing and spreadsheet applications. spreadsheet girlies rise up. 📊
  • --amount-width INT — Sets the width, in characters, of the amount column in the register report.
  • --anon — Anonymizes registry output, mostly for sending in bug reports. protect ur privacy bestie 🙈
  • --ansi — Use color if your terminal supports it. Alias for --color. 🌈
  • --args-only — Ignores init files AND environment variables for the ledger run. it's giving "no outside opinions". 💀
  • --auto-match — When you're generating a ledger transaction from a CSV file using the convert command, this automatically matches an account from the Ledger journal. ✨
  • --aux-date — Shows auxiliary dates for all calculations. Alias for --effective.
  • --average (-A) — Prints average values over the number of transactions instead of running totals. the math girlies ate this one. 🎀
  • --average-lot-prices — Reports the average price at which each commodity was purchased, in a balance report.
  • --balance-format FMT — Specifies the format to use for the balance report.
  • --base — Reduces convertible commodities down to the bottom of the conversion — like, display time in seconds. bottom of the stack energy. 🧚
  • --basis (-B) — Reports the cost basis on all posting. Alias for --cost.
  • --begin DATE (-b) — Specifies the start DATE of all calculations. Transactions before that date? ignored. not even a little bit considered bestie.
  • --bold-if EXPR — Prints the ENTIRE line in bold if the given value expression is true. dramatic much? iconic much? 💅
  • --budget — Only display budgeted items. In a register report this displays transaction in the budget; in a balance report it displays accounts in the budget. 🍓
  • --budget-format FMT — Specifies the format to use for the budget report.
  • --by-payee (-P) — Groups postings in the register report by common payee names. bestie-coded grouping fr fr. 🫶
  • --check-payees — Enables strict and pedantic checking for payees, as well as accounts, commodities and tags. no typos allowed, no cap. 👑
  • --cleared (-C) — Displays only cleared postings. ✅
  • --cleared-format FMT — Specifies the format to use for the cleared report.
  • --collapse (-n) — Prints only the top level accounts. everything else gets folded away like laundry you're ignoring. 🧺
  • --collapse-if-zero — Collapses the account display only if it has a zero balance. conditional queen. 💅
  • --color — Use color if the terminal supports it. Alias for --ansi. 🌸
  • --columns INT — Makes the register report INT characters wide. By default, ledger will use all available columns in your terminal — it's flexible like that. ✨
  • --cost — Reports the cost basis on all posting. Alias for --basis.
  • --count — Directs ledger to report the number of items when appended to the commodities, accounts or payees commands.
  • --csv-format FMT — Formats the csv report according to FMT.
  • --current (-c) — Shorthand for --limit 'date <= today'. today-only filter, slay. 📆
  • --daily (-D) — Shorthand for --period daily.
  • --date EXPR — Transforms the date of the transaction using EXPR. time travel but make it accounting. 🦋
  • --date-format DATEFMT (-y) — Prints dates using DATEFMT. Refer to strftime(3) for details on the format string syntax. 📝
  • --datetime-format DATETIMEFMT — Prints datetimes using DATETIMEFMT. Refer to strftime(3) for details on the format string syntax. ⏰
  • --date-width INT — Specifies the width, in characters, of the date column in the register report.
  • --day-break — Breaks up a register report of timelog entries that span multiple days, by day. one day at a time bestie. 🗓️
  • --days-of-week — Groups transactions by the days of the week. Alias for --dow.
  • --dc — Displays register or balance in debit/credit format. If you use --dc with either the register or balance commands, you'll now get separate columns for debits and credits. fancy fr. 💚
  • --debug STR — If ledger has been built with debug options, this provides extra data during the run. 🐛
  • --decimal-comma — Directs ledger to parse journals using the European standard — comma as the decimal separator, vice a period. 🇪🇺
  • --depth INT — Limits the depth of displayed accounts in balance and register reports. Any accounts of greater depth get folded into their parent at the specified level. Like, with --depth 2 the account Expenses:Entertainment:Dining would be folded into Expenses:Entertainment for display. Importantly — this is a display predicate, which means it only affects display, NOT the total calculations. don't let it gaslight your totals bestie. ⚠️
  • --detail — Related to the convert command. Synonym to the --rich-data option.
  • --deviation — Reports each posting's deviation from the average. It is only meaningful in the register and prices reports.
  • --display EXPR (-d) — Displays lines that satisfy the expression EXPR. ✨
  • --display-amount EXPR — Applies a transformation to the displayed amount. This happens after calculations occur. timing is everything. 💅
  • --display-total EXPR — Applies a transformation to the displayed total. This also happens after calculations occur.
  • --dow — Groups transactions by the days of the week. Alias for --days-of-week.
  • --download — Causes quotes to be automagically 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 prices are then appended to the price database, usually specified using the environment variable LEDGER_PRICE_DB. ✨ automagically ✨
  • --effective — Shows auxiliary dates for all calculations. Alias for --aux-date.
  • --empty (-E) — Includes empty accounts in the report. they're still valid bestie, let them in. 🫶
  • --end DATE (-e) — Constrains the report so that transactions on or after DATE are not considered. cut off, bye. ✂️
  • --equity — Related to the equity command. Gives current account balances in the form of a register report.
  • --exact — Reports the beginning and ending of periods by the date of the first and last posting occurring in that period. precise, no cap. 🎯
  • --exchange "COMMODITY [, COMMODITY, ...]" (-X) — Displays values in terms of the given COMMODITY. If multiple commodities are given, values in a listed commodity will remain as-is, and others will be displayed in the first listed commodity they can be converted to. 💱
  • --file FILE (-f) — Reads journal data from FILE. 📂
  • --first INT — Prints the first INT entries. Opposite of --last INT. Alias for --head.
  • --flat — Forces the full names of accounts to be used in the balance report. The balance report will not use an indented tree. no nesting, just vibes. 🌈
  • --force-color — Outputs TTY color codes even if the TTY doesn't support them. Useful for TTYs that don't advertise their capabilities correctly. delulu is the solulu. 💅
  • --force-pager — Forces ledger to paginate its output. 📄
  • --forecast-while EXPR — Continues forecasting while VEXPR is true. Alias for --forecast.
  • --forecast-years INT — Forecasts at most INT years into the future. future-tripping but it's accounting. 🔮
  • --format FMT (-F) — Uses the given format string FMT to print output.
  • --gain (-G) — Reports net gain or loss for commodities that have a price history. 📈
  • --generated — Includes auto-generated postings (such as those from automated transactions) in the report, in cases where you normally wouldn't want them. letting the bots in. 🤖
  • --group-by EXPR — Groups transactions together in the register report. EXPR can be anything, although the most common would be payee or commodity. The tag() function is also useful here. 💖
  • --group-title-format FMT — Sets the format for the headers that separate reports sections of a grouped report. Only has effect with a --group-by EXPR register report.
  • --hashes ALGO — Records the hash of each transaction in a Hash metadata value, according to the hashing algorithm given by the ALGO argument. Supported algorithms are sha512 or sha512_half, where both use SHA512, but the latter only stores the first half of the hash value.

If a Hash metadata value is explicitly provided and does not match what would have been generated, an error is reported. Hashes depend on previous entries, such that setting a single hash value is sufficient to guarantee the shape of the entire history leading up to that entry. cryptographic queen behavior. 👑

  • --head INT — Prints the first INT entries. Opposite of --tail INT. Alias for --first.
  • --help — Prints this man page. hi bestie 👋
  • --immediate — Evaluates calculations immediately rather than lazily. no procrastination allowed. 💀
  • --import FILE — Imports FILE as a Python module. 🐍
  • --init-file FILE (-i) — Reads FILE before any other ledger file. This file may not contain any postings, but it may contain option settings. To specify options in the init file, use the same syntax as the command-line, but put each option on its own line. one option per line bestie, we're not savages. 💅
  • --inject STR — Uses STR amounts in calculations. In case you know what amount a transaction should be, but the actual transaction has the wrong value, you can use metadata STR to specify the expected amount. fixing the math behind the scenes, sneaky slay. ✨
  • --input-date-format DATEFMT — Specifies the input date format for journal entries. 📅
  • --invert — Changes the sign of all reported values. flip it, reverse it, invert it. 🔄
  • --last INT — bestie, only show the last INT entries. It's the mirror image of --first INT 💫. Only useful on a register report. Alias for --tail.
  • --leeway INT (-Z) — alias for --price-exp. that's it, that's the whole thing 🎀
  • --limit EXPR (-l) — caps how many postings get used in calculations. a little velvet rope for your data ✨
  • --lisp-date-format FORMAT — sets how dates look in lisp output. the default is the Emacs Lisp time format. other options? 'seconds' (Unix epoch seconds) or a strftime format string like '%Y-%m-%d'. pick ur fighter 💅
  • --lot-dates — reports the date each commodity in a balance report got purchased. receipts for ur receipts 📅
  • --lot-notes — reports the tag attached to each commodity in a balance report. the lil sticky note energy 🏷️
  • --lot-prices — reports the price each commodity in a balance report was purchased at. how much u paid, no cap 💸
  • --lots — reports the date and price each commodity was purchased at in a balance report. two for one, we love to see it 🫶
  • --lots-actual — keeps commodities unique so they don't get merged during reporting, without printing the lot annotations. lowkey protective 🛡️
  • --market (-V) — uses the latest market value for all commodities. main character pricing ✨
  • --master-account STR — prepends every account name with STR. like a group chat prefix but for ur chart of accounts 👑
  • --meta STR — in the register report, prepends the transaction with the value of the given tag STR. it's giving context 🦋
  • --meta-width INT — sets the width of the Meta column used for the --meta TAG options. give it room to breathe 🌬️
  • --monthly (-M) — shorthand for --period monthly. short king behavior 💅
  • --no-aliases — aliases are completely ignored. not even a little bit acknowledged 🙈
  • --no-color — suppresses any color TTY output. monochrome era, very demure 🖤
  • --no-pager — disables the pager on TTY output. no scrolling, just vibes 📜
  • --no-revalued — stops ledger from showing <Revalued> postings. we don't need to see them ✋
  • --no-rounding — doesn't output "<Adjustment>" postings.
⚠️ note that this will cause the running total to often not add up! its main use is for --amount-data (-j) and --total-data (-J) reports. so like, use it on purpose, not by accident 😭
  • --no-titles — suppresses the output of group titles. no header moment 📛
  • --no-total — suppresses printing the final total line in a balance report. the grand finale is cancelled 🎬
  • --now DATE — uses DATE as the current date. this affects the output when using --period, --begin, --end, or --current to decide which dates lie in the past or future. time travel but make it accounting 🕰️
  • --only EXPR — a postings predicate that applies after certain transforms have been executed, such as periodic gathering. late-stage filtering, iykyk 🔍
  • --options — displays the options in effect for this ledger invocation, along with their values and the source of those values. receipts on ur receipts 🔎
  • --output FILE (-o) — redirects ledger's output to FILE. bye bye stdout 👋
  • --pager STR — uses STR as the pager program. u pick the scroll gremlin 🧚
  • --payee — sets a value expression for formatting the payee. in the register report this prevents the second entry from having a date and payee for each transaction. tidier, cleaner, iconic 💅
  • --payee-width INT — sets the number of columns dedicated to the payee in the register report to INT. personal space for ur payees 📏
  • --pedantic — accounts, tags or commodities not previously declared will cause errors. strict mode, no chill 😤
  • --pending — uses only postings marked pending. halfway there, fr fr ⏳
  • --percent (-%) — calculates the percentage value of each account in a balance report. only works for accounts that have a single commodity 🍓
  • --period PERIOD (-p) — defines a period expression that sets the time period during which transactions are to be accounted. for a register report, only the transactions that satisfy the period expression will be displayed. for a balance report, only those transactions will be accounted in the final balances. time window: acquired ⏰
  • --period-sort — sorts the postings within transactions using the given value expression. inner organization ✨
  • --permissive — quiet balance assertions. shhh, it's fine 🤫
  • --pivot TAG — produces a balance pivot report "around" the given TAG. rotating around ur data like a lil planet 🌍
  • --plot-amount-format FMT — defines the output format for an amount data plot. graph girlies rise 📊
  • --plot-total-format FMT — defines the output format for a total data plot. 📈
  • --prepend-format FMT — prepends FMT to every single line of the output. every. single. line. 🫶
  • --prepend-width INT — reserves INT spaces at the beginning of each line of the output. breathing room 🎀
  • --price (-I) — uses the price of the commodity purchase for performing calculations. original price tag energy 🏷️
  • --price-db FILE — no description given in the original, bestie. it's just FILE. that's the whole entry 💀
  • --price-exp INT (-Z) — sets the expected freshness of price quotes, in INT hours. so 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 fresh enough. alias for --leeway. expiration date check 🥛
  • --prices-format FMT — sets the format for the prices report. 💰
  • --pricedb-format FMT — sets the format expected for the historical price file. 📚
  • --primary-date — shows primary dates for all calculations. alias for --actual-dates 👑
  • --quantity (-O) — reports commodity totals (this is the default). the classic, the standard, the blueprint ✨
  • --quarterly — shorthand for --period quarterly. four times a year, four times the slay 🌸
  • --raw — in the print report, shows transactions using the exact same syntax as specified by the user in their data file. doesn't do any massaging or interpreting. can be useful for minor cleanups, like just aligning amounts. raw dogging ur ledger, respectfully 🗂️
  • --real (-R) — accounts using only real transactions, ignoring virtual and automatic transactions. only the real ones 🔥
  • --recursive-aliases — causes ledger to try to expand aliases recursively, i.e. try to expand the result of an earlier expansion again, until no more expansions apply. inception but for aliases 🌀
  • --register-format FMT — defines the output format for the register report. ur register, ur rules 💅
  • --related (-r) — in a register report, shows the related account. this is the other side of the transaction. seeing both perspectives 🪞
  • --related-all — shows all postings in a transaction, similar to --related but shows both sides of each transaction. no secrets here 👀
  • --revalued — reports discrepancy in values for manual reports by inserting <Revalued> postings. this is implied when using the --exchange (-X) or --market (-V) option. 💫
  • --revalued-only — shows only <Revalued> postings. exclusive club 🎟️
  • --revalued-total — displays the sum of the revalued postings as the running total, which serves to show unrealized capital in a gain/losses report. the tea ☕
  • --rich-data — when generating a ledger transaction from a CSV file using the convert command, adds CSV, Imported, and UUID meta-data. extra toppings 🍒
  • --seed INT — sets the random seed to INT for the generate command. used as part of development testing. deterministic chaos 🎲
  • --script FILE — executes a ledger script. run it bestie 📜
  • --sort EXPR (-S) — sorts the register report based on the value expression EXPR. organize ur life ✨
  • --sort-xacts — sorts the postings within transactions using the given value expression. inner sorting, outer peace 🧘
  • --start-of-week STR — uses STR as the particular day of the week to start when using the --weekly option. STR can be day names, their abbreviations like "Mon", or the weekday number starting at 0 for Sunday. pick ur week opener 📆
  • --sort-all — sorts all accounts and commodities. everything, everywhere, in order 🌈
  • --strict — accounts, tags or commodities not previously declared will cause warnings. softer than --pedantic but still paying attention 👀
  • --subtotal (-s) — reports the register as a single subtotal. condensed ✨
  • --tail INT — reports only the last INT entries. only useful on a register report. alias for --last INT 🍑
  • --time-colon — displays the value for commodities based on seconds as hours and minutes. thus 8100s will be displayed as 2:15h instead of 2.25h. clock format, cuter format 🕐
  • --time-report — adds two columns to the balance report to show the earliest checkin and checkout times for timelog entries. ⏱️
  • --total EXPR (-T) — defines a value expression used to calculate the total in reports. math but make it ✨
  • --total-data (-J) — shows only dates and totals to format the output for plots. data for the graph girlies 📉📈
  • --total-width INT — sets the width of the total field in the register report. give ur totals some space 📐
  • --trace INT — enables tracing. the INT specifies the level of trace desired. follow the breadcrumbs 🍞
  • --truncate STR — indicates how truncation should happen when the contents of columns exceed their width. valid arguments for STR are leading, middle, and trailing. the default is smarter than any of these three, as it considers sub-names within the account name (that style is called "abbreviate"). smart default behavior, we stan 🧠
  • --unbudgeted — shows only un-budgeted postings. the wild ones 🦋
  • --uncleared (-U) — uses only uncleared transactions in calculations and reports. not yet checked off the list 📝
  • --unrealized — shows generated unrealized gain and loss accounts in the balance report. 👛
  • --unrealized-gains — lets u specify what account name should be used for unrealized gains. defaults to Equity:Unrealized Gains. often set in one's init file to change the default. 💚
  • --unrealized-losses — lets u specify what account name should be used for unrealized losses. defaults to Equity:Unrealized Losses. often set in one's init file to change the default. ❤️
  • --unround — performs all calculations without rounding and displays results to full precision. every last decimal, no cap 🔬
  • --values — shows the values used by each tag when used in combination with the tags command. 🏷️
  • --value-expr EXPR — sets a global value expression annotation. ✍️
  • --verbose — prints detailed information on the execution of ledger. tell me everything 🗣️
  • --verify — enables additional assertions during run-time. this causes a significant slowdown. when combined with --debug CODE, ledger will produce memory trace information. 🐢
  • --verify-memory — verifies that every constructed object is properly destructed. this is for debugging purposes only. 🧹
  • --version — prints version information and exits. which era of ledger r u in 💖
  • --weekly (-W) — shorthand for --period weekly. seven day slay 🎀
  • --wide (-w) — assumes 132 columns instead of the TTY width. big screen energy 🖥️
  • --yearly (-Y) — shorthand for --period yearly. annual icon behavior 👑

🎀 PRE-COMMANDS 🎀

Okay bestie, pre-commands are literally the vibe check you run before committing to a command. They're here for when you're like "hmm, how does this even work??" and you don't wanna mess anything up. ✨

The glow-up here: a pre-command is not like a regular command because it completely ignores the journal data file, and it also doesn't read your init file. So it's a totally clean slate, no baggage, main character energy only. 💅

  • args / query — This one evaluates whatever arguments you throw at it and then shows you how ledger is interpreting them, all against this model transaction right here:
2004/05/27 Book Store
    ; This note applies to all postings. :SecondTag:
    Expenses:Books                 20 BOOK @ $10
    ; Metadata: Some Value
    ; Typed:: $100 + $200
    ; :ExampleTag:
    ; Here follows a note describing the posting.
    Liabilities:MasterCard        $-200.00
  • eval — Runs your value expression against the model transaction so you can see what's up. 🧚
  • format — Prints out all the deets of how ledger uses the formatting description you gave it, and applies it against a model transaction.
  • parse / expr — Prints the deets of how ledger uses your value expression description, and applies it against a model transaction.
  • generate — Randomly generates syntactically valid ledger data from a seed. It's used by the GenerateTests harness for development testing. No cap. 🌱
  • period — Evaluates the period you hand it and reports back how ledger interprets it.
  • template — Shows the insertion template that the xact command generates. This is a debugging command, so it's giving ✨developer tools✨ energy.

🌈 QUERIES 🌈

So the syntax for reporting queries can get kinda complex — it's not giving simple, it's giving layered. 👑

It's a series of query terms, and between them there's an implicit OR operator. Here are all the terms you can use:

  • regex — A bare string gets taken as a regular expression (PCRE) that matches the full account name. So if you wanna report the current balance for all assets and liabilities, you'd go:
ledger bal asset liab
  • payee regex (@regex) — This queries on the payee instead of the account. 🫶
  • tag regex (%regex) — This queries on tags.
  • note regex (=regex) — Queries on anything found in an item's note.
  • code regex (#regex) — Queries on the xact's optional code (which can be literally any string the user wants).
  • term and term — Query terms get joined by an implicit OR operator, but you can switch that to AND with the and keyword. For example, to show food expenditures happening at Shakee's Pizza, you could say:
ledger reg food and @Shakee
  • term or term — When you wanna be more explicit about it, use the OR operator. 💖
  • show — (yes, that's the whole thing, it's just show)
  • not term — Reverses the logical meaning of the term that follows it. And combined with parentheses it absolutely ate:
ledger reg food and @Shakee and not dining
  • ( term ) — If you wanna mix OR and AND operators together, it's usually super helpful to wrap the logical units in parentheses.
⚠️ NOTE: Because of the way some shells interpret parentheses, you should always escape them. Like this, bestie:
ledger bal \( assets or liab \) and not food

✨ EXPRESSIONS ✨

okay bestie, this is the function library — the little guys you can call inside value expressions and format strings. they all show up in the same section of the manual, so here's the whole lineup, no skips 💅

  • abs(value) — gives you the absolute value of whatever value you hand it. negative vibes removed ✨
  • account — returns the posting's account.
  • account_base — returns the base account, i.e. everything after the last account delimiter ':'.
  • actual — true if the transaction is real (i.e. not an automated or virtual transaction), false otherwise.
  • amount — returns the amount of the posting.
  • amount_expr — returns the calculated amount of the posting, following whatever the --amount option says.
  • ansify_if(value, color, bool) — renders value as a string and, if bool is true, slaps on the proper ANSI escape codes so it shows up in the given color. it usually peeks at the --color option, like this:
ansify_if(amount, blue, options.color)
  • beg_line — line number where the entry for the posting begins.
  • beg_pos — character position where the entry for the posting begins.
  • ceiling(value) — returns the next integer of value toward +infinity.
  • cleared — true if the posting was cleared, false otherwise.
  • code — returns the transaction code, that string chillin' between the parenthesis after the date.
  • commodity(value) — returns the commodity of value, or the posting amount if value wasn't specified.
  • date — returns the date of the posting.
  • end_line — line number where the entry for the posting ends.
  • end_pos — character position where the entry for the posting ends.
  • floor(value) — returns the next integer of value toward -infinity.
  • filename — the name of the ledger data file from whence the posting came 🦋
  • format(string) — evaluates string as a format, exactly like the --format option does.
  • format_date(date, format) — returns the date as a string using format. for the format string deets, go peek at strftime(3).
  • format_datetime(datetime, format) — returns the datetime as a string using format. again, strftime(3) has the format string details.
  • get_at(seq, index) — returns the value at index from seq. used internally to build the different reports.
  • has_meta(tag) — true if the posting has metadata named tag, false otherwise.
  • has_tag(tag) — true if the posting has metadata named tag, false otherwise.
  • is_seq(value) — true if value is a sequence. used internally.
  • join(value) — replaces all newlines in value with \n.
  • justify(value, first_width, latter_width, right_justify, colorize) — right- or left-justifies the string representing value. the field width on the first line is first_width. for the lines after that, the width is latter_width. if latter_width is -1, then first_width gets used for every line. if right_justify is true, the field is right justified inside the field width. if it's false, the field is left justified and padded out to the full width of the field. if colorize is true, ledger will honor color settings 🎀
  • market(value, datetime) — returns the price of value at datetime. heads up: datetime must be wrapped in brackets to parse correctly, e.g. [2012/03/23].
  • meta(name) — returns the value of the metadata named name.
  • note — returns the note for the posting.
  • now — returns the current datetime ⏰
  • options — a variable giving you access to the values of the given command-line options by their long option names. e.g. to check whether --daily (-D) was given, use option.daily.
  • payee — returns the payee of the posting.
  • percent(value_a, value_b) — returns the percentage of value_a in relation to value_b (which is treated as 100%).
  • pending — true if the posting is marked as pending, false otherwise.
  • percent(value_a, value_b) — returns the percentage of value_a in relation to value_b. (yep, it's listed twice in the manual — iconic of it honestly 💀)
  • print(value) — prints value to stdout. used internally for debugging.
  • quantity(value) — returns the quantity of value for values that have a per-unit cost.
  • quoted(expression) — surrounds expression with double quotes.
  • quoted_rfc(expression) — surrounds expression with double quotes, compliant with rfc 4180.
  • real — true if the transaction is real (i.e. not an automated or virtual transaction), false otherwise.
  • roundto(value, n) — returns value rounded to n digits. does not affect formatting.
  • should_bold — true if the expression given to --bold-if evaluates to true. internal use only! 🙈
  • scrub(value) — cleans value using various transformations, such as round, stripping value annotations, and more.
  • strip(value) — strips the value annotation from value.
  • tag(name) — returns the value of the tag named name.
  • to_amount(value) — converts value to an amount. internal use only!
  • to_balance(value) — converts value to a balance. internal use only!
  • to_boolean(value) — converts value to a boolean. internal use only!
  • to_date(value) — converts value to a date. internal use only!
  • to_datetime(value) — converts value to a datetime. internal use only!
  • to_int(value) — returns the integer value for value.
  • to_mask(value) — converts value to a mask. internal use only!
  • to_sequence(value) — converts value to a sequence. internal use only!
  • to_string(value) — converts value to a character string.
  • today — returns today's date 🌸
  • total — returns the total of the posting.
  • total_expr — returns the calculated total of the posting, following whatever the --total option says.
  • trim(value) — trims leading and trailing whitespace off value.
  • truncated(string, total_len, account_len) — truncates string to total_len while making sure each account is at least account_len long.
  • virtual — true if the transaction is virtual, e.g. automated, false otherwise.
  • averaged_lots() — returns lots with averaged prices.
  • clear_commodity() — clears commodity pricing information.
  • commodity_price(commodity) — returns the price of the given commodity.
  • display_amount(amount) — formats amount for display.
  • display_total(total) — formats total for display.
  • lot_date(posting) — returns the lot date of a posting.
  • lot_price(posting) — returns the lot price of a posting.
  • lot_tag(posting) — returns the lot tag of a posting.
  • nail_down(amount) — fixes the precision of an amount.
  • round(amount) — rounds an amount to standard precision.
  • rounded(amount) — returns the rounded version of amount.
  • set_commodity_price(commodity, price) — sets the price for a commodity.
  • top_amount(amount) — returns the top-level amount.
  • unround(amount) — removes rounding from an amount.
  • unrounded(amount) — returns the unrounded version of amount.

💀 DEBUG COMMANDS 💀

besides the regular reporting commands, ledger also takes a lil stack of debug commands. they're giving main-character-forensics energy, ngl:

  • args [report-query] — displays a complete analysis of how ledger interpreted the given report-query. super useful if you wanna understand how report queries get translated into value expressions.
  • eval [value-expression] — evaluates the given value-expression and prints the result. for more on value expressions, see the section “EXPRESSIONS”.
  • format [format-string] — displays an analysis of how format-string was parsed, and what it would look like applied to a sample transaction. for more on format strings, see the section “FORMATS”.
  • generate — generates 50 randomly composed yet valid ledger transactions 🎲
  • parse [value-expression] — parses the given value-expression and displays an analysis of the expression tree and its evaluated value. for more on value expressions, see the section “EXPRESSIONS”.
  • python [file] — invokes a Python interpreter to read the given file. the special part? the ledger module is builtin, not read from disk, so it doesn't need ledger installed anywhere, nor the shared library variants built. slay.
  • reload — reloads all data files for the current session immediately. can only be used in the REPL.
  • template [draft-template] — displays information about how draft-template was parsed. see the section on “DRAFTS”.

🌈 ENVIRONMENT 🌈

every option to ledger can be set with an environment variable, as long as that option has a long name. for example, setting the environment variable LEDGER_DATE_FORMAT="%d.%m.%Y" does the exact same thing as specifying --date-format '%d.%m.%Y' on the command-line. however — options given on the command-line always take precedence over environment variable settings. periodt. 💅

📁 FILES 📁

  • $XDG_CONFIG_HOME/ledger/ledgerrc
  • ~/.config/ledger/ledgerrc
  • ~/.ledgerrc — your personal ledger initializations ✨

👀 SEE ALSO 👀

beancount(1), hledger(1)

the full documentation for ledger is maintained as a Texinfo manual. if the info program is installed on your system, this command:

info ledger3

should give you access to the complete manual. go off, bestie 📖

👑 AUTHORS 👑

John Wiegley ⟨johnw@newartisans.com⟩

and that's the whole page, you made it to the end 🫶 this beauty lives in the Debian edition of the manual, dated December 13, 2023, and you can find it filed under LEDGER(1). go balance those books, icon 💖

📦 where this page comes from