;doc: update embedded manuals

This commit is contained in:
Simon Michael 2025-06-04 07:31:18 -10:00
parent af9822a60a
commit 2899b46c59
13 changed files with 3317 additions and 2717 deletions

View File

@ -1,2 +1,2 @@
m4_dnl Date to show in man pages. Updated by "Shake manuals" m4_dnl Date to show in man pages. Updated by "Shake manuals"
m4_define({{_monthyear_}}, {{March 2025}})m4_dnl m4_define({{_monthyear_}}, {{June 2025}})m4_dnl

View File

@ -1,2 +1,2 @@
m4_dnl Date to show in man pages. Updated by "Shake manuals" m4_dnl Date to show in man pages. Updated by "Shake manuals"
m4_define({{_monthyear_}}, {{March 2025}})m4_dnl m4_define({{_monthyear_}}, {{June 2025}})m4_dnl

View File

@ -1,5 +1,5 @@
.TH "HLEDGER\-UI" "1" "March 2025" "hledger-ui-1.42.99 " "hledger User Manuals" .TH "HLEDGER\-UI" "1" "June 2025" "hledger-ui-1.43.99 " "hledger User Manuals"
@ -17,7 +17,7 @@ or
.PD .PD
\f[CR]hledger ui \-\- [OPTS] [QUERYARGS]\f[R] \f[CR]hledger ui \-\- [OPTS] [QUERYARGS]\f[R]
.SH DESCRIPTION .SH DESCRIPTION
This manual is for hledger\[aq]s terminal interface, version 1.42.99. This manual is for hledger\[aq]s terminal interface, version 1.43.99.
See also the hledger manual for common concepts and file formats. See also the hledger manual for common concepts and file formats.
.PP .PP
hledger is a robust, user\-friendly, cross\-platform set of programs for hledger is a robust, user\-friendly, cross\-platform set of programs for
@ -437,33 +437,51 @@ immediately without having to context switch.
This leaves more mental bandwidth for your accounting. This leaves more mental bandwidth for your accounting.
Of course you can still interact with hledger\-ui when needed, eg to Of course you can still interact with hledger\-ui when needed, eg to
toggle cleared mode, or to explore the history. toggle cleared mode, or to explore the history.
.PP .SS \-\-watch problems
There are currently some limitations with \f[CR]\-\-watch\f[R]: \f[I]However.\f[R] There are limitations/unresolved bugs with
.PP \f[CR]\-\-watch\f[R]:
It may not work correctly for you, depending on platform or system .IP \[bu] 2
It may not work at all for you, depending on platform or system
configuration. configuration.
(Eg #836.) On some unix systems, increasing fs.inotify.max_user_watches or
fs.file\-max parameters in /etc/sysctl.conf might help.
(#836)
.IP \[bu] 2
It may not detect file changes made by certain tools, such as Jetbrains
IDEs or gedit.
(#1617)
.IP \[bu] 2
It may not detect changes made from outside a virtual machine, ie by an
editor running on the host system.
.IP \[bu] 2
It may not detect file changes on certain less common filesystems.
.IP \[bu] 2
It may use increasing CPU and RAM over time, especially with large
files.
(This is probably not \-\-watch specific, you may be able to reproduce
it by pressing \f[CR]g\f[R] repeatedly.)
(#1825)
.PP .PP
At least on mac, there can be a slow build\-up of CPU usage over time, Tips/workarounds:
until the program is restarted (or, suspending and restarting with .IP \[bu] 2
\f[CR]CTRL\-z\f[R] \f[CR]fg\f[R] may be enough). If \-\-watch won\[aq]t work for you, press \f[CR]g\f[R] to reload data
.PP manually instead.
It will not detect file changes made by certain editors, such as .IP \[bu] 2
Jetbrains IDEs or \f[CR]gedit\f[R], or on certain less common If \-\-watch is leaking resources over time, quit and restart (or
filesystems. suspend and resume) hledger\-ui when you\[aq]re not using it.
(To work around, press \f[CR]g\f[R] to reload manually, or try .IP \[bu] 2
#1617\[aq]s \f[CR]fs.inotify.max_user_watches\f[R] workaround and let us When running hledger\-ui inside a VM, also make file changes inside the
know.) VM.
.PP .IP \[bu] 2
If you are viewing files mounted from another machine, the system clocks When working with files mounted from another machine, make sure the
on both machines should be roughly in agreement. system clocks on both machines are roughly in agreement.
.SH ENVIRONMENT .SH ENVIRONMENT
\f[B]LEDGER_FILE\f[R] The main journal file to use when not specified \f[B]LEDGER_FILE\f[R] The main journal file to use when not specified
with \f[CR]\-f/\-\-file\f[R]. with \f[CR]\-f/\-\-file\f[R].
Default: \f[CR]$HOME/.hledger.journal\f[R]. Default: \f[CR]$HOME/.hledger.journal\f[R].
.SH BUGS .SH BUGS
We welcome bug reports in the hledger issue tracker (shortcut: We welcome bug reports in the hledger issue tracker
https://bugs.hledger.org), or on the hledger chat or mail list (https://bugs.hledger.org), or on the hledger chat or mail list
(https://hledger.org/support). (https://hledger.org/support).
.PP .PP
Some known issues: Some known issues:
@ -471,14 +489,15 @@ Some known issues:
\f[CR]\-f\-\f[R] doesn\[aq]t work (hledger\-ui can\[aq]t read from \f[CR]\-f\-\f[R] doesn\[aq]t work (hledger\-ui can\[aq]t read from
stdin). stdin).
.PP .PP
\f[CR]\-\-watch\f[R] is not robust, especially with large files (see
WATCH MODE above).
.PP
The Transaction screen does not update after file changes, even if you
press \f[CR]g\f[R], until you exit and re\-enter it.
(#2288)
.PP
If you press \f[CR]g\f[R] with large files, there could be a noticeable If you press \f[CR]g\f[R] with large files, there could be a noticeable
pause. pause with the UI unresponsive.
.PP
The Transaction screen does not update from file changes until you exit
and re\-endter it (see SCREENS > Transaction above).
.PP
\f[CR]\-\-watch\f[R] is not yet fully robust on all platforms (see Watch
mode above).
.SH AUTHORS .SH AUTHORS

View File

@ -18,7 +18,7 @@ plain text accounting app.
or or
'hledger ui -- [OPTS] [QUERYARGS]' 'hledger ui -- [OPTS] [QUERYARGS]'
This manual is for hledger's terminal interface, version 1.42.99. This manual is for hledger's terminal interface, version 1.43.99.
See also the hledger manual for common concepts and file formats. See also the hledger manual for common concepts and file formats.
hledger is a robust, user-friendly, cross-platform set of programs hledger is a robust, user-friendly, cross-platform set of programs
@ -491,22 +491,41 @@ bandwidth for your accounting. Of course you can still interact with
hledger-ui when needed, eg to toggle cleared mode, or to explore the hledger-ui when needed, eg to toggle cleared mode, or to explore the
history. history.
There are currently some limitations with '--watch': * Menu:
It may not work correctly for you, depending on platform or system * --watch problems::
configuration. (Eg #836.)
At least on mac, there can be a slow build-up of CPU usage over time, 
until the program is restarted (or, suspending and restarting with File: hledger-ui.info, Node: --watch problems, Up: WATCH MODE
'CTRL-z' 'fg' may be enough).
It will not detect file changes made by certain editors, such as 5.1 -watch problems
Jetbrains IDEs or 'gedit', or on certain less common filesystems. (To ===================
work around, press 'g' to reload manually, or try #1617's
'fs.inotify.max_user_watches' workaround and let us know.)
If you are viewing files mounted from another machine, the system _However._ There are limitations/unresolved bugs with '--watch':
clocks on both machines should be roughly in agreement.
* It may not work at all for you, depending on platform or system
configuration. On some unix systems, increasing
fs.inotify.max_user_watches or fs.file-max parameters in
/etc/sysctl.conf might help. (#836)
* It may not detect file changes made by certain tools, such as
Jetbrains IDEs or gedit. (#1617)
* It may not detect changes made from outside a virtual machine, ie
by an editor running on the host system.
* It may not detect file changes on certain less common filesystems.
* It may use increasing CPU and RAM over time, especially with large
files. (This is probably not -watch specific, you may be able to
reproduce it by pressing 'g' repeatedly.) (#1825)
Tips/workarounds:
* If -watch won't work for you, press 'g' to reload data manually
instead.
* If -watch is leaking resources over time, quit and restart (or
suspend and resume) hledger-ui when you're not using it.
* When running hledger-ui inside a VM, also make file changes inside
the VM.
* When working with files mounted from another machine, make sure the
system clocks on both machines are roughly in agreement.
 
File: hledger-ui.info, Node: ENVIRONMENT, Next: BUGS, Prev: WATCH MODE, Up: Top File: hledger-ui.info, Node: ENVIRONMENT, Next: BUGS, Prev: WATCH MODE, Up: Top
@ -523,22 +542,23 @@ File: hledger-ui.info, Node: BUGS, Prev: ENVIRONMENT, Up: Top
7 BUGS 7 BUGS
****** ******
We welcome bug reports in the hledger issue tracker (shortcut: We welcome bug reports in the hledger issue tracker
https://bugs.hledger.org), or on the hledger chat or mail list (https://bugs.hledger.org), or on the hledger chat or mail list
(https://hledger.org/support). (https://hledger.org/support).
Some known issues: Some known issues:
'-f-' doesn't work (hledger-ui can't read from stdin). '-f-' doesn't work (hledger-ui can't read from stdin).
If you press 'g' with large files, there could be a noticeable pause. '--watch' is not robust, especially with large files (see WATCH MODE
The Transaction screen does not update from file changes until you
exit and re-endter it (see SCREENS > Transaction above).
'--watch' is not yet fully robust on all platforms (see Watch mode
above). above).
The Transaction screen does not update after file changes, even if
you press 'g', until you exit and re-enter it. (#2288)
If you press 'g' with large files, there could be a noticeable pause
with the UI unresponsive.
 
Tag Table: Tag Table:
Node: Top221 Node: Top221
@ -555,8 +575,9 @@ Node: Register screen16383
Node: Transaction screen18826 Node: Transaction screen18826
Node: Error screen20401 Node: Error screen20401
Node: WATCH MODE20767 Node: WATCH MODE20767
Node: ENVIRONMENT22343 Node: --watch problems21665
Node: BUGS22576 Node: ENVIRONMENT23018
Node: BUGS23251
 
End Tag Table End Tag Table

View File

@ -11,7 +11,7 @@ SYNOPSIS
hledger ui -- [OPTS] [QUERYARGS] hledger ui -- [OPTS] [QUERYARGS]
DESCRIPTION DESCRIPTION
This manual is for hledger's terminal interface, version 1.42.99. See This manual is for hledger's terminal interface, version 1.43.99. See
also the hledger manual for common concepts and file formats. also the hledger manual for common concepts and file formats.
hledger is a robust, user-friendly, cross-platform set of programs for hledger is a robust, user-friendly, cross-platform set of programs for
@ -394,44 +394,62 @@ WATCH MODE
hledger-ui when needed, eg to toggle cleared mode, or to explore the hledger-ui when needed, eg to toggle cleared mode, or to explore the
history. history.
There are currently some limitations with --watch: --watch problems
However. There are limitations/unresolved bugs with --watch:
It may not work correctly for you, depending on platform or system con- o It may not work at all for you, depending on platform or system con-
figuration. (Eg #836.) figuration. On some unix systems, increasing fs.ino-
tify.max_user_watches or fs.file-max parameters in /etc/sysctl.conf
might help. (#836)
At least on mac, there can be a slow build-up of CPU usage over time, o It may not detect file changes made by certain tools, such as Jet-
until the program is restarted (or, suspending and restarting with brains IDEs or gedit. (#1617)
CTRL-z fg may be enough).
It will not detect file changes made by certain editors, such as Jet- o It may not detect changes made from outside a virtual machine, ie by
brains IDEs or gedit, or on certain less common filesystems. (To work an editor running on the host system.
around, press g to reload manually, or try #1617's fs.ino-
tify.max_user_watches workaround and let us know.)
If you are viewing files mounted from another machine, the system o It may not detect file changes on certain less common filesystems.
clocks on both machines should be roughly in agreement.
o It may use increasing CPU and RAM over time, especially with large
files. (This is probably not --watch specific, you may be able to
reproduce it by pressing g repeatedly.) (#1825)
Tips/workarounds:
o If --watch won't work for you, press g to reload data manually in-
stead.
o If --watch is leaking resources over time, quit and restart (or sus-
pend and resume) hledger-ui when you're not using it.
o When running hledger-ui inside a VM, also make file changes inside
the VM.
o When working with files mounted from another machine, make sure the
system clocks on both machines are roughly in agreement.
ENVIRONMENT ENVIRONMENT
LEDGER_FILE The main journal file to use when not specified with LEDGER_FILE The main journal file to use when not specified with
-f/--file. Default: $HOME/.hledger.journal. -f/--file. Default: $HOME/.hledger.journal.
BUGS BUGS
We welcome bug reports in the hledger issue tracker (shortcut: We welcome bug reports in the hledger issue tracker
https://bugs.hledger.org), or on the hledger chat or mail list (https://bugs.hledger.org), or on the hledger chat or mail list
(https://hledger.org/support). (https://hledger.org/support).
Some known issues: Some known issues:
-f- doesn't work (hledger-ui can't read from stdin). -f- doesn't work (hledger-ui can't read from stdin).
If you press g with large files, there could be a noticeable pause. --watch is not robust, especially with large files (see WATCH MODE
The Transaction screen does not update from file changes until you exit
and re-endter it (see SCREENS > Transaction above).
--watch is not yet fully robust on all platforms (see Watch mode
above). above).
The Transaction screen does not update after file changes, even if you
press g, until you exit and re-enter it. (#2288)
If you press g with large files, there could be a noticeable pause with
the UI unresponsive.
AUTHORS AUTHORS
@ -450,4 +468,4 @@ LICENSE
SEE ALSO SEE ALSO
hledger(1), hledger-ui(1), hledger-web(1), ledger(1) hledger(1), hledger-ui(1), hledger-web(1), ledger(1)
hledger-ui-1.42.99 March 2025 HLEDGER-UI(1) hledger-ui-1.43.99 June 2025 HLEDGER-UI(1)

View File

@ -1,2 +1,2 @@
m4_dnl Date to show in man pages. Updated by "Shake manuals" m4_dnl Date to show in man pages. Updated by "Shake manuals"
m4_define({{_monthyear_}}, {{March 2025}})m4_dnl m4_define({{_monthyear_}}, {{June 2025}})m4_dnl

View File

@ -1,5 +1,5 @@
.TH "HLEDGER\-WEB" "1" "March 2025" "hledger-web-1.42.99 " "hledger User Manuals" .TH "HLEDGER\-WEB" "1" "June 2025" "hledger-web-1.43.99 " "hledger User Manuals"
@ -17,7 +17,7 @@ or
.PD .PD
\f[CR]hledger web \-\- [OPTS] [QUERY]\f[R] \f[CR]hledger web \-\- [OPTS] [QUERY]\f[R]
.SH DESCRIPTION .SH DESCRIPTION
This manual is for hledger\[aq]s web interface, version 1.42.99. This manual is for hledger\[aq]s web interface, version 1.43.99.
See also the hledger manual for common concepts and file formats. See also the hledger manual for common concepts and file formats.
.PP .PP
hledger is a robust, user\-friendly, cross\-platform set of programs for hledger is a robust, user\-friendly, cross\-platform set of programs for
@ -220,38 +220,33 @@ If this is not working see Install > Shell completions.
By default, hledger\-web allows anyone who can reach it to view the By default, hledger\-web allows anyone who can reach it to view the
journal and to add new transactions, but not to change existing data. journal and to add new transactions, but not to change existing data.
.PP .PP
You can restrict who can reach it by You can restrict who can reach it, by
.IP \[bu] 2 .IP \[bu] 2
setting the IP address it listens on (see \f[CR]\-\-host\f[R] above). setting the IP address it listens on (see \f[CR]\-\-host\f[R] above).
By default it listens on 127.0.0.1, accessible to all users on the local By default it listens on 127.0.0.1, accessible to users on the local
machine. machine only.
.IP \[bu] 2 .IP \[bu] 2
putting it behind an authenticating proxy, using eg apache or nginx putting it behind an authenticating proxy, such as caddy or apache
.IP \[bu] 2 .IP \[bu] 2
custom firewall rules putting it behind a firewall
.PP .PP
You can restrict what the users who reach it can do, by And you can restrict what the users reaching it can do, by specifying
the \f[CR]\-\-allow=ACCESSLEVEL\f[R] option at startup.
ACCESSLEVEL is one of:
.IP \[bu] 2 .IP \[bu] 2
using the \f[CR]\-\-capabilities=CAP[,CAP..]\f[R] flag when you start \f[CR]view\f[R] \- allows viewing the journal file(s)
it, enabling one or more of the following capabilities.
The default value is \f[CR]view,add\f[R]:
.RS 2
.IP \[bu] 2 .IP \[bu] 2
\f[CR]view\f[R] \- allows viewing the journal file and all included \f[CR]add\f[R] \- also allows adding new transactions to the main
files journal file
.IP \[bu] 2 .IP \[bu] 2
\f[CR]add\f[R] \- allows adding new transactions to the main journal \f[CR]edit\f[R] \- also allows editing, uploading or downloading the
file journal file(s)
.IP \[bu] 2 .IP \[bu] 2
\f[CR]manage\f[R] \- allows editing, uploading or downloading the main \f[CR]sandstorm\f[R] \- (for the hledger\-web Sandstorm app:) allows
or included files whichever of \f[CR]view\f[R], \f[CR]add\f[R], or \f[CR]edit\f[R] are
.RE specified in the \f[CR]X\-Sandstorm\-Permissions\f[R] HTTP header
.IP \[bu] 2 .PP
using the \f[CR]\-\-capabilities\-header=HTTPHEADER\f[R] flag to specify The default access level is \f[CR]add\f[R].
a HTTP header from which it will read capabilities to enable.
hledger\-web on Sandstorm uses the X\-Sandstorm\-Permissions header to
integrate with Sandstorm\[aq]s permissions.
This is disabled by default.
.SH EDITING, UPLOADING, DOWNLOADING .SH EDITING, UPLOADING, DOWNLOADING
If you enable the \f[CR]manage\f[R] capability mentioned above, If you enable the \f[CR]manage\f[R] capability mentioned above,
you\[aq]ll see a new \[dq]spanner\[dq] button to the right of the search you\[aq]ll see a new \[dq]spanner\[dq] button to the right of the search
@ -500,8 +495,8 @@ stderr, eg:
with \f[CR]\-f/\-\-file\f[R]. with \f[CR]\-f/\-\-file\f[R].
Default: \f[CR]$HOME/.hledger.journal\f[R]. Default: \f[CR]$HOME/.hledger.journal\f[R].
.SH BUGS .SH BUGS
We welcome bug reports in the hledger issue tracker (shortcut: We welcome bug reports in the hledger issue tracker
https://bugs.hledger.org), or on the hledger chat or mail list (https://bugs.hledger.org), or on the hledger chat or mail list
(https://hledger.org/support). (https://hledger.org/support).
.PP .PP
Some known issues: Some known issues:

View File

@ -18,7 +18,7 @@ plain text accounting app.
or or
'hledger web -- [OPTS] [QUERY]' 'hledger web -- [OPTS] [QUERY]'
This manual is for hledger's web interface, version 1.42.99. See This manual is for hledger's web interface, version 1.43.99. See
also the hledger manual for common concepts and file formats. also the hledger manual for common concepts and file formats.
hledger is a robust, user-friendly, cross-platform set of programs hledger is a robust, user-friendly, cross-platform set of programs
@ -229,30 +229,27 @@ File: hledger-web.info, Node: PERMISSIONS, Next: EDITING UPLOADING DOWNLOADING
By default, hledger-web allows anyone who can reach it to view the By default, hledger-web allows anyone who can reach it to view the
journal and to add new transactions, but not to change existing data. journal and to add new transactions, but not to change existing data.
You can restrict who can reach it by You can restrict who can reach it, by
* setting the IP address it listens on (see '--host' above). By * setting the IP address it listens on (see '--host' above). By
default it listens on 127.0.0.1, accessible to all users on the default it listens on 127.0.0.1, accessible to users on the local
local machine. machine only.
* putting it behind an authenticating proxy, using eg apache or nginx * putting it behind an authenticating proxy, such as caddy or apache
* custom firewall rules * putting it behind a firewall
You can restrict what the users who reach it can do, by And you can restrict what the users reaching it can do, by specifying
the '--allow=ACCESSLEVEL' option at startup. ACCESSLEVEL is one of:
* using the '--capabilities=CAP[,CAP..]' flag when you start it, * 'view' - allows viewing the journal file(s)
enabling one or more of the following capabilities. The default * 'add' - also allows adding new transactions to the main journal
value is 'view,add': file
* 'view' - allows viewing the journal file and all included * 'edit' - also allows editing, uploading or downloading the journal
files file(s)
* 'add' - allows adding new transactions to the main journal * 'sandstorm' - (for the hledger-web Sandstorm app:) allows whichever
file of 'view', 'add', or 'edit' are specified in the
* 'manage' - allows editing, uploading or downloading the main 'X-Sandstorm-Permissions' HTTP header
or included files
* using the '--capabilities-header=HTTPHEADER' flag to specify a HTTP The default access level is 'add'.
header from which it will read capabilities to enable. hledger-web
on Sandstorm uses the X-Sandstorm-Permissions header to integrate
with Sandstorm's permissions. This is disabled by default.
 
File: hledger-web.info, Node: EDITING UPLOADING DOWNLOADING, Next: RELOADING, Prev: PERMISSIONS, Up: Top File: hledger-web.info, Node: EDITING UPLOADING DOWNLOADING, Next: RELOADING, Prev: PERMISSIONS, Up: Top
@ -517,8 +514,8 @@ File: hledger-web.info, Node: BUGS, Prev: ENVIRONMENT, Up: Top
8 BUGS 8 BUGS
****** ******
We welcome bug reports in the hledger issue tracker (shortcut: We welcome bug reports in the hledger issue tracker
https://bugs.hledger.org), or on the hledger chat or mail list (https://bugs.hledger.org), or on the hledger chat or mail list
(https://hledger.org/support). (https://hledger.org/support).
Some known issues: Some known issues:
@ -530,13 +527,13 @@ Tag Table:
Node: Top223 Node: Top223
Node: OPTIONS2581 Node: OPTIONS2581
Node: PERMISSIONS11270 Node: PERMISSIONS11270
Node: EDITING UPLOADING DOWNLOADING12621 Node: EDITING UPLOADING DOWNLOADING12420
Node: RELOADING13636 Node: RELOADING13435
Node: JSON API14203 Node: JSON API14002
Node: DEBUG OUTPUT19852 Node: DEBUG OUTPUT19651
Node: Debug output20004 Node: Debug output19803
Node: ENVIRONMENT20522 Node: ENVIRONMENT20321
Node: BUGS20758 Node: BUGS20557
 
End Tag Table End Tag Table

View File

@ -11,7 +11,7 @@ SYNOPSIS
hledger web -- [OPTS] [QUERY] hledger web -- [OPTS] [QUERY]
DESCRIPTION DESCRIPTION
This manual is for hledger's web interface, version 1.42.99. See also This manual is for hledger's web interface, version 1.43.99. See also
the hledger manual for common concepts and file formats. the hledger manual for common concepts and file formats.
hledger is a robust, user-friendly, cross-platform set of programs for hledger is a robust, user-friendly, cross-platform set of programs for
@ -201,57 +201,55 @@ PERMISSIONS
By default, hledger-web allows anyone who can reach it to view the By default, hledger-web allows anyone who can reach it to view the
journal and to add new transactions, but not to change existing data. journal and to add new transactions, but not to change existing data.
You can restrict who can reach it by You can restrict who can reach it, by
o setting the IP address it listens on (see --host above). By default o setting the IP address it listens on (see --host above). By default
it listens on 127.0.0.1, accessible to all users on the local ma- it listens on 127.0.0.1, accessible to users on the local machine
chine. only.
o putting it behind an authenticating proxy, using eg apache or nginx o putting it behind an authenticating proxy, such as caddy or apache
o custom firewall rules o putting it behind a firewall
You can restrict what the users who reach it can do, by And you can restrict what the users reaching it can do, by specifying
the --allow=ACCESSLEVEL option at startup. ACCESSLEVEL is one of:
o using the --capabilities=CAP[,CAP..] flag when you start it, enabling o view - allows viewing the journal file(s)
one or more of the following capabilities. The default value is
view,add:
o view - allows viewing the journal file and all included files o add - also allows adding new transactions to the main journal file
o add - allows adding new transactions to the main journal file o edit - also allows editing, uploading or downloading the journal
file(s)
o manage - allows editing, uploading or downloading the main or in- o sandstorm - (for the hledger-web Sandstorm app:) allows whichever of
cluded files view, add, or edit are specified in the X-Sandstorm-Permissions HTTP
header
o using the --capabilities-header=HTTPHEADER flag to specify a HTTP The default access level is add.
header from which it will read capabilities to enable. hledger-web
on Sandstorm uses the X-Sandstorm-Permissions header to integrate
with Sandstorm's permissions. This is disabled by default.
EDITING, UPLOADING, DOWNLOADING EDITING, UPLOADING, DOWNLOADING
If you enable the manage capability mentioned above, you'll see a new If you enable the manage capability mentioned above, you'll see a new
"spanner" button to the right of the search form. Clicking this will "spanner" button to the right of the search form. Clicking this will
let you edit, upload, or download the journal file or any files it in- let you edit, upload, or download the journal file or any files it in-
cludes. cludes.
Note, unlike any other hledger command, in this mode you (or any visi- Note, unlike any other hledger command, in this mode you (or any visi-
tor) can alter or wipe the data files. tor) can alter or wipe the data files.
Normally whenever a file is changed in this way, hledger-web saves a Normally whenever a file is changed in this way, hledger-web saves a
numbered backup (assuming file permissions allow it, the disk is not numbered backup (assuming file permissions allow it, the disk is not
full, etc.) hledger-web is not aware of version control systems, cur- full, etc.) hledger-web is not aware of version control systems, cur-
rently; if you use one, you'll have to arrange to commit the changes rently; if you use one, you'll have to arrange to commit the changes
yourself (eg with a cron job or a file watcher like entr). yourself (eg with a cron job or a file watcher like entr).
Changes which would leave the journal file(s) unparseable or non-valid Changes which would leave the journal file(s) unparseable or non-valid
(eg with failing balance assertions) are prevented. (Probably. This (eg with failing balance assertions) are prevented. (Probably. This
needs re-testing.) needs re-testing.)
RELOADING RELOADING
hledger-web detects changes made to the files by other means (eg if you hledger-web detects changes made to the files by other means (eg if you
edit it directly, outside of hledger-web), and it will show the new edit it directly, outside of hledger-web), and it will show the new
data when you reload the page or navigate to a new page. If a change data when you reload the page or navigate to a new page. If a change
makes a file unparseable, hledger-web will display an error message un- makes a file unparseable, hledger-web will display an error message un-
til the file has been fixed. til the file has been fixed.
@ -259,8 +257,8 @@ RELOADING
that both machine clocks are roughly in step.) that both machine clocks are roughly in step.)
JSON API JSON API
In addition to the web UI, hledger-web also serves a JSON API that can In addition to the web UI, hledger-web also serves a JSON API that can
be used to get data or add new transactions. If you want the JSON API be used to get data or add new transactions. If you want the JSON API
only, you can use the --serve-api flag. Eg: only, you can use the --serve-api flag. Eg:
$ hledger-web -f examples/sample.journal --serve-api $ hledger-web -f examples/sample.journal --serve-api
@ -277,7 +275,7 @@ JSON API
/accounttransactions/ACCOUNTNAME /accounttransactions/ACCOUNTNAME
Eg, all account names in the journal (similar to the accounts command). Eg, all account names in the journal (similar to the accounts command).
(hledger-web's JSON does not include newlines, here we use python to (hledger-web's JSON does not include newlines, here we use python to
prettify it): prettify it):
$ curl -s http://127.0.0.1:5000/accountnames | python -m json.tool $ curl -s http://127.0.0.1:5000/accountnames | python -m json.tool
@ -318,26 +316,26 @@ JSON API
"aprice": null, "aprice": null,
... ...
Most of the JSON corresponds to hledger's data types; for details of Most of the JSON corresponds to hledger's data types; for details of
what the fields mean, see the Hledger.Data.Json haddock docs and click what the fields mean, see the Hledger.Data.Json haddock docs and click
on the various data types, eg Transaction. And for a higher level un- on the various data types, eg Transaction. And for a higher level un-
derstanding, see the journal docs. There is also a basic OpenAPI spec- derstanding, see the journal docs. There is also a basic OpenAPI spec-
ification. ification.
In some cases there is outer JSON corresponding to a "Report" type. To In some cases there is outer JSON corresponding to a "Report" type. To
understand that, go to the Hledger.Web.Handler.MiscR haddock and look understand that, go to the Hledger.Web.Handler.MiscR haddock and look
at the source for the appropriate handler to see what it returns. Eg at the source for the appropriate handler to see what it returns. Eg
for /accounttransactions it's getAccounttransactionsR, returning a "ac- for /accounttransactions it's getAccounttransactionsR, returning a "ac-
countTransactionsReport ...". Looking up the haddock for that we can countTransactionsReport ...". Looking up the haddock for that we can
see that /accounttransactions returns an AccountTransactionsReport, see that /accounttransactions returns an AccountTransactionsReport,
which consists of a report title and a list of AccountTransactionsRe- which consists of a report title and a list of AccountTransactionsRe-
portItem (etc). portItem (etc).
You can add a new transaction to the journal with a PUT request to You can add a new transaction to the journal with a PUT request to
/add, if hledger-web was started with the add capability (enabled by /add, if hledger-web was started with the add capability (enabled by
default). The payload must be the full, exact JSON representation of a default). The payload must be the full, exact JSON representation of a
hledger transaction (partial data won't do). You can get sample JSON hledger transaction (partial data won't do). You can get sample JSON
from hledger-web's /transactions or /accounttransactions, or you can from hledger-web's /transactions or /accounttransactions, or you can
export it with hledger-lib, eg like so: export it with hledger-lib, eg like so:
.../hledger$ stack ghci hledger-lib .../hledger$ stack ghci hledger-lib
@ -433,28 +431,28 @@ JSON API
"tstatus": "Unmarked" "tstatus": "Unmarked"
} }
And here's how to test adding it with curl. This should add a new en- And here's how to test adding it with curl. This should add a new en-
try to your journal: try to your journal:
$ curl http://127.0.0.1:5000/add -X PUT -H 'Content-Type: application/json' --data-binary @txn.json $ curl http://127.0.0.1:5000/add -X PUT -H 'Content-Type: application/json' --data-binary @txn.json
DEBUG OUTPUT DEBUG OUTPUT
Debug output Debug output
You can add --debug[=N] to the command line to log debug output. N You can add --debug[=N] to the command line to log debug output. N
ranges from 1 (least output, the default) to 9 (maximum output). Typi- ranges from 1 (least output, the default) to 9 (maximum output). Typi-
cally you would start with 1 and increase until you are seeing enough. cally you would start with 1 and increase until you are seeing enough.
Debug output goes to stderr, interleaved with the requests logged on Debug output goes to stderr, interleaved with the requests logged on
stdout. To capture debug output in a log file instead, you can usually stdout. To capture debug output in a log file instead, you can usually
redirect stderr, eg: redirect stderr, eg:
hledger-web --debug=3 2>hledger-web.log. hledger-web --debug=3 2>hledger-web.log.
ENVIRONMENT ENVIRONMENT
LEDGER_FILE The main journal file to use when not specified with LEDGER_FILE The main journal file to use when not specified with
-f/--file. Default: $HOME/.hledger.journal. -f/--file. Default: $HOME/.hledger.journal.
BUGS BUGS
We welcome bug reports in the hledger issue tracker (shortcut: We welcome bug reports in the hledger issue tracker
https://bugs.hledger.org), or on the hledger chat or mail list (https://bugs.hledger.org), or on the hledger chat or mail list
(https://hledger.org/support). (https://hledger.org/support).
Some known issues: Some known issues:
@ -479,4 +477,4 @@ LICENSE
SEE ALSO SEE ALSO
hledger(1), hledger-ui(1), hledger-web(1), ledger(1) hledger(1), hledger-ui(1), hledger-web(1), ledger(1)
hledger-web-1.42.99 March 2025 HLEDGER-WEB(1) hledger-web-1.43.99 June 2025 HLEDGER-WEB(1)

View File

@ -1,2 +1,2 @@
m4_dnl Date to show in man pages. Updated by "Shake manuals" m4_dnl Date to show in man pages. Updated by "Shake manuals"
m4_define({{_monthyear_}}, {{March 2025}})m4_dnl m4_define({{_monthyear_}}, {{June 2025}})m4_dnl

File diff suppressed because it is too large Load Diff

File diff suppressed because it is too large Load Diff

File diff suppressed because it is too large Load Diff