| 1 |
run |
| 2 |
|
| 3 |
Run a sequence of hledger commands, provided as files or command line |
| 4 |
arguments. Data files are parsed just once, so the commands run faster. |
| 5 |
|
| 6 |
Flags: |
| 7 |
no command-specific flags |
| 8 |
|
| 9 |
This command is experimental and could change in the future. |
| 10 |
|
| 11 |
You can use run in three ways: |
| 12 |
|
| 13 |
- hledger run -- CMD1 -- CMD2 -- CMD3 - read commands from the command |
| 14 |
line, separated by -- |
| 15 |
- hledger run SCRIPTFILE1 SCRIPTFILE2 - read commands from one or more |
| 16 |
files |
| 17 |
- cat SCRIPTFILE1 | hledger run - read commands from standard input. |
| 18 |
|
| 19 |
run first loads the input file(s) specified by LEDGER_FILE or by -f |
| 20 |
options, in the usual way. Then it runs each command in turn, each using |
| 21 |
the same input data. But if you want a particular command to use |
| 22 |
different input, you can specify an -f option within that command. This |
| 23 |
will override (not add to) the default input, just for that command. |
| 24 |
|
| 25 |
Each input file (more precisely, each combination of input file and |
| 26 |
input options) is parsed only once. This means that commands will not |
| 27 |
see any changes made to these files, until the next run. But the |
| 28 |
commands will run more quickly than if run individually (typically about |
| 29 |
twice as fast). |
| 30 |
|
| 31 |
Command scripts, whether in a file or written on the command line, have |
| 32 |
a simple syntax: |
| 33 |
|
| 34 |
- each line may contain a single hledger command and its arguments, |
| 35 |
without the usual hledger first word |
| 36 |
- empty lines are ignored |
| 37 |
- text from # to end of line is a comment, and ignored |
| 38 |
- you can use single or double quotes to quote arguments when needed, as |
| 39 |
on the command line |
| 40 |
- these extra commands are available: echo TEXT prints some text, and |
| 41 |
exit or quit ends the run. |
| 42 |
|
| 43 |
On unix systems you can use #!/usr/bin/env hledger run in the first line |
| 44 |
of a command file to make it a runnable script. If that gives an error, |
| 45 |
use #!/usr/bin/env -S hledger run. |
| 46 |
|
| 47 |
It's ok to use the run command recursively within a command script. |
| 48 |
|
| 49 |
You may find some differences in behaviour between run command lines and |
| 50 |
normal hledger command lines. run is a little stricter; eg it requires |
| 51 |
full command names or official abbreviations (as seen in the commands |
| 52 |
list), and command options must be written after the command name. |
| 53 |
|
| 54 |
Examples |
| 55 |
|
| 56 |
Run commands from the command line: |
| 57 |
|
| 58 |
hledger -f some.journal run -- balance assets --depth 2 -- balance liabilities -f /some/other.journal --depth 3 --transpose -- stats |
| 59 |
|
| 60 |
This would load some.journal, run balance assets --depth 2 on it, then |
| 61 |
run balance liabilities --depth 3 --transpose on /some/other.journal, |
| 62 |
and finally run stats on some.journal |
| 63 |
|
| 64 |
Run commands from standard input: |
| 65 |
|
| 66 |
(echo "files"; echo "stats") | hledger -f some.journal run |
| 67 |
|
| 68 |
Run commands as a script: |
| 69 |
|
| 70 |
$ cat report |
| 71 |
#!/usr/bin/env -S hledger run -f some.journal |
| 72 |
|
| 73 |
echo "List of accounts in some.journal" |
| 74 |
accounts |
| 75 |
|
| 76 |
echo "Assets of some.journal" |
| 77 |
balance assets --depth 2 |
| 78 |
|
| 79 |
echo "Liabilities from /some/other.journal" |
| 80 |
balance liabilities -f /some/other.journal --depth 3 --transpose |
| 81 |
|
| 82 |
echo "Commands from another.script, applied to another.journal" |
| 83 |
run -f another.journal another.script |
| 84 |
|
| 85 |
$ chmod +x report |
| 86 |
$ ./report |
| 87 |
List of accounts in some.journal |
| 88 |
... |