hledger/doc/mockups/help.org
2023-01-25 11:18:08 -10:00

34 KiB
Raw Blame History

0.27

$ hledger help hledger [COMMAND] … [OPTIONS] [ARGS]

Data entry commands: add prompt for transactions and add them to the journal

Reporting commands: print show transaction entries accounts show account names balance show accounts and balances (bal) register show postings and running total (reg) incomestatement show an income statement (is) balancesheet show a balance sheet (bs) cashflow show a cashflow statement (cf) activity show an ascii barchart of posting counts per interval (default: daily) stats show some journal statistics

Add-on commands: autosync chart generate simple balance pie charts check-dates check-dates1 convertdates diff equity show a transaction entry zeroing all accounts estimatedtax estimatedtax.hs interest generate interest transaction entries irr calculate internal rate of return print-unique print only transactions with unique descriptions register-match rewrite add specified postings to matched transaction entries ui ui1 vty start the curses-style interface web start the web interface webdev

General flags: -h help show general help or (after command) command help debug=N show debug output if N is 1-9 (default: 0) version show version information

$ hledger accounts help accounts [OPTIONS] [PATTERNS] show account names

Flags: tree show short account names, as a tree flat show full account names, as a list (default) drop=N flat mode: omit N leading account name parts

General flags: -f file=FILE use a different input file. For stdin, use - rules-file=RFILE CSV conversion rules file (default: FILE.rules) alias=OLD=NEW display accounts named OLD as NEW ignore-assertions ignore any balance assertions in the journal -b begin=DATE include postings/txns on or after this date -e end=DATE include postings/txns before this date -D daily multiperiod/multicolumn report by day -W weekly multiperiod/multicolumn report by week -M monthly multiperiod/multicolumn report by month -Q quarterly multiperiod/multicolumn report by quarter -Y yearly multiperiod/multicolumn report by year -p period=PERIODEXP set start date, end date, and/or reporting interval all at once (overrides the flags above) date2 aux-date use postings/txns' secondary dates instead -C cleared include only cleared postings/txns pending include only pending postings/txns -U uncleared include only uncleared (and pending) postings/txns -R real include only non-virtual postings depth=N hide accounts/postings deeper than N -E empty show empty/zero things which are normally omitted -B cost show amounts in their cost price's commodity -h help show general help or (after command) command help debug=N show debug output if N is 1-9 (default: 0) version show version information

This command lists the accounts referenced by matched postings (and in tree mode, their parents as well). The accounts can be depth-clipped (depth N) or have their leading parts trimmed (drop N).

$ hledger balance help balance [OPTIONS] [PATTERNS] show accounts and balances (bal)

Flags: tree show accounts as a tree (default in simple reports) flat show accounts as a list (default in multicolumn mode) drop=N flat mode: omit N leading account name parts format=FORMATSTR singlecolumn mode: use this custom line format no-elide tree mode: don't squash boring parent accounts -H historical multicolumn mode: show historical ending balances cumulative multicolumn mode: show accumulated ending balances -A average multicolumn mode: show a row average column -T row-total multicolumn mode: show a row total column -N no-total don't show the final total row -V value show amounts as their current market value in their default valuation commodity -o output-file=FILE[.FMT] write output to FILE instead of stdout. A recognised FMT suffix influences the format. -O output-format=FMT select the output format. Supported formats: txt, csv.

General flags: -f file=FILE use a different input file. For stdin, use - rules-file=RFILE CSV conversion rules file (default: FILE.rules) alias=OLD=NEW display accounts named OLD as NEW ignore-assertions ignore any balance assertions in the journal -b begin=DATE include postings/txns on or after this date -e end=DATE include postings/txns before this date -D daily multiperiod/multicolumn report by day -W weekly multiperiod/multicolumn report by week -M monthly multiperiod/multicolumn report by month -Q quarterly multiperiod/multicolumn report by quarter -Y yearly multiperiod/multicolumn report by year -p period=PERIODEXP set start date, end date, and/or reporting interval all at once (overrides the flags above) date2 aux-date use postings/txns' secondary dates instead -C cleared include only cleared postings/txns pending include only pending postings/txns -U uncleared include only uncleared (and pending) postings/txns -R real include only non-virtual postings depth=N hide accounts/postings deeper than N -E empty show empty/zero things which are normally omitted -B cost show amounts in their cost price's commodity -h help show general help or (after command) command help debug=N show debug output if N is 1-9 (default: 0) version show version information

$ hledger print help print [OPTIONS] [PATTERNS] show transaction entries

Flags: -m match=STR show the transaction whose description is most similar to STR, and is most recent -o output-file=FILE[.FMT] write output to FILE instead of stdout. A recognised FMT suffix influences the format. -O output-format=FMT select the output format. Supported formats: txt, csv.

General flags: -f file=FILE use a different input file. For stdin, use - rules-file=RFILE CSV conversion rules file (default: FILE.rules) alias=OLD=NEW display accounts named OLD as NEW ignore-assertions ignore any balance assertions in the journal -b begin=DATE include postings/txns on or after this date -e end=DATE include postings/txns before this date -D daily multiperiod/multicolumn report by day -W weekly multiperiod/multicolumn report by week -M monthly multiperiod/multicolumn report by month -Q quarterly multiperiod/multicolumn report by quarter -Y yearly multiperiod/multicolumn report by year -p period=PERIODEXP set start date, end date, and/or reporting interval all at once (overrides the flags above) date2 aux-date use postings/txns' secondary dates instead -C cleared include only cleared postings/txns pending include only pending postings/txns -U uncleared include only uncleared (and pending) postings/txns -R real include only non-virtual postings depth=N hide accounts/postings deeper than N -E empty show empty/zero things which are normally omitted -B cost show amounts in their cost price's commodity -h help show general help or (after command) command help debug=N show debug output if N is 1-9 (default: 0) version show version information

$ hledger register help register [OPTIONS] [PATTERNS] show postings and running total (reg)

Flags: -H historical include prior postings in the running total -A average show a running average instead of the running total (implies empty) -r related show postings' siblings instead -w width=N set output width (default: terminal width or COLUMNS. -wN,M sets description width as well) -o output-file=FILE[.FMT] write output to FILE instead of stdout. A recognised FMT suffix influences the format. -O output-format=FMT select the output format. Supported formats: txt, csv.

General flags: -f file=FILE use a different input file. For stdin, use - rules-file=RFILE CSV conversion rules file (default: FILE.rules) alias=OLD=NEW display accounts named OLD as NEW ignore-assertions ignore any balance assertions in the journal -b begin=DATE include postings/txns on or after this date -e end=DATE include postings/txns before this date -D daily multiperiod/multicolumn report by day -W weekly multiperiod/multicolumn report by week -M monthly multiperiod/multicolumn report by month -Q quarterly multiperiod/multicolumn report by quarter -Y yearly multiperiod/multicolumn report by year -p period=PERIODEXP set start date, end date, and/or reporting interval all at once (overrides the flags above) date2 aux-date use postings/txns' secondary dates instead -C cleared include only cleared postings/txns pending include only pending postings/txns -U uncleared include only uncleared (and pending) postings/txns -R real include only non-virtual postings depth=N hide accounts/postings deeper than N -E empty show empty/zero things which are normally omitted -B cost show amounts in their cost price's commodity -h help show general help or (after command) command help debug=N show debug output if N is 1-9 (default: 0) version show version information

$ hledger stats help stats [OPTIONS] [PATTERNS] show some journal statistics

Flags: -o output-file=FILE[.FMT] write output to FILE instead of stdout. A recognised FMT suffix influences the format.

General flags: -f file=FILE use a different input file. For stdin, use - rules-file=RFILE CSV conversion rules file (default: FILE.rules) alias=OLD=NEW display accounts named OLD as NEW ignore-assertions ignore any balance assertions in the journal -b begin=DATE include postings/txns on or after this date -e end=DATE include postings/txns before this date -D daily multiperiod/multicolumn report by day -W weekly multiperiod/multicolumn report by week -M monthly multiperiod/multicolumn report by month -Q quarterly multiperiod/multicolumn report by quarter -Y yearly multiperiod/multicolumn report by year -p period=PERIODEXP set start date, end date, and/or reporting interval all at once (overrides the flags above) date2 aux-date use postings/txns' secondary dates instead -C cleared include only cleared postings/txns pending include only pending postings/txns -U uncleared include only uncleared (and pending) postings/txns -R real include only non-virtual postings depth=N hide accounts/postings deeper than N -E empty show empty/zero things which are normally omitted -B cost show amounts in their cost price's commodity -h help show general help or (after command) command help debug=N show debug output if N is 1-9 (default: 0) version show version information

201511 ideas for shorter help

general help: Flags moved to top, -h and help split:

$ hledger help hledger [COMMAND] … [OPTIONS] [ARGS]

General flags: -h show short help (general or, after command, command-specific) help show long help (general or command-specific) debug=N show debug output if N is 1-9 (default: 0) version show version information

Data entry commands: add prompt for transactions and add them to the journal

Reporting commands: print show transaction entries accounts show account names balance show accounts and balances (bal) register show postings and running total (reg) incomestatement show an income statement (is) balancesheet show a balance sheet (bs) cashflow show a cashflow statement (cf) activity show an ascii barchart of posting counts per interval (default: daily) stats show some journal statistics

Add-on commands: autosync chart generate simple balance pie charts check-dates check-dates1 convertdates diff equity show a transaction entry zeroing all accounts estimatedtax estimatedtax.hs interest generate interest transaction entries irr calculate internal rate of return print-unique print only transactions with unique descriptions register-match rewrite add specified postings to matched transaction entries ui ui1 vty start the curses-style interface web start the web interface webdev

-h shows just the command-specific flags:

$ hledger accounts -h accounts [OPTIONS] [PATTERNS] show account names

Flags: tree show short account names, as a tree flat show full account names, as a list (default) drop=N flat mode: omit N leading account name parts

(To see all flags, use help)

$ hledger balance -h balance [OPTIONS] [PATTERNS] show accounts and balances (bal)

Flags: tree show accounts as a tree (default in simple reports) flat show accounts as a list (default in multicolumn mode) drop=N flat mode: omit N leading account name parts format=FORMATSTR singlecolumn mode: use this custom line format no-elide tree mode: don't squash boring parent accounts -H historical multicolumn mode: show historical ending balances cumulative multicolumn mode: show accumulated ending balances -A average multicolumn mode: show a row average column -T row-total multicolumn mode: show a row total column -N no-total don't show the final total row -V value show amounts as their current market value in their default valuation commodity -o output-file=FILE[.FMT] write output to FILE instead of stdout. A recognised FMT suffix influences the format. -O output-format=FMT select the output format. Supported formats: txt, csv.

(To see all flags, use help)

-h shows command-specific flags plus general flags in brief:

$ hledger print -h print [OPTIONS] [PATTERNS] show transaction entries

Flags: -m match=STR show the transaction whose description is most similar to STR, and is most recent -o output-file=FILE[.FMT] write output to FILE instead of stdout. A recognised FMT suffix influences the format. -O output-format=FMT select the output format. Supported formats: txt, csv.

General flags (for more detail, use help): -f file=FILE rules-file=RFILE alias=OLD=NEW ignore-assertions -b begin=DATE -e end=DATE -D daily -W weekly -M monthly -Q quarterly -Y yearly -p period=PERIODEXP date2 aux-date -C cleared pending -U uncleared -R real depth=N -E empty -B cost -h help debug=N version

-h shows command-specific flags in brief plus general flags in brief:

$ hledger register -h register [OPTIONS] [PATTERNS] show postings and running total (reg)

Flags: -H historical -A average -r related -w width=N -o output-file=FILE[.FMT] -O output-format=FMT

General flags: -f file=FILE rules-file=RFILE alias=OLD=NEW ignore-assertions -b begin=DATE -e end=DATE -D daily -W weekly -M monthly -Q quarterly -Y yearly -p period=PERIODEXP date2 aux-date -C cleared pending -U uncleared -R real depth=N -E empty -B cost -h help debug=N version

(for more detail, use help)

-h shows specific flags and general flags in brief, together

$ hledger stats -h stats [OPTIONS] [PATTERNS] show some journal statistics

Flags: -o output-file=FILE[.FMT] -f file=FILE rules-file=RFILE alias=OLD=NEW ignore-assertions -b begin=DATE -e end=DATE -D daily -W weekly -M monthly -Q quarterly -Y yearly -p period=PERIODEXP date2 aux-date -C cleared pending -U uncleared -R real depth=N -E empty -B cost -h help debug=N version

(for more detail, use help)

-h shows specific flags and general flags in brief, together, more compactly

$ hledger stats -h

stats [-o output-file=FILE[.FMT] -f file=FILE rules-file=RFILE alias=OLD=NEW ignore-assertions -b begin=DATE -e end=DATE -D daily -W weekly -M monthly -Q quarterly -Y yearly -p period=PERIODEXP date2 aux-date -C cleared pending -U uncleared -R real depth=N -E empty -B cost -h help debug=N version] [PATTERNS]

show some journal statistics

(for more detail, use help)

1.1

$ hledger hledger [COMMAND] … [OPTIONS] [ARGS]

Commands: help show any of the hledger manuals man show any of the hledger manuals with man info show any of the hledger manuals with info Data entry commands: add prompt for transactions and add them to the journal

Reporting commands: print show transaction entries accounts show account names balance show accounts and balances (bal) register show postings and running total (reg) incomestatement show an income statement (is) balancesheet show a balance sheet (bs) cashflow show a cashflow statement (cf) activity show an ascii barchart of posting counts per interval (default: daily) stats show some journal statistics

Add-on commands: api autosync budget chart generate simple balance pie charts check check-dates check dupes equity show a transaction entry zeroing all accounts estimatedtax iadd interest generate interest transaction entries invariant prices print-unique print only transactions with unique descriptions register-match rewrite add specified postings to matched transaction entries ui web start the web interface

General flags: -h show general usage or (after COMMAND, the command's usage help show the current program's manual as plain text (or after an add-on COMMAND, the add-on's manual) man show the current program's manual with man info show the current program's manual with info debug=[N] show debug output (levels 1-9, default: 1) version show version information

201703 ideas

wishes

short help that fits more easily on a single screen

avoid surprise due to difference between -h and -help

avoid unexpected/excessive output/scrolling

adapt to current terminal, pager, tools

use pager if available and supported by terminal and output is long
use man (or info) if available and supported by terminal

clear intuitive consistent maintainable UI without confusion/over-complexity

organise commands by topic, usefulness, maturity, location

use colour

commands list help section

a

Get help: -h show general short help CMD -h show command's short help help show manual info show manual with info man show manual with man help show any of the hledger manuals info show any of the hledger manuals with info man show any of the hledger manuals with man

b

Get help: (see also hledger -h, hledger CMD -h, hledger help|man|info) help show any of the hledger manuals info show any of the hledger manuals with info man show any of the hledger manuals with man

c

Get help: help|man|info show any of the hledger manuals in text/info/man format see also -h, CMD -h, help|man|info

d

Get help: (see also -h, CMD -h, help|man|info) help|man|info show any of the hledger manuals in text/info/man format

hledger (commands list)

Commands available:

Standard reports: accounts show chart of accounts balancesheet (bs) show a balance sheet cashflow (cf) show a cashflow statement incomestatement (is) show an income statement transactions (txns) show transactions in some account

General reporting: activity show a bar chart of posting counts per interval balance (bal) show accounts and balances budget add automated postings/txns/bucket accts (experimental) chart generate simple balance pie charts (experimental) check check more powerful balance assertions check-dates check transactions are ordered by date check-dupes check for accounts with the same leaf name estimatedtax calculate estimated tax amounts for some revenue irr calculate internal rate of return of an investment prices show market price records print show transaction journal entries print-unique show only transactions with unique descriptions register (reg) show postings and running total register-match show best matching transaction for a description stats show some journal statistics

Interfaces: add console ui for adding transactions api web api server iadd curses ui for adding transactions ui curses ui web web ui

Misc: autosync download/deduplicate/convert OFX data equity generate transactions to zero & restore account balances interest generate interest transactions rewrite add automated postings to certain transactions

Help: (see also -h, CMD -h, help|—man|info) help|man|info show any of the hledger manuals in text/man/info format

hledger -h (usage/short help)

hledger [CMD] [OPTS] [ARGS] hledger's command line interface

General input flags: -f file=FILE use a different input file. For stdin, use - rules-file=RFILE CSV conversion rules file (default: FILE.rules) alias=OLD=NEW rename accounts named OLD to NEW anon anonymize accounts and payees pivot=TAGNAME use some other field/tag for account names -I ignore-assertions ignore any balance assertions

General reporting flags: -b begin=DATE include postings/txns on or after this date -e end=DATE include postings/txns before this date -D daily multiperiod/multicolumn report by day -W weekly multiperiod/multicolumn report by week -M monthly multiperiod/multicolumn report by month -Q quarterly multiperiod/multicolumn report by quarter -Y yearly multiperiod/multicolumn report by year -p period=PERIODEXP set start date, end date, and/or report interval all at once (overrides the flags above) date2 show and match on secondary dates instead -C cleared include only cleared postings/txns pending include only pending postings/txns -U uncleared include only uncleared (and pending) postings/txns -R real include only non-virtual postings depth=N hide accounts/postings deeper than N -E empty show items with zero amount, normally hidden -B cost convert amounts to their cost at transaction time (using the transaction price, if any) -V value convert amounts to their market value on the report end date (using the most recent applicable market price, if any)

General flags: -h usage show general usage or (after COMMAND, the command's usage help show this program's manual (or after an add-on command, the add-on's manual) man show the manual with man info show the manual with info debug=[N] show debug output (levels 1-9, default: 1) version show version information

Examples:

hledger list commands
hledger CMD [] [OPTS] [ARGS] run a command. command-specific options must go after CMD, and if its an addon
hledger-CMD [OPTS] [ARGS] or run an addon command directly
hledger -h hledger usage
hledger CMD -h command usage
hledger help hledger manual
hledger man hledger manual as man page
hledger info hledger manual as info manual
hledger help list help topics
hledger help TOPIC TOPIC manual
hledger man TOPIC TOPIC manual as man page
hledger info TOPIC TOPIC manual as info manual

hledger print -h (command usage)

print [OPTS] [QUERYARGS] show transaction journal entries

Flags: -m match=STR show the transaction whose description is most similar to STR, and is most recent -x explicit show all amounts explicitly -O output-format=FMT select the output format. Supported formats: txt, csv. -o output-file=FILE write output to FILE. A file extension matching one of the above formats selects that format.

plus general flags, see "hledger -h" or "hledger print -hh".

hledger print -hh (command full usage)

print [OPTIONS] [QUERY] show transaction journal entries

Flags: -m match=STR show the transaction whose description is most similar to STR, and is most recent -x explicit show all amounts explicitly -O output-format=FMT select the output format. Supported formats: txt, csv. -o output-file=FILE write output to FILE. A file extension matching one of the above formats selects that format.

General input flags: -f file=FILE use a different input file. For stdin, use - rules-file=RFILE CSV conversion rules file (default: FILE.rules) alias=OLD=NEW rename accounts named OLD to NEW anon anonymize accounts and payees pivot=TAGNAME use some other field/tag for account names -I ignore-assertions ignore any balance assertions

General reporting flags: -b begin=DATE include postings/txns on or after this date -e end=DATE include postings/txns before this date -D daily multiperiod/multicolumn report by day -W weekly multiperiod/multicolumn report by week -M monthly multiperiod/multicolumn report by month -Q quarterly multiperiod/multicolumn report by quarter -Y yearly multiperiod/multicolumn report by year -p period=PERIODEXP set start date, end date, and/or report interval all at once (overrides the flags above) date2 show and match on secondary dates instead -C cleared include only cleared postings/txns pending include only pending postings/txns -U uncleared include only uncleared (and pending) postings/txns -R real include only non-virtual postings depth=N hide accounts/postings deeper than N -E empty show items with zero amount, normally hidden -B cost convert amounts to their cost at transaction time (using the transaction price, if any) -V value convert amounts to their market value on the report end date (using the most recent applicable market price, if any)

General flags: -h usage show general usage or (after COMMAND, the command's usage help show this program's manual (or after an add-on command, the add-on's manual) man show the current program's manual with man info show the current program's manual with info debug=[N] show debug output (levels 1-9, default: 1) version show version information

hledger help (manual/long help)

hledger(1) hledger User Manuals hledger(1)

NAME hledger - a command-line accounting tool

SYNOPSIS hledger [-f FILE] COMMAND [OPTIONS] [CMDARGS] hledger [-f FILE] ADDONCMD [OPTIONS] [CMDARGS]

DESCRIPTION hledger is a cross-platform program for tracking money, time, or any other commodity, using double-entry accounting and a simple, editable file format. hledger is inspired by and largely compatible with ….

201707 https://github.com/simonmichael/hledger/issues/579

principles

docs (usage, manuals, tutorials..) should be available reliably and instantly from the software you are running (without net or filesystem access and on windows too)

docs should by default be provided in the native UI of the tool you request them from

if you're using hledger, you'll see docs as plain text printed to the console (possibly with a pager).
if you're using hledger-ui, you'll see them as tui screens or dialogs.
if you're using hledger-web, you'll see them as built-in web content.
if you're using the web, you'll see them as web pages.

each tool should provide the full set of docs

within a tool, there should be one clear way to call up any particular doc

merge -h/help, emphasize help command, provide full docs in hledger-ui and hledger-web also

-h/help will be synonyms for short context-sensitive usage help (ideally one screenful)

hledger help will list/show all (8) manuals as plain text (or man pages or info manuals where supported)

hledger
hledger-ui
hledger-web
hledger-api
journal-format
csv-format
timeclock-format
timedot-format

hledger-ui will include all manuals as help screens (or call out to man/info)

hledger-web will include all manuals as web content

examples

``` hledger -h/help general usage hledger CMD -h/help command usage hledger help list manuals/topics hledger help [man|info] MANUAL/TOPIC show MANUAL/TOPIC as plain text[/man page/info manual] hledger-ui, hledger-web (manuals provided in-app) ```