diff --git a/hledger/hledger.1 b/hledger/hledger.1 index 68a9db5a6..efd73b41b 100644 --- a/hledger/hledger.1 +++ b/hledger/hledger.1 @@ -8349,6 +8349,49 @@ test \- run self tests .PP Next, these commands are described in detail. .SH Help commands +.SS commands +Show the hledger commands list. +.IP +.EX +Flags: + \-\-builtin show only builtin commands, not addons +.EE +.SS demo +Play demos of hledger usage in the terminal, if asciinema is installed. +.IP +.EX +Flags: + \-s \-\-speed=SPEED playback speed (1 is original speed, .5 is half, 2 + is double, etc (default: 2)) +.EE +.PP +Run this command with no argument to list the demos. +To play a demo, write its number or a prefix or substring of its title. +Tips: +.PP +Make your terminal window large enough to see the demo clearly. +.PP +Use the \-s/\-\-speed SPEED option to set your preferred playback speed, +eg \f[CR]\-s4\f[R] to play at 4x original speed or \f[CR]\-s.5\f[R] to +play at half speed. +The default speed is 2x. +.PP +Other asciinema options can be added following a double dash, eg +\f[CR]\-\- \-i.1\f[R] to limit pauses or \f[CR]\-\- \-h\f[R] to list +asciinema\[aq]s other options. +.PP +During playback, several keys are available: SPACE to pause/unpause, . +to step forward (while paused), CTRL\-c quit. +.PP +Examples: +.IP +.EX +$ hledger demo # list available demos +$ hledger demo 1 # play the first demo at default speed (2x) +$ hledger demo install \-s4 # play the \[dq]install\[dq] demo at 4x speed +.EE +.PP +This command is experimental: there aren\[aq]t many useful demos yet. .SS help Show the hledger user manual with \f[CR]info\f[R], \f[CR]man\f[R], or a pager. @@ -8396,43 +8439,190 @@ $ hledger help # show the manual with info, man or $PAGER $ hledger help \[aq]time periods\[aq] # show the manual\[aq]s \[dq]Time periods\[dq] topic $ hledger help \[aq]time periods\[aq] \-m # use man, even if info is installed .EE -.SS demo -Play demos of hledger usage in the terminal, if asciinema is installed. +.SH User interface commands +.SS repl +Start an interactive prompt, where you can run any of hledger\[aq]s +commands. +Data files are parsed just once, so the commands run faster. .IP .EX Flags: - \-s \-\-speed=SPEED playback speed (1 is original speed, .5 is half, 2 - is double, etc (default: 2)) +no command\-specific flags .EE .PP -Run this command with no argument to list the demos. -To play a demo, write its number or a prefix or substring of its title. -Tips: +This command is experimental and could change in the future. .PP -Make your terminal window large enough to see the demo clearly. +\f[CR]hledger repl\f[R] starts a read\-eval\-print loop (REPL) where you +can enter commands interactively. +As with the \f[CR]run\f[R] command, each input file (or each input +file/input options combination) is parsed just once, so commands will +run more quickly than if you ran them individually at the command line. .PP -Use the \-s/\-\-speed SPEED option to set your preferred playback speed, -eg \f[CR]\-s4\f[R] to play at 4x original speed or \f[CR]\-s.5\f[R] to -play at half speed. -The default speed is 2x. +Also like \f[CR]run\f[R], the input file(s) specified for the +\f[CR]repl\f[R] command will be the default input for all interactive +commands, you can override this temporarily by specifying an +\f[CR]\-f\f[R] option in particular commands, and commands will not see +any changes made to input files (eg by \f[CR]add\f[R]) until you exit +and restart the REPL. .PP -Other asciinema options can be added following a double dash, eg -\f[CR]\-\- \-i.1\f[R] to limit pauses or \f[CR]\-\- \-h\f[R] to list -asciinema\[aq]s other options. +The command syntax is the same as with \f[CR]run\f[R]: +.IP \[bu] 2 +enter one hledger command at a time, without the usual +\f[CR]hledger\f[R] first word +.IP \[bu] 2 +empty lines and comment text from \f[CR]#\f[R] to end of line are +ignored +.IP \[bu] 2 +use single or double quotes to quote arguments when needed +.IP \[bu] 2 +type \f[CR]exit\f[R] or \f[CR]quit\f[R] or control\-D to exit the REPL. .PP -During playback, several keys are available: SPACE to pause/unpause, . -to step forward (while paused), CTRL\-c quit. +While it is running, the REPL remembers your command history, and you +can navigate in the usual ways: \- Keypad or Emacs navigation keys to +edit the current command line \- UP/DOWN or control\-P/control\-N to +step back/forward through history \- control\-R to search for a past +command, etc. .PP -Examples: +The \f[CR]commands\f[R] and \f[CR]help\f[R]\ commands, and the command +help flags (\f[CR]CMD \-\-tldr\f[R], \f[CR]CMD \-h/\-\-help\f[R], +\f[CR]CMD \-\-info\f[R], \f[CR]CMD \-\-man\f[R]), work in the usual way, +and can be useful. +.PP +You can type control\-C to cancel a long\-running command (but only +once; typing it a second time will exit the REPL). +.PP +And in most shells you can type control\-Z to exit temporarily to the +shell (and \f[CR]fg\f[R] to return to the REPL). +.SS Caveats +You may find some differences in behaviour between \f[CR]run\f[R] +command lines and normal hledger command lines. +For example, in the REPL, +.IP \[bu] 2 +the command name must be written first, options afterward +.IP \[bu] 2 +full command names or official abbreviations (as in the command list) +must be used +.IP \[bu] 2 +options parsing with addon commands might be less flexible than the CLI +.IP \[bu] 2 +the \f[CR]stats\f[R] command gives false timings, currently +.SS Examples +Start the REPL: .IP .EX -$ hledger demo # list available demos -$ hledger demo 1 # play the first demo at default speed (2x) -$ hledger demo install \-s4 # play the \[dq]install\[dq] demo at 4x speed +hledger repl .EE .PP -This command is experimental: there aren\[aq]t many useful demos yet. -.SH User interface commands +or +.IP +.EX +hledger repl \-f some.journal +.EE +.SS run +Run a sequence of hledger commands, provided as files or command line +arguments. +Data files are parsed just once, so the commands run faster. +.IP +.EX +Flags: +no command\-specific flags +.EE +.PP +This command is experimental and could change in the future. +.PP +You can use \f[CR]run\f[R] in three ways: +.IP \[bu] 2 +\f[CR]hledger run \-\- CMD1 \-\- CMD2 \-\- CMD3\f[R] \- read commands +from the command line, separated by \f[CR]\-\-\f[R] +.IP \[bu] 2 +\f[CR]hledger run SCRIPTFILE1 SCRIPTFILE2\f[R] \- read commands from one +or more files +.IP \[bu] 2 +\f[CR]cat SCRIPTFILE1 | hledger run\f[R] \- read commands from standard +input. +.PP +\f[CR]run\f[R] first loads the input file(s) specified by +\f[CR]LEDGER_FILE\f[R] or by \f[CR]\-f\f[R] options, in the usual way. +Then it runs each command in turn, each using the same input data. +But if you want a particular command to use different input, you can +specify an \f[CR]\-f\f[R] option within that command. +This will override (not add to) the default input, just for that +command. +.PP +Each input file (more precisely, each combination of input file and +input options) is parsed only once. +This means that commands will not see any changes made to these files, +until the next run. +But the commands will run more quickly than if run individually +(typically about twice as fast). +.PP +Command scripts, whether in a file or written on the command line, have +a simple syntax: +.IP \[bu] 2 +each line may contain a single hledger command and its arguments, +without the usual \f[CR]hledger\f[R] first word +.IP \[bu] 2 +empty lines are ignored +.IP \[bu] 2 +text from \f[CR]#\f[R] to end of line is a comment, and ignored +.IP \[bu] 2 +you can use single or double quotes to quote arguments when needed, as +on the command line +.IP \[bu] 2 +these extra commands are available: \f[CR]echo TEXT\f[R] prints some +text, and \f[CR]exit\f[R] or \f[CR]quit\f[R] ends the run. +.PP +On unix systems you can use \f[CR]#!/usr/bin/env hledger run\f[R] in the +first line of a command file to make it a runnable script. +If that gives an error, use \f[CR]#!/usr/bin/env \-S hledger run\f[R]. +.PP +It\[aq]s ok to use the \f[CR]run\f[R] command recursively within a +command script. +.SS Caveats +You may find some differences in behaviour between \f[CR]run\f[R] +command lines and normal hledger command lines. +For example, with \f[CR]run\f[R], +.IP \[bu] 2 +the command name must be written first, options afterward +.IP \[bu] 2 +full command names or official abbreviations (as in the command list) +must be used +.SS Examples +Run commands specified on the command line: +.IP +.EX +hledger \-f some.journal run \-\- balance assets \-\-depth 2 \-\- balance liabilities \-f /some/other.journal \-\-depth 3 \-\-transpose \-\- stats +.EE +.PP +This would load \f[CR]some.journal\f[R], run +\f[CR]balance assets \-\-depth 2\f[R] on it, then run +\f[CR]balance liabilities \-\-depth 3 \-\-transpose\f[R] on +\f[CR]/some/other.journal\f[R], and finally run \f[CR]stats\f[R] on +\f[CR]some.journal\f[R] +.PP +Run commands from standard input: +.IP +.EX +(echo \[dq]files\[dq]; echo \[dq]stats\[dq]) | hledger \-f some.journal run +.EE +.PP +Provide commands as a runnable script: +.IP +.EX +#!/usr/bin/env \-S hledger run \-f some.journal + +echo \[dq]List of accounts in some.journal\[dq] +accounts + +echo \[dq]Assets of some.journal\[dq] +balance assets \-\-depth 2 + +echo \[dq]Liabilities from /some/other.journal\[dq] +balance liabilities \-f /some/other.journal \-\-depth 3 \-\-transpose + +echo \[dq]Commands from another.script, applied to another.journal\[dq] +run \-f another.journal another.script +.EE .SS ui Runs hledger\-ui (if installed). .SS web diff --git a/hledger/hledger.info b/hledger/hledger.info index 32fc32b30..0853eb0c4 100644 --- a/hledger/hledger.info +++ b/hledger/hledger.info @@ -8064,13 +8064,60 @@ File: hledger.info, Node: Help commands, Next: User interface commands, Prev: * Menu: -* help:: +* commands:: * demo:: +* help::  -File: hledger.info, Node: help, Next: demo, Up: Help commands +File: hledger.info, Node: commands, Next: demo, Up: Help commands -24.1 help +24.1 commands +============= + +Show the hledger commands list. + +Flags: + --builtin show only builtin commands, not addons + + +File: hledger.info, Node: demo, Next: help, Prev: commands, Up: Help commands + +24.2 demo +========= + +Play demos of hledger usage in the terminal, if asciinema is installed. + +Flags: + -s --speed=SPEED playback speed (1 is original speed, .5 is half, 2 + is double, etc (default: 2)) + + Run this command with no argument to list the demos. To play a demo, +write its number or a prefix or substring of its title. Tips: + + Make your terminal window large enough to see the demo clearly. + + Use the -s/-speed SPEED option to set your preferred playback speed, +eg '-s4' to play at 4x original speed or '-s.5' to play at half speed. +The default speed is 2x. + + Other asciinema options can be added following a double dash, eg '-- +-i.1' to limit pauses or '-- -h' to list asciinema's other options. + + During playback, several keys are available: SPACE to pause/unpause, +. to step forward (while paused), CTRL-c quit. + + Examples: + +$ hledger demo # list available demos +$ hledger demo 1 # play the first demo at default speed (2x) +$ hledger demo install -s4 # play the "install" demo at 4x speed + + This command is experimental: there aren't many useful demos yet. + + +File: hledger.info, Node: help, Prev: demo, Up: Help commands + +24.3 help ========= Show the hledger user manual with 'info', 'man', or a pager. With a @@ -8109,41 +8156,6 @@ $ hledger help # show the manual with info, man or $PAGER $ hledger help 'time periods' # show the manual's "Time periods" topic $ hledger help 'time periods' -m # use man, even if info is installed - -File: hledger.info, Node: demo, Prev: help, Up: Help commands - -24.2 demo -========= - -Play demos of hledger usage in the terminal, if asciinema is installed. - -Flags: - -s --speed=SPEED playback speed (1 is original speed, .5 is half, 2 - is double, etc (default: 2)) - - Run this command with no argument to list the demos. To play a demo, -write its number or a prefix or substring of its title. Tips: - - Make your terminal window large enough to see the demo clearly. - - Use the -s/-speed SPEED option to set your preferred playback speed, -eg '-s4' to play at 4x original speed or '-s.5' to play at half speed. -The default speed is 2x. - - Other asciinema options can be added following a double dash, eg '-- --i.1' to limit pauses or '-- -h' to list asciinema's other options. - - During playback, several keys are available: SPACE to pause/unpause, -. to step forward (while paused), CTRL-c quit. - - Examples: - -$ hledger demo # list available demos -$ hledger demo 1 # play the first demo at default speed (2x) -$ hledger demo install -s4 # play the "install" demo at 4x speed - - This command is experimental: there aren't many useful demos yet. -  File: hledger.info, Node: User interface commands, Next: Data entry commands, Prev: Help commands, Up: Top @@ -8152,13 +8164,206 @@ File: hledger.info, Node: User interface commands, Next: Data entry commands, * Menu: +* repl:: +* run:: * ui:: * web::  -File: hledger.info, Node: ui, Next: web, Up: User interface commands +File: hledger.info, Node: repl, Next: run, Up: User interface commands -25.1 ui +25.1 repl +========= + +Start an interactive prompt, where you can run any of hledger's +commands. Data files are parsed just once, so the commands run faster. + +Flags: +no command-specific flags + + This command is experimental and could change in the future. + + 'hledger repl' starts a read-eval-print loop (REPL) where you can +enter commands interactively. As with the 'run' command, each input +file (or each input file/input options combination) is parsed just once, +so commands will run more quickly than if you ran them individually at +the command line. + + Also like 'run', the input file(s) specified for the 'repl' command +will be the default input for all interactive commands, you can override +this temporarily by specifying an '-f' option in particular commands, +and commands will not see any changes made to input files (eg by 'add') +until you exit and restart the REPL. + + The command syntax is the same as with 'run': + + * enter one hledger command at a time, without the usual 'hledger' + first word + * empty lines and comment text from '#' to end of line are ignored + * use single or double quotes to quote arguments when needed + * type 'exit' or 'quit' or control-D to exit the REPL. + + While it is running, the REPL remembers your command history, and you +can navigate in the usual ways: - Keypad or Emacs navigation keys to +edit the current command line - UP/DOWN or control-P/control-N to step +back/forward through history - control-R to search for a past command, +etc. + + The 'commands' and 'help' commands, and the command help flags ('CMD +--tldr', 'CMD -h/--help', 'CMD --info', 'CMD --man'), work in the usual +way, and can be useful. + + You can type control-C to cancel a long-running command (but only +once; typing it a second time will exit the REPL). + + And in most shells you can type control-Z to exit temporarily to the +shell (and 'fg' to return to the REPL). + +* Menu: + +* Caveats:: +* Examples:: + + +File: hledger.info, Node: Caveats, Next: Examples, Up: repl + +25.1.1 Caveats +-------------- + +You may find some differences in behaviour between 'run' command lines +and normal hledger command lines. For example, in the REPL, + + * the command name must be written first, options afterward + * full command names or official abbreviations (as in the command + list) must be used + * options parsing with addon commands might be less flexible than the + CLI + * the 'stats' command gives false timings, currently + + +File: hledger.info, Node: Examples, Prev: Caveats, Up: repl + +25.1.2 Examples +--------------- + +Start the REPL: + +hledger repl + + or + +hledger repl -f some.journal + + +File: hledger.info, Node: run, Next: ui, Prev: repl, Up: User interface commands + +25.2 run +======== + +Run a sequence of hledger commands, provided as files or command line +arguments. Data files are parsed just once, so the commands run faster. + +Flags: +no command-specific flags + + This command is experimental and could change in the future. + + You can use 'run' in three ways: + + * 'hledger run -- CMD1 -- CMD2 -- CMD3' - read commands from the + command line, separated by '--' + * 'hledger run SCRIPTFILE1 SCRIPTFILE2' - read commands from one or + more files + * 'cat SCRIPTFILE1 | hledger run' - read commands from standard + input. + + 'run' first loads the input file(s) specified by 'LEDGER_FILE' or by +'-f' options, in the usual way. Then it runs each command in turn, each +using the same input data. But if you want a particular command to use +different input, you can specify an '-f' option within that command. +This will override (not add to) the default input, just for that +command. + + Each input file (more precisely, each combination of input file and +input options) is parsed only once. This means that commands will not +see any changes made to these files, until the next run. But the +commands will run more quickly than if run individually (typically about +twice as fast). + + Command scripts, whether in a file or written on the command line, +have a simple syntax: + + * each line may contain a single hledger command and its arguments, + without the usual 'hledger' first word + * empty lines are ignored + * text from '#' to end of line is a comment, and ignored + * you can use single or double quotes to quote arguments when needed, + as on the command line + * these extra commands are available: 'echo TEXT' prints some text, + and 'exit' or 'quit' ends the run. + + On unix systems you can use '#!/usr/bin/env hledger run' in the first +line of a command file to make it a runnable script. If that gives an +error, use '#!/usr/bin/env -S hledger run'. + + It's ok to use the 'run' command recursively within a command script. + +* Menu: + +* Caveats: Caveats 2. +* Examples: Examples 2. + + +File: hledger.info, Node: Caveats 2, Next: Examples 2, Up: run + +25.2.1 Caveats +-------------- + +You may find some differences in behaviour between 'run' command lines +and normal hledger command lines. For example, with 'run', + + * the command name must be written first, options afterward + * full command names or official abbreviations (as in the command + list) must be used + + +File: hledger.info, Node: Examples 2, Prev: Caveats 2, Up: run + +25.2.2 Examples +--------------- + +Run commands specified on the command line: + +hledger -f some.journal run -- balance assets --depth 2 -- balance liabilities -f /some/other.journal --depth 3 --transpose -- stats + + This would load 'some.journal', run 'balance assets --depth 2' on it, +then run 'balance liabilities --depth 3 --transpose' on +'/some/other.journal', and finally run 'stats' on 'some.journal' + + Run commands from standard input: + +(echo "files"; echo "stats") | hledger -f some.journal run + + Provide commands as a runnable script: + +#!/usr/bin/env -S hledger run -f some.journal + +echo "List of accounts in some.journal" +accounts + +echo "Assets of some.journal" +balance assets --depth 2 + +echo "Liabilities from /some/other.journal" +balance liabilities -f /some/other.journal --depth 3 --transpose + +echo "Commands from another.script, applied to another.journal" +run -f another.journal another.script + + +File: hledger.info, Node: ui, Next: web, Prev: run, Up: User interface commands + +25.3 ui ======= Runs hledger-ui (if installed). @@ -8166,7 +8371,7 @@ Runs hledger-ui (if installed).  File: hledger.info, Node: web, Prev: ui, Up: User interface commands -25.2 web +25.4 web ======== Runs hledger-web (if installed). @@ -12642,121 +12847,128 @@ Node: Interaction of valuation and queries283814 Node: Effect of valuation on reports284531 Node: PART 4 COMMANDS292429 Node: Help commands294645 -Node: help294818 -Node: demo296523 -Node: User interface commands297740 -Node: ui297934 -Node: web298059 -Node: Data entry commands298187 -Node: add298385 -Node: import300840 -Node: Import preview301874 -Node: Overlap detection302822 -Node: First import305708 -Node: Importing balance assignments306903 -Node: Import and commodity styles307958 -Node: Import special cases308396 -Node: Basic report commands309731 -Node: accounts310032 -Node: codes312905 -Node: commodities313927 -Node: descriptions314171 -Node: files314638 -Node: notes314935 -Node: payees315447 -Node: prices316231 -Node: stats317123 -Node: tags318864 -Node: Standard report commands320171 -Node: print320476 -Node: print explicitness323217 -Node: print amount style324137 -Node: print parseability325375 -Node: print other features326294 -Node: print output format327157 -Node: aregister330442 -Node: aregister and posting dates334901 -Node: register335802 -Node: Custom register output342977 -Node: balancesheet344162 -Node: balancesheetequity348932 -Node: cashflow354072 -Node: incomestatement358634 -Node: Advanced report commands363232 -Node: balance363440 -Node: balance features368616 -Node: Simple balance report370692 -Node: Balance report line format372502 -Node: Filtered balance report374862 -Node: List or tree mode375381 -Node: Depth limiting376894 -Node: Dropping top-level accounts377661 -Node: Showing declared accounts378171 -Node: Sorting by amount378901 -Node: Percentages379738 -Node: Multi-period balance report380445 -Node: Balance change end balance383197 -Node: Balance report types384834 -Node: Calculation type385513 -Node: Accumulation type386217 -Node: Valuation type387318 -Node: Combining balance report types388507 -Node: Budget report390539 -Node: Using the budget report392844 -Node: Budget date surprises395120 -Node: Selecting budget goals396484 -Node: Budgeting vs forecasting397432 -Node: Balance report layout399109 -Node: Wide layout400314 -Node: Tall layout402719 -Node: Bare layout404025 -Node: Tidy layout406089 -Node: Balance report output407633 -Node: Some useful balance reports408448 -Node: roi409708 -Node: Spaces and special characters in --inv and --pnl411955 -Node: Semantics of --inv and --pnl412681 -Node: IRR and TWR explained414768 -Node: Chart commands418179 -Node: activity418360 -Node: Data generation commands418857 -Node: close419063 -Node: close --clopen421626 -Node: close --close423800 -Node: close --open424324 -Node: close --assert424574 -Node: close --assign424901 -Node: close --retain425580 -Node: close customisation426437 -Node: close and balance assertions428081 -Node: close examples429603 -Node: Retain earnings429840 -Node: Migrate balances to a new file430343 -Node: More detailed close examples431705 -Node: rewrite431927 -Node: Re-write rules in a file434499 -Node: Diff output format435809 -Node: rewrite vs print --auto437082 -Node: Maintenance commands437796 -Node: check438005 -Node: Basic checks439087 -Node: Strict checks440040 -Node: Other checks440915 -Node: Custom checks442770 -Node: diff443225 -Node: test444432 -Node: PART 5 COMMON TASKS445304 -Node: Getting help445537 -Node: Constructing command lines446446 -Node: Starting a journal file447284 -Node: Setting LEDGER_FILE448668 -Node: Setting opening balances449926 -Node: Recording transactions453248 -Node: Reconciling453973 -Node: Reporting456362 -Node: Migrating to a new file460476 -Node: BUGS460925 -Node: Troubleshooting461890 +Node: commands294831 +Node: demo295039 +Node: help296273 +Node: User interface commands297978 +Node: repl298189 +Node: Caveats300205 +Node: Examples300730 +Node: run300897 +Node: Caveats 2303044 +Node: Examples 2303433 +Node: ui304416 +Node: web304553 +Node: Data entry commands304681 +Node: add304879 +Node: import307334 +Node: Import preview308368 +Node: Overlap detection309316 +Node: First import312202 +Node: Importing balance assignments313397 +Node: Import and commodity styles314452 +Node: Import special cases314890 +Node: Basic report commands316225 +Node: accounts316526 +Node: codes319399 +Node: commodities320421 +Node: descriptions320665 +Node: files321132 +Node: notes321429 +Node: payees321941 +Node: prices322725 +Node: stats323617 +Node: tags325358 +Node: Standard report commands326665 +Node: print326970 +Node: print explicitness329711 +Node: print amount style330631 +Node: print parseability331869 +Node: print other features332788 +Node: print output format333651 +Node: aregister336936 +Node: aregister and posting dates341395 +Node: register342296 +Node: Custom register output349471 +Node: balancesheet350656 +Node: balancesheetequity355426 +Node: cashflow360566 +Node: incomestatement365128 +Node: Advanced report commands369726 +Node: balance369934 +Node: balance features375110 +Node: Simple balance report377186 +Node: Balance report line format378996 +Node: Filtered balance report381356 +Node: List or tree mode381875 +Node: Depth limiting383388 +Node: Dropping top-level accounts384155 +Node: Showing declared accounts384665 +Node: Sorting by amount385395 +Node: Percentages386232 +Node: Multi-period balance report386939 +Node: Balance change end balance389691 +Node: Balance report types391328 +Node: Calculation type392007 +Node: Accumulation type392711 +Node: Valuation type393812 +Node: Combining balance report types395001 +Node: Budget report397033 +Node: Using the budget report399338 +Node: Budget date surprises401614 +Node: Selecting budget goals402978 +Node: Budgeting vs forecasting403926 +Node: Balance report layout405603 +Node: Wide layout406808 +Node: Tall layout409213 +Node: Bare layout410519 +Node: Tidy layout412583 +Node: Balance report output414127 +Node: Some useful balance reports414942 +Node: roi416202 +Node: Spaces and special characters in --inv and --pnl418449 +Node: Semantics of --inv and --pnl419175 +Node: IRR and TWR explained421262 +Node: Chart commands424673 +Node: activity424854 +Node: Data generation commands425351 +Node: close425557 +Node: close --clopen428120 +Node: close --close430294 +Node: close --open430818 +Node: close --assert431068 +Node: close --assign431395 +Node: close --retain432074 +Node: close customisation432931 +Node: close and balance assertions434575 +Node: close examples436097 +Node: Retain earnings436334 +Node: Migrate balances to a new file436837 +Node: More detailed close examples438199 +Node: rewrite438421 +Node: Re-write rules in a file440993 +Node: Diff output format442303 +Node: rewrite vs print --auto443576 +Node: Maintenance commands444290 +Node: check444499 +Node: Basic checks445581 +Node: Strict checks446534 +Node: Other checks447409 +Node: Custom checks449264 +Node: diff449719 +Node: test450926 +Node: PART 5 COMMON TASKS451798 +Node: Getting help452031 +Node: Constructing command lines452940 +Node: Starting a journal file453778 +Node: Setting LEDGER_FILE455162 +Node: Setting opening balances456420 +Node: Recording transactions459742 +Node: Reconciling460467 +Node: Reporting462856 +Node: Migrating to a new file466970 +Node: BUGS467419 +Node: Troubleshooting468384  End Tag Table diff --git a/hledger/hledger.txt b/hledger/hledger.txt index faf0599a2..8a72cb886 100644 --- a/hledger/hledger.txt +++ b/hledger/hledger.txt @@ -6487,6 +6487,42 @@ PART 4: COMMANDS Next, these commands are described in detail. Help commands + commands + Show the hledger commands list. + + Flags: + --builtin show only builtin commands, not addons + + demo + Play demos of hledger usage in the terminal, if asciinema is installed. + + Flags: + -s --speed=SPEED playback speed (1 is original speed, .5 is half, 2 + is double, etc (default: 2)) + + Run this command with no argument to list the demos. To play a demo, + write its number or a prefix or substring of its title. Tips: + + Make your terminal window large enough to see the demo clearly. + + Use the -s/--speed SPEED option to set your preferred playback speed, + eg -s4 to play at 4x original speed or -s.5 to play at half speed. The + default speed is 2x. + + Other asciinema options can be added following a double dash, eg -- + -i.1 to limit pauses or -- -h to list asciinema's other options. + + During playback, several keys are available: SPACE to pause/unpause, . + to step forward (while paused), CTRL-c quit. + + Examples: + + $ hledger demo # list available demos + $ hledger demo 1 # play the first demo at default speed (2x) + $ hledger demo install -s4 # play the "install" demo at 4x speed + + This command is experimental: there aren't many useful demos yet. + help Show the hledger user manual with info, man, or a pager. With a (case insensitive) TOPIC argument, try to open it at that section heading. @@ -6523,37 +6559,170 @@ Help commands $ hledger help 'time periods' # show the manual's "Time periods" topic $ hledger help 'time periods' -m # use man, even if info is installed - demo - Play demos of hledger usage in the terminal, if asciinema is installed. +User interface commands + repl + Start an interactive prompt, where you can run any of hledger's com- + mands. Data files are parsed just once, so the commands run faster. Flags: - -s --speed=SPEED playback speed (1 is original speed, .5 is half, 2 - is double, etc (default: 2)) + no command-specific flags - Run this command with no argument to list the demos. To play a demo, - write its number or a prefix or substring of its title. Tips: + This command is experimental and could change in the future. - Make your terminal window large enough to see the demo clearly. + hledger repl starts a read-eval-print loop (REPL) where you can enter + commands interactively. As with the run command, each input file (or + each input file/input options combination) is parsed just once, so com- + mands will run more quickly than if you ran them individually at the + command line. - Use the -s/--speed SPEED option to set your preferred playback speed, - eg -s4 to play at 4x original speed or -s.5 to play at half speed. The - default speed is 2x. + Also like run, the input file(s) specified for the repl command will be + the default input for all interactive commands, you can override this + temporarily by specifying an -f option in particular commands, and com- + mands will not see any changes made to input files (eg by add) until + you exit and restart the REPL. - Other asciinema options can be added following a double dash, eg -- - -i.1 to limit pauses or -- -h to list asciinema's other options. + The command syntax is the same as with run: - During playback, several keys are available: SPACE to pause/unpause, . - to step forward (while paused), CTRL-c quit. + o enter one hledger command at a time, without the usual hledger first + word - Examples: + o empty lines and comment text from # to end of line are ignored - $ hledger demo # list available demos - $ hledger demo 1 # play the first demo at default speed (2x) - $ hledger demo install -s4 # play the "install" demo at 4x speed + o use single or double quotes to quote arguments when needed - This command is experimental: there aren't many useful demos yet. + o type exit or quit or control-D to exit the REPL. + + While it is running, the REPL remembers your command history, and you + can navigate in the usual ways: - Keypad or Emacs navigation keys to + edit the current command line - UP/DOWN or control-P/control-N to step + back/forward through history - control-R to search for a past command, + etc. + + The commands and help commands, and the command help flags (CMD --tldr, + CMD -h/--help, CMD --info, CMD --man), work in the usual way, and can + be useful. + + You can type control-C to cancel a long-running command (but only once; + typing it a second time will exit the REPL). + + And in most shells you can type control-Z to exit temporarily to the + shell (and fg to return to the REPL). + + Caveats + You may find some differences in behaviour between run command lines + and normal hledger command lines. For example, in the REPL, + + o the command name must be written first, options afterward + + o full command names or official abbreviations (as in the command list) + must be used + + o options parsing with addon commands might be less flexible than the + CLI + + o the stats command gives false timings, currently + + Examples + Start the REPL: + + hledger repl + + or + + hledger repl -f some.journal + + run + Run a sequence of hledger commands, provided as files or command line + arguments. Data files are parsed just once, so the commands run + faster. + + Flags: + no command-specific flags + + This command is experimental and could change in the future. + + You can use run in three ways: + + o hledger run -- CMD1 -- CMD2 -- CMD3 - read commands from the command + line, separated by -- + + o hledger run SCRIPTFILE1 SCRIPTFILE2 - read commands from one or more + files + + o cat SCRIPTFILE1 | hledger run - read commands from standard input. + + run first loads the input file(s) specified by LEDGER_FILE or by -f op- + tions, in the usual way. Then it runs each command in turn, each using + the same input data. But if you want a particular command to use dif- + ferent input, you can specify an -f option within that command. This + will override (not add to) the default input, just for that command. + + Each input file (more precisely, each combination of input file and in- + put options) is parsed only once. This means that commands will not + see any changes made to these files, until the next run. But the com- + mands will run more quickly than if run individually (typically about + twice as fast). + + Command scripts, whether in a file or written on the command line, have + a simple syntax: + + o each line may contain a single hledger command and its arguments, + without the usual hledger first word + + o empty lines are ignored + + o text from # to end of line is a comment, and ignored + + o you can use single or double quotes to quote arguments when needed, + as on the command line + + o these extra commands are available: echo TEXT prints some text, and + exit or quit ends the run. + + On unix systems you can use #!/usr/bin/env hledger run in the first + line of a command file to make it a runnable script. If that gives an + error, use #!/usr/bin/env -S hledger run. + + It's ok to use the run command recursively within a command script. + + Caveats + You may find some differences in behaviour between run command lines + and normal hledger command lines. For example, with run, + + o the command name must be written first, options afterward + + o full command names or official abbreviations (as in the command list) + must be used + + Examples + Run commands specified on the command line: + + hledger -f some.journal run -- balance assets --depth 2 -- balance liabilities -f /some/other.journal --depth 3 --transpose -- stats + + This would load some.journal, run balance assets --depth 2 on it, then + run balance liabilities --depth 3 --transpose on /some/other.journal, + and finally run stats on some.journal + + Run commands from standard input: + + (echo "files"; echo "stats") | hledger -f some.journal run + + Provide commands as a runnable script: + + #!/usr/bin/env -S hledger run -f some.journal + + echo "List of accounts in some.journal" + accounts + + echo "Assets of some.journal" + balance assets --depth 2 + + echo "Liabilities from /some/other.journal" + balance liabilities -f /some/other.journal --depth 3 --transpose + + echo "Commands from another.script, applied to another.journal" + run -f another.journal another.script -User interface commands ui Runs hledger-ui (if installed).