Debian Codegraph @

Hledger/Cli/Commands/Run.txt

raw
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 ...