hledger-web 1.42.2 → 1.43
raw patch · 14 files changed
+290/−219 lines, 14 filesdep +file-embeddep −base-compatdep ~basedep ~hledgerdep ~hledger-lib
Dependencies added: file-embed
Dependencies removed: base-compat
Dependency ranges changed: base, hledger, hledger-lib
Files
- CHANGES.md +29/−0
- Hledger/Web/App.hs +2/−2
- Hledger/Web/Application.hs +2/−2
- Hledger/Web/Handler/MiscR.hs +14/−0
- Hledger/Web/Handler/RegisterR.hs +2/−3
- Hledger/Web/Main.hs +30/−18
- Hledger/Web/WebOptions.hs +33/−13
- LICENSE +4/−4
- config/routes +2/−0
- hledger-web.1 +28/−34
- hledger-web.cabal +17/−15
- hledger-web.info +34/−38
- hledger-web.txt +73/−76
- templates/default-layout.hamlet +20/−14
CHANGES.md view
@@ -22,6 +22,35 @@ See also the hledger changelog. +# 1.43 2025-06-01++Features++- Serve openapi.json, documenting the hledger-web HTTP API so that tools+ like open-webui and LLMs can query hledger-web for context.+ (Ben Sima)++Improvements++- The search help popup has been updated, and now shows the hledger-web version.++- The default "serve and browse" mode now has an explicit `--serve-browse` mode flag, for consistency.++- The old `--server` flag is now deprecated and hidden. Use `--serve` instead.++- CLI error messages now have consistent clean format independent of GHC version. [#2367]++- Fix capitalisation in Sandstorm app metadata.++- Support GHC 9.12.++- Drop base-compat dependency (Thomas Miedema)++Docs++- Fix outdated PERMISSIONS doc.++ # 1.42.2 2025-05-16 Fixes
Hledger/Web/App.hs view
@@ -269,8 +269,8 @@ checkServerSideUiEnabled :: Handler () checkServerSideUiEnabled = do- VD{opts=WebOpts{serve_api_}} <- getViewData- when serve_api_ $+ VD{opts=WebOpts{server_mode_}} <- getViewData+ when (server_mode_ == ServeJson) $ -- this one gives 500 internal server error when called from defaultLayout: -- permissionDenied "server-side UI is disabled due to --serve-api" sendResponseStatus status403 ("server-side UI is disabled due to --serve-api" :: Text)
Hledger/Web/Application.hs view
@@ -29,7 +29,7 @@ import Hledger.Web.Handler.JournalR import Hledger.Web.Handler.RegisterR import Hledger.Web.Import-import Hledger.Web.WebOptions (WebOpts(serve_,serve_api_), corsPolicy)+import Hledger.Web.WebOptions (ServerMode(..), WebOpts(server_mode_), corsPolicy) -- mkYesodDispatch creates our YesodDispatch instance. -- It complements the mkYesodData call in App.hs,@@ -47,7 +47,7 @@ (logWare . (corsPolicy opts')) <$> toWaiApp app where logWare | development = logStdoutDev- | serve_ opts' || serve_api_ opts' = logStdout+ | server_mode_ opts' `elem` [Serve, ServeJson] = logStdout | otherwise = id makeApp :: AppConfig DefaultEnv Extra -> WebOpts -> IO App
Hledger/Web/Handler/MiscR.hs view
@@ -19,10 +19,14 @@ , getManageR , getRobotsR , getRootR+ , getOpenApiR ) where import qualified Data.Map as M import qualified Data.Text as T+import qualified Data.Yaml as Yaml+import qualified Data.ByteString as BS+import Data.FileEmbed (embedFile) import Yesod.Default.Handlers (getFaviconR, getRobotsR) import Hledger@@ -107,3 +111,13 @@ styleAmounts (journalCommodityStylesWith HardRounding j) $ accountTransactionsReport rspec{_rsQuery=Any} j thisacctq +openApiYaml :: BS.ByteString+openApiYaml = $(embedFile "config/openapi.yaml")++getOpenApiR :: Handler Value+getOpenApiR =+ case Yaml.decodeEither' openApiYaml of+ Left _ -> notFound+ Right openapi -> do+ addHeader "Content-Type" "application/json"+ return openapi
Hledger/Web/Handler/RegisterR.hs view
@@ -9,9 +9,9 @@ module Hledger.Web.Handler.RegisterR where -import qualified Data.List.NonEmpty.Compat as NonEmpty -- from base-compat for ghc 8.10 import Data.List (intersperse, nub, partition) import qualified Data.Text as T+import Safe (tailSafe) import Text.Hamlet (hamletFile) import Hledger@@ -42,11 +42,10 @@ map (\(acct,(name,comma)) -> (acct, (T.pack name, T.pack comma))) . undecorateLinks . elideRightDecorated 40 . decorateLinks . addCommas . preferReal . otherTransactionAccounts q acctQuery- snoc xs x = NonEmpty.prependList xs $ NonEmpty.singleton x addCommas xs = zip xs $ zip (map (T.unpack . accountSummarisedName . paccount) xs) $- NonEmpty.tail $ snoc (", "<$xs) ""+ tailSafe (", "<$xs) ++ [""] items = styleAmounts (journalCommodityStylesWith HardRounding j) $ accountTransactionsReport rspec{_rsQuery=q} j acctQuery
Hledger/Web/Main.hs view
@@ -1,8 +1,20 @@ {-| hledger-web - a basic but robust web UI and JSON API server for hledger. -Copyright (c) 2007-2023 Simon Michael <simon@joyful.com> and contributors.-Released under GPL version 3 or later.+SPDX-License-Identifier: GPL-3.0-or-later+Copyright (c) 2007-2025 (each year in this range) Simon Michael <simon@joyful.com> and contributors.++This program is free software: you can redistribute it and/or modify+it under the terms of the GNU General Public License as published by+the Free Software Foundation, either version 3 of the License, or+(at your option) any later version.++This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY;+without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.+See the GNU General Public License for more details.+You should have received a copy of the GNU General Public License along with this program.+If not, see <https://www.gnu.org/licenses/>.+ -} {-# LANGUAGE CPP #-}@@ -25,7 +37,6 @@ import Network.Wai.Handler.Launch (runHostPortFullUrl) import System.Directory (removeFile) import System.Environment ( getArgs, withArgs )-import System.Exit (exitFailure) import System.IO (hFlush, stdout) import System.PosixCompat.Files (getFileStatus, isSocket) import Text.Printf (printf)@@ -50,7 +61,7 @@ -- Run normally. hledgerWebMain :: IO ()-hledgerWebMain = withGhcDebug' $ do+hledgerWebMain = exitOnError $ withGhcDebug' $ do when (ghcDebugMode == GDPauseAtStart) $ ghcDebugPause' #if MIN_VERSION_base(4,20,0)@@ -105,8 +116,9 @@ -- show configuration let- services | serve_api_ opts = "json API"- | otherwise = "web UI and json API"+ services+ | server_mode_ opts == ServeJson = "json API"+ | otherwise = "web UI and json API" prettyip ip | ip == "127.0.0.1" = ip ++ " (local access)" | ip == "0.0.0.0" = ip ++ " (all interfaces)"@@ -121,8 +133,15 @@ Nothing -> pure () -- start server and maybe browser- if serve_ opts || serve_api_ opts+ if server_mode_ opts == ServeBrowse then do+ putStrLn "This server will exit after 2m with no browser windows open (or press ctrl-c)"+ putStrLn "Opening web browser..."+ hFlush stdout+ -- exits after 2m of inactivity (hardcoded)+ Network.Wai.Handler.Launch.runHostPortFullUrl h p u app++ else do putStrLn "Press ctrl-c to quit" hFlush stdout let warpsettings = setHost (fromString h) (setPort p defaultSettings)@@ -142,17 +161,10 @@ when (isSocket sockstat) $ removeFile s ) (\sock -> Network.Wai.Handler.Warp.runSettingsSocket warpsettings sock app)- else do- putStrLn "Unix domain sockets are not available on your operating system"- putStrLn "Please try again without --socket"- exitFailure+ else error $ unlines+ ["Unix domain sockets are not available on your operating system."+ ,"Please try again without --socket."+ ] Nothing -> Network.Wai.Handler.Warp.runSettings warpsettings app-- else do- putStrLn "This server will exit after 2m with no browser windows open (or press ctrl-c)"- putStrLn "Opening web browser..."- hFlush stdout- -- exits after 2m of inactivity (hardcoded)- Network.Wai.Handler.Launch.runHostPortFullUrl h p u app
Hledger/Web/WebOptions.hs view
@@ -2,6 +2,7 @@ {-# LANGUAGE OverloadedStrings #-} {-# LANGUAGE TemplateHaskell #-} {-# LANGUAGE RecordWildCards #-}+{-# LANGUAGE LambdaCase #-} module Hledger.Web.WebOptions where @@ -22,10 +23,11 @@ import qualified Data.Text as T import Data.Char (toLower) import Data.List (isPrefixOf)+import Data.Either (fromRight) -- cf Hledger.Cli.Version -packageversion :: PackageVersion+packageversion :: PackageVersionString packageversion = #ifdef VERSION VERSION@@ -51,16 +53,23 @@ progname packageversion +binaryinfo :: HledgerBinaryInfo+binaryinfo = fromRight nullbinaryinfo $ parseHledgerVersion prognameandversion+ webflags :: [Flag RawOpts] webflags = [ flagNone- ["serve", "server"]+ ["serve-browse"]+ (setboolopt "serve-browse")+ (serveprefix ++ "serve the web UI and JSON API, and open a browser, and exit if inactive for 2m (default)")+ , flagNone+ ["serve"] (setboolopt "serve")- "serve and log requests, don't browse or auto-exit"+ (serveprefix ++ "just serve the web UI and JSON API") , flagNone ["serve-api"] (setboolopt "serve-api")- "like --serve, but serve only the JSON web API, not the web UI"+ (serveprefix ++ "just serve the JSON API") , flagReq ["allow"] (\s opts -> Right $ setopt "allow" s opts)@@ -85,7 +94,7 @@ ["socket"] (\s opts -> Right $ setopt "socket" s opts) "SOCKET"- "listen on the given unix socket instead of an IP address and port (unix only; implies --serve)"+ "listen on the given unix socket instead of an IP address and port (only on unix)" , flagReq ["base-url"] (\s opts -> Right $ setopt "base-url" s opts)@@ -102,6 +111,8 @@ (setboolopt "test") "run hledger-web's tests and exit. hspec test runner args may follow a --, eg: hledger-web --test -- --help" ]+ where+ serveprefix = "server mode: " webmode :: Mode RawOpts webmode =@@ -115,15 +126,18 @@ Group { groupUnnamed = webflags , groupHidden = hiddenflags+ +++ [flagNone ["server"] (setboolopt "serve") "old flag, use --serve instead"] , groupNamed = mkgeneralflagsgroups1 helpflags } , modeHelpSuffix = [] } +data ServerMode = ServeBrowse | Serve | ServeJson deriving (Show, Eq)+ -- hledger-web options, used in hledger-web and above data WebOpts = WebOpts- { serve_ :: !Bool- , serve_api_ :: !Bool+ { server_mode_ :: !ServerMode , cors_ :: !(Maybe String) , host_ :: !String , port_ :: !Int@@ -136,8 +150,7 @@ defwebopts :: WebOpts defwebopts = WebOpts- { serve_ = False- , serve_api_ = False+ { server_mode_ = ServeBrowse , cors_ = Nothing , host_ = "" , port_ = def@@ -172,10 +185,7 @@ Left err -> error' ("Unknown access level: " ++ err) -- PARTIAL: return defwebopts- { serve_ = case sock of- Just _ -> True- Nothing -> boolopt "serve" rawopts- , serve_api_ = boolopt "serve-api" rawopts+ { server_mode_ = servermodeopt rawopts , cors_ = maybestringopt "cors" rawopts , host_ = h , port_ = p@@ -187,6 +197,16 @@ } where stripTrailingSlash = reverse . dropWhile (== '/') . reverse -- yesod don't like it++servermodeopt :: RawOpts -> ServerMode+servermodeopt =+ fromMaybe ServeBrowse . choiceopt parse+ where+ parse = \case+ "serve-browse" -> Just ServeBrowse+ "serve" -> Just Serve+ "serve-api" -> Just ServeJson+ _ -> Nothing checkWebOpts :: WebOpts -> WebOpts checkWebOpts wopts@WebOpts{..}
LICENSE view
@@ -1,7 +1,7 @@ GNU GENERAL PUBLIC LICENSE Version 3, 29 June 2007 - Copyright (C) 2007 Free Software Foundation, Inc. <http://fsf.org/>+ Copyright (C) 2007 Free Software Foundation, Inc. <https://fsf.org/> Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed. @@ -645,7 +645,7 @@ GNU General Public License for more details. You should have received a copy of the GNU General Public License- along with this program. If not, see <http://www.gnu.org/licenses/>.+ along with this program. If not, see <https://www.gnu.org/licenses/>. Also add information on how to contact you by electronic and paper mail. @@ -664,11 +664,11 @@ You should also get your employer (if you work as a programmer) or school, if any, to sign a "copyright disclaimer" for the program, if necessary. For more information on this, and how to apply and follow the GNU GPL, see-<http://www.gnu.org/licenses/>.+<https://www.gnu.org/licenses/>. The GNU General Public License does not permit incorporating your program into proprietary programs. If your program is a subroutine library, you may consider it more useful to permit linking proprietary applications with the library. If this is what you want to do, use the GNU Lesser General Public License instead of this License. But first, please read-<http://www.gnu.org/philosophy/why-not-lgpl.html>.+<https://www.gnu.org/licenses/why-not-lgpl.html>.
config/routes view
@@ -2,6 +2,8 @@ /robots.txt RobotsR GET /static StaticR Static getStatic +/openapi.json OpenApiR GET+ / RootR GET /journal JournalR GET /register RegisterR GET
hledger-web.1 view
@@ -1,5 +1,5 @@ -.TH "HLEDGER\-WEB" "1" "May 2025" "hledger-web-1.42.2 " "hledger User Manuals"+.TH "HLEDGER\-WEB" "1" "May 2025" "hledger-web-1.43 " "hledger User Manuals" @@ -17,7 +17,7 @@ .PD \f[CR]hledger web \-\- [OPTS] [QUERY]\f[R] .SH DESCRIPTION-This manual is for hledger\[aq]s web interface, version 1.42.2.+This manual is for hledger\[aq]s web interface, version 1.43. See also the hledger manual for common concepts and file formats. .PP hledger is a robust, user\-friendly, cross\-platform set of programs for@@ -51,15 +51,14 @@ .PP hledger\-web can be run in three modes: .IP \[bu] 2-Transient mode (the default): your default web browser will be opened to-show the app if possible, and the app exits automatically after two-minutes of inactivity (no requests received and no open browser windows-viewing it).+\f[CR]\-\-serve\-browse\f[R] mode (the default): the app serves the web+UI and JSON API, and opens your default web browser to show the app if+possible, and exits automatically after two minutes of inactivity (with+no requests received and no open browser windows viewing it). .IP \[bu] 2-With \f[CR]\-\-serve\f[R]: the app runs without stopping, and without-opening a browser.+\f[CR]\-\-serve\f[R]: the app just serves the web UI and JSON API. .IP \[bu] 2-With \f[CR]\-\-serve\-api\f[R]: only the JSON API is served.+\f[CR]\-\-serve\-api\f[R]: the app just serves the JSON API. .PP In all cases hledger\-web runs as a foreground process, logging requests to stdout.@@ -221,38 +220,33 @@ 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. .PP-You can restrict who can reach it by+You can restrict who can reach it, by .IP \[bu] 2 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-machine.+By default it listens on 127.0.0.1, accessible to users on the local+machine only. .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-custom firewall rules+putting it behind a firewall .PP-You can restrict what the users who reach it can do, by-.IP \[bu] 2-using the \f[CR]\-\-capabilities=CAP[,CAP..]\f[R] flag when you start-it, enabling one or more of the following capabilities.-The default value is \f[CR]view,add\f[R]:-.RS 2+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-\f[CR]view\f[R] \- allows viewing the journal file and all included-files+\f[CR]view\f[R] \- allows viewing the journal file(s) .IP \[bu] 2-\f[CR]add\f[R] \- allows adding new transactions to the main journal-file+\f[CR]add\f[R] \- also allows adding new transactions to the main+journal file .IP \[bu] 2-\f[CR]manage\f[R] \- allows editing, uploading or downloading the main-or included files-.RE+\f[CR]edit\f[R] \- also allows editing, uploading or downloading the+journal file(s) .IP \[bu] 2-using the \f[CR]\-\-capabilities\-header=HTTPHEADER\f[R] flag to specify-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.+\f[CR]sandstorm\f[R] \- (for the hledger\-web Sandstorm app:) allows+whichever of \f[CR]view\f[R], \f[CR]add\f[R], or \f[CR]edit\f[R] are+specified in the \f[CR]X\-Sandstorm\-Permissions\f[R] HTTP header+.PP+The default access level is \f[CR]add\f[R]. .SH EDITING, UPLOADING, DOWNLOADING 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@@ -501,8 +495,8 @@ with \f[CR]\-f/\-\-file\f[R]. Default: \f[CR]$HOME/.hledger.journal\f[R]. .SH BUGS-We welcome bug reports in the hledger issue tracker (shortcut:-https://bugs.hledger.org), or on the hledger chat or mail list+We welcome bug reports in the hledger issue tracker+(https://bugs.hledger.org), or on the hledger chat or mail list (https://hledger.org/support). .PP Some known issues:
hledger-web.cabal view
@@ -1,11 +1,11 @@-cabal-version: 1.12+cabal-version: 2.2 -- This file has been generated from package.yaml by hpack version 0.38.0. -- -- see: https://github.com/sol/hpack name: hledger-web-version: 1.42.2+version: 1.43 synopsis: Web user interface for the hledger accounting system description: A simple web user interface for the hledger accounting system, providing a more modern UI than the command-line or terminal interfaces.@@ -24,11 +24,11 @@ bug-reports: http://bugs.hledger.org author: Simon Michael <simon@joyful.com> maintainer: Simon Michael <simon@joyful.com>-license: GPL-3+license: GPL-3.0-or-later license-file: LICENSE build-type: Simple tested-with:- GHC==8.10.7, GHC==9.0.2, GHC==9.2.8, GHC==9.4.5+ ghc==8.10.7, ghc==9.0.2, ghc==9.2.8, ghc==9.4.8, ghc==9.6.7, ghc==9.8.4, ghc==9.10.1 extra-source-files: CHANGES.md README.md@@ -153,15 +153,16 @@ Hledger.Web.Widget.AddForm Hledger.Web.Widget.Common Paths_hledger_web+ autogen-modules:+ Paths_hledger_web hs-source-dirs: ./ ghc-options: -Wall -Wredundant-constraints -Wincomplete-record-updates -Wincomplete-uni-patterns- cpp-options: -DVERSION="1.42.2"+ cpp-options: -DVERSION="1.43" build-depends: Decimal >=0.5.1 , aeson >=1 && <2.3- , base >=4.14 && <4.21- , base-compat >=0.14.0+ , base >=4.14 && <4.22 , base64 , blaze-html , blaze-markup@@ -175,11 +176,12 @@ , data-default , directory >=1.2.3.0 , extra >=1.7.11+ , file-embed >=0.0.16.0 , filepath , githash >=0.1.6.2 , hjsmin- , hledger >=1.42.2 && <1.43- , hledger-lib >=1.42.2 && <1.43+ , hledger ==1.43.*+ , hledger-lib ==1.43.* , hspec , http-client , http-conduit@@ -221,13 +223,14 @@ main-is: main.hs other-modules: Paths_hledger_web+ autogen-modules:+ Paths_hledger_web hs-source-dirs: app ghc-options: -Wall -Wredundant-constraints -Wincomplete-record-updates -Wincomplete-uni-patterns -with-rtsopts=-T- cpp-options: -DVERSION="1.42.2"+ cpp-options: -DVERSION="1.43" build-depends:- base >=4.14 && <4.21- , base-compat >=0.14.0+ base >=4.14 && <4.22 , hledger-web default-language: Haskell2010 if flag(threaded)@@ -247,10 +250,9 @@ hs-source-dirs: test ghc-options: -Wall -Wredundant-constraints -Wincomplete-record-updates -Wincomplete-uni-patterns- cpp-options: -DVERSION="1.42.2"+ cpp-options: -DVERSION="1.43" build-depends:- base >=4.14 && <4.21- , base-compat >=0.14.0+ base >=4.14 && <4.22 , hledger-web default-language: Haskell2010 if flag(threaded)
hledger-web.info view
@@ -18,7 +18,7 @@ or 'hledger web -- [OPTS] [QUERY]' - This manual is for hledger's web interface, version 1.42.2. See also+ This manual is for hledger's web interface, version 1.43. See also the hledger manual for common concepts and file formats. hledger is a robust, user-friendly, cross-platform set of programs@@ -47,15 +47,14 @@ hledger-web can be run in three modes: - * Transient mode (the default): your default web browser will be- opened to show the app if possible, and the app exits automatically- after two minutes of inactivity (no requests received and no open- browser windows viewing it).+ * '--serve-browse' mode (the default): the app serves the web UI and+ JSON API, and opens your default web browser to show the app if+ possible, and exits automatically after two minutes of inactivity+ (with no requests received and no open browser windows viewing it). - * With '--serve': the app runs without stopping, and without opening- a browser.+ * '--serve': the app just serves the web UI and JSON API. - * With '--serve-api': only the JSON API is served.+ * '--serve-api': the app just serves the JSON API. In all cases hledger-web runs as a foreground process, logging requests to stdout.@@ -230,30 +229,27 @@ 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. - 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- default it listens on 127.0.0.1, accessible to all users on the- local machine.- * putting it behind an authenticating proxy, using eg apache or nginx- * custom firewall rules+ default it listens on 127.0.0.1, accessible to users on the local+ machine only.+ * putting it behind an authenticating proxy, such as caddy or apache+ * 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,- enabling one or more of the following capabilities. The default- value is 'view,add':- * 'view' - allows viewing the journal file and all included- files- * 'add' - allows adding new transactions to the main journal- file- * 'manage' - allows editing, uploading or downloading the main- or included files+ * 'view' - allows viewing the journal file(s)+ * 'add' - also allows adding new transactions to the main journal+ file+ * 'edit' - also allows editing, uploading or downloading the journal+ file(s)+ * 'sandstorm' - (for the hledger-web Sandstorm app:) allows whichever+ of 'view', 'add', or 'edit' are specified in the+ 'X-Sandstorm-Permissions' HTTP header - * using the '--capabilities-header=HTTPHEADER' flag to specify 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's permissions. This is disabled by default.+ The default access level is 'add'. File: hledger-web.info, Node: EDITING UPLOADING DOWNLOADING, Next: RELOADING, Prev: PERMISSIONS, Up: Top@@ -518,8 +514,8 @@ 8 BUGS ****** -We welcome bug reports in the hledger issue tracker (shortcut:-https://bugs.hledger.org), or on the hledger chat or mail list+We welcome bug reports in the hledger issue tracker+(https://bugs.hledger.org), or on the hledger chat or mail list (https://hledger.org/support). Some known issues:@@ -529,15 +525,15 @@ Tag Table: Node: Top223-Node: OPTIONS2568-Node: PERMISSIONS11257-Node: EDITING UPLOADING DOWNLOADING12608-Node: RELOADING13623-Node: JSON API14190-Node: DEBUG OUTPUT19839-Node: Debug output19991-Node: ENVIRONMENT20509-Node: BUGS20745+Node: OPTIONS2578+Node: PERMISSIONS11267+Node: EDITING UPLOADING DOWNLOADING12417+Node: RELOADING13432+Node: JSON API13999+Node: DEBUG OUTPUT19648+Node: Debug output19800+Node: ENVIRONMENT20318+Node: BUGS20554 End Tag Table
hledger-web.txt view
@@ -11,44 +11,43 @@ hledger web -- [OPTS] [QUERY] DESCRIPTION- This manual is for hledger's web interface, version 1.42.2. See also- the hledger manual for common concepts and file formats.+ This manual is for hledger's web interface, version 1.43. See also the+ hledger manual for common concepts and file formats. - hledger is a robust, user-friendly, cross-platform set of programs for- tracking money, time, or any other commodity, using double-entry ac-- counting and a simple, editable file format. hledger is inspired by- and largely compatible with ledger(1), and largely interconvertible+ hledger is a robust, user-friendly, cross-platform set of programs for+ tracking money, time, or any other commodity, using double-entry ac-+ counting and a simple, editable file format. hledger is inspired by+ and largely compatible with ledger(1), and largely interconvertible with beancount(1). - hledger-web is a simple web application for browsing and adding trans-- actions. It provides a more user-friendly UI than the hledger CLI or- hledger-ui TUI, showing more at once (accounts, the current account+ hledger-web is a simple web application for browsing and adding trans-+ actions. It provides a more user-friendly UI than the hledger CLI or+ hledger-ui TUI, showing more at once (accounts, the current account register, balance charts) and allowing history-aware data entry, inter- active searching, and bookmarking. - hledger-web also lets you share a journal with multiple users, or even- the public web. There is no access control, so if you need that you- should put it behind a suitable web proxy. As a small protection- against data loss when running an unprotected instance, it writes a+ hledger-web also lets you share a journal with multiple users, or even+ the public web. There is no access control, so if you need that you+ should put it behind a suitable web proxy. As a small protection+ against data loss when running an unprotected instance, it writes a numbered backup of the main journal file (only) on every edit. - Like hledger, it reads from (and appends to) a journal file specified- by the LEDGER_FILE environment variable (defaulting to- $HOME/.hledger.journal); or you can specify files with -f options. It- can also read timeclock files, timedot files, or any CSV/SSV/TSV file+ Like hledger, it reads from (and appends to) a journal file specified+ by the LEDGER_FILE environment variable (defaulting to+ $HOME/.hledger.journal); or you can specify files with -f options. It+ can also read timeclock files, timedot files, or any CSV/SSV/TSV file with a date field. (See hledger(1) -> Input for details.) hledger-web can be run in three modes: - o Transient mode (the default): your default web browser will be opened- to show the app if possible, and the app exits automatically after- two minutes of inactivity (no requests received and no open browser- windows viewing it).+ o --serve-browse mode (the default): the app serves the web UI and JSON+ API, and opens your default web browser to show the app if possible,+ and exits automatically after two minutes of inactivity (with no re-+ quests received and no open browser windows viewing it). - o With --serve: the app runs without stopping, and without opening a- browser.+ o --serve: the app just serves the web UI and JSON API. - o With --serve-api: only the JSON API is served.+ o --serve-api: the app just serves the JSON API. In all cases hledger-web runs as a foreground process, logging requests to stdout.@@ -202,57 +201,55 @@ 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. - 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- it listens on 127.0.0.1, accessible to all users on the local ma-- chine.+ it listens on 127.0.0.1, accessible to users on the local machine+ 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- one or more of the following capabilities. The default value is- view,add:+ o view - allows viewing the journal file(s) - 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-- cluded files+ o sandstorm - (for the hledger-web Sandstorm app:) allows whichever of+ view, add, or edit are specified in the X-Sandstorm-Permissions HTTP+ header - o using the --capabilities-header=HTTPHEADER flag to specify 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's permissions. This is disabled by default.+ The default access level is add. EDITING, UPLOADING, DOWNLOADING- 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- let you edit, upload, or download the journal file or any files it in-+ 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+ let you edit, upload, or download the journal file or any files it in- 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. - Normally whenever a file is changed in this way, hledger-web saves a- numbered backup (assuming file permissions allow it, the disk is not- 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+ Normally whenever a file is changed in this way, hledger-web saves a+ numbered backup (assuming file permissions allow it, the disk is not+ 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 yourself (eg with a cron job or a file watcher like entr). - Changes which would leave the journal file(s) unparseable or non-valid- (eg with failing balance assertions) are prevented. (Probably. This+ Changes which would leave the journal file(s) unparseable or non-valid+ (eg with failing balance assertions) are prevented. (Probably. This needs re-testing.) RELOADING 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- data when you reload the page or navigate to a new page. If a change+ 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 makes a file unparseable, hledger-web will display an error message un- til the file has been fixed. @@ -260,8 +257,8 @@ that both machine clocks are roughly in step.) JSON API- 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+ 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 only, you can use the --serve-api flag. Eg: $ hledger-web -f examples/sample.journal --serve-api@@ -278,7 +275,7 @@ /accounttransactions/ACCOUNTNAME 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): $ curl -s http://127.0.0.1:5000/accountnames | python -m json.tool@@ -319,26 +316,26 @@ "aprice": null, ... - 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- on the various data types, eg Transaction. And for a higher level un-+ 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+ 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- ification. 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- at the source for the appropriate handler to see what it returns. Eg+ 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 for /accounttransactions it's getAccounttransactionsR, returning a "ac-- countTransactionsReport ...". Looking up the haddock for that we can- see that /accounttransactions returns an AccountTransactionsReport,- which consists of a report title and a list of AccountTransactionsRe-+ countTransactionsReport ...". Looking up the haddock for that we can+ see that /accounttransactions returns an AccountTransactionsReport,+ which consists of a report title and a list of AccountTransactionsRe- portItem (etc). - 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+ 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 default). The payload must be the full, exact JSON representation of a- hledger transaction (partial data won't do). You can get sample JSON- from hledger-web's /transactions or /accounttransactions, or you can+ hledger transaction (partial data won't do). You can get sample JSON+ from hledger-web's /transactions or /accounttransactions, or you can export it with hledger-lib, eg like so: .../hledger$ stack ghci hledger-lib@@ -434,28 +431,28 @@ "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: $ curl http://127.0.0.1:5000/add -X PUT -H 'Content-Type: application/json' --data-binary @txn.json 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-- cally you would start with 1 and increase until you are seeing enough.- Debug output goes to stderr, interleaved with the requests logged on+ cally you would start with 1 and increase until you are seeing enough.+ Debug output goes to stderr, interleaved with the requests logged on stdout. To capture debug output in a log file instead, you can usually redirect stderr, eg: hledger-web --debug=3 2>hledger-web.log. 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. BUGS- We welcome bug reports in the hledger issue tracker (shortcut:- https://bugs.hledger.org), or on the hledger chat or mail list+ We welcome bug reports in the hledger issue tracker+ (https://bugs.hledger.org), or on the hledger chat or mail list (https://hledger.org/support). Some known issues:@@ -480,4 +477,4 @@ SEE ALSO hledger(1), hledger-ui(1), hledger-web(1), ledger(1) -hledger-web-1.42.2 May 2025 HLEDGER-WEB(1)+hledger-web-1.43 May 2025 HLEDGER-WEB(1)
templates/default-layout.hamlet view
@@ -38,6 +38,7 @@ <div .modal-content> <div .modal-header> <button type="button" .close data-dismiss="modal" aria-hidden="true">×+ <span style="float:right; margin-right:4em;">#{progname} #{packageversion} <h3 .modal-title #helpLabel>Help <div .modal-body> <div .row>@@ -64,17 +65,22 @@ <p> <b>Search <ul>- <li> <code>acct:REGEXP</code> - filter on to/from account- <li> <code>desc:REGEXP</code> - filter on description- <li> <code>date:PERIODEXP</code>, <code>date2:PERIODEXP</code> - filter on date or secondary date- <li> <code>code:REGEXP</code> - filter on transaction's code (eg check number)- <li> <code>status:*</code>, <code>status:!</code>, <code>status:</code> - filter on transaction's cleared status (cleared, pending, uncleared)- <!-- <li> <code>empty:BOOL</code> - filter on whether amount is zero -->- <li> <code>amt:N</code>, <code>amt:<N</code>, <code>amt:>N</code> - filter on the unsigned amount magnitude. Or with a sign before N, filter on the signed value. (Single-commodity amounts only.)- <li> <code>cur:REGEXP</code> - filter on the currency/commodity symbol (must match all of it). Dollar sign must be written as <code>\$</code>- <li> <code>tag:NAME</code>, <code>tag:NAME=REGEX</code> - filter on tag name, or tag name and value- <!-- <li> <code>depth:N</code> - filter out accounts below this depth -->- <li> <code>real:BOOL</code> - filter on postings' real/virtual-ness- <li> Enclose search patterns containing spaces in single or double quotes- <li> Prepend <code>not:</code> to negate a search term- <li> Description, account, status query terms are OR'ed, others are AND'ed.+ <li> Search patterns with spaces should be enclosed in quotes.+ <li> <code>REGEX</code> - match account names+ <li> <code>type:TYPE</code> - match account types+ <li> <code>date:PERIODEXP</code> - match dates+ <li> <code>status:*</code>, <code>status:!</code>, <code>status:</code> - match status+ <li> <code>code:REGEX</code> - match transaction codes+ <li> <code>desc:REGEX</code> - match transaction descriptions+ <li> <code>payee:REGEX</code> - match payee part of descriptions+ <li> <code>note:REGEX</code> - match note part of descriptions+ <li> <code>amt:N</code>, <code>amt:<N</code>, <code>amt:>N</code> - match unsigned magnitudes, or with signed N, signed amounts. For single-commodity amounts only.+ <li> <code>cur:REGEX</code> - match currencies/commodities. Must match the whole symbol/name. To match dollar sign, write <code>\$</code>+ <li> <code>tag:NAME</code>, <code>tag:NAME=REGEX</code> - match tags, or tag and value+ <li> <code>real:BOOL</code> - match postings' realness/virtualness+ <li> <code>not:QTERM</code> - prepend not: to negate a search term+ <li> <code>expr:'QEXPR'</code> - match with a boolean query (and, or, not, (..))+ <li> <code>any:'QEXPR'</code> - match transactions where any posting matches+ <li> <code>all:'QEXPR'</code> - match transactions where all postings match+ <li style="margin-top:1em;"> <code>depth:N</code> - clip account names at this depth+ $# <li> Description, account, status query terms are OR'ed, others are AND'ed.