hledger

https://hledger.org/
Admin
hledger is a fast, dependable, plain text accounting tool for tracking money, investments, and time...
Tokens:712,250
Snippets:5,878
Trust Score:9.6
Update:5 days ago
Show doc for...
Tokens:
Raw
### hledger setup command example

Source: https://hledger.org/manual.html

Run hledger setup to check the installation. The output lists checks for hledger, terminal, and journal configuration.

```shell
$ hledger setup
```

--------------------------------

### Install development tools and clone quickbench

Source: https://hledger.org/DEVWORKFLOWS.html

Installs shelltestrunner, ghcid, and hasktags via stack, then clones the quickbench repository and installs it from its source directory. The quickbench install must be run in the source directory.

```shell
stack install shelltestrunner ghcid hasktags
git clone https://github.com/simonmichael/quickbench; cd quickbench; stack install  # must run in source dir
```

--------------------------------

### Run hledger setup to check installation

Source: https://hledger.org/install.html

Run this command to verify your hledger installation. If it doesn't work, read the rest of the page for troubleshooting.

```bash
hledger setup
```

--------------------------------

### Start hledger-web with --serve-api

Source: https://hledger.org/1.52/hledger-web.html

Run hledger-web with the --serve-api flag to serve only the JSON API. The example uses a sample journal file.

```shell
$ hledger-web -f examples/sample.journal --serve-api
...
```

--------------------------------

### hledger setup

Source: https://hledger.org/1.52/hledger.html

Checks the hledger installation and prints a list of results with helpful hints. Makes one network request to detect the latest release version; uses ANSI color by default unless disabled by NO_COLOR or --color=n. Expects the hledger version to be installed in PATH.

```shell
$ hledger setup
Checking your hledger setup..
Legend: good, neutral, unknown, warning

hledger
* is a released version ?                   no  hledger 1.42.99-gbca4b39c5-20250425, mac-aarch64
* is up to date ?                          yes  1.42.99 installed, latest is 1.42.1
* is a native binary for this machine ?    yes  aarch64
* is installed in PATH ?                   yes  /Users/simon/.local/bin/hledger
* has a system text encoding configured ?  yes  UTF-8, data files should use this encoding
* has a user config file ? (optional)       no  
* current directory has a local config ?   yes  /Users/simon/src/hledger/hledger.conf
* the config file is readable ?            yes  /Users/simon/src/hledger/hledger.conf

terminal
* the NO_COLOR variable is defined ?        no  
* --color is configured by config file ?    no  
* hledger will use color by default ?      yes  
* the PAGER variable is defined ?          yes  less
* --pager is configured by config file ?    no  
* hledger will use a pager when needed ?   yes  /opt/homebrew/bin/less
* the LESS variable is defined ?           yes  
* the HLEDGER_LESS variable is defined ?    no  
* adjusting LESS variable for color etc. ? yes  
* --pretty is enabled by config file ?      no  tables will use ASCII characters
* bash shell completions are installed ?     ?  
* zsh shell completions are installed ?      ?  

journal
* the LEDGER_FILE variable is defined ?    yes  /Users/simon/finance/2025/2025.journal
* a default journal file is readable ?     yes  /Users/simon/finance/2025/2025.journal
* it includes additional files ?           yes  15
* all commodities are declared ?           yes  10
* all accounts are declared ?              yes  160
* all accounts have types ?                 no  14 untyped
* accounts of each type were detected ?    yes  ALERXCV
* commodities/accounts are checked ?        no  use -s to check commodities/accounts
* balance assertions are checked ?         yes  use -I to ignore assertions

```

--------------------------------

### hledger-web startup and request log

Source: https://hledger.org/web.html

Example output printed by hledger-web when it starts and receives requests. Shows the server URL, auto-exit behavior, and request log format.

```log
22/Mar/2020:17:34:19 -0700 [Info#yesod-core] Application launched @(yesod-core-1.6.17.2-1LbNd7zV6uz551mHDWJO3b:Yesod.Core.Dispatch src/Yesod/Core/Dispatch.hs:163:11)
Serving web UI and API on 127.0.0.1:5000 with base url http://127.0.0.1:5000
This server will exit after 2m with no browser windows open (or press ctrl-c)
Opening web browser...
127.0.0.1 - - [22/Mar/2020:17:34:21 -0700] "GET / HTTP/1.1" 303 0 "" "Mozilla/5.0 (Macintosh; Intel Mac OS X 10.15; rv:74.0) Gecko/20100101 Firefox/74.0"
127.0.0.1 - - [22/Mar/2020:17:34:21 -0700] "GET /journal HTTP/1.1" 200 - "" "Mozilla/5.0 (Macintosh; Intel Mac OS X 10.15; rv:74.0) Gecko/20100101 Firefox/74.0"
127.0.0.1 - - [22/Mar/2020:17:34:23 -0700] "GET /static/js/typeahead.bundle.min.js HTTP/1.1" 200 - "http://127.0.0.1:5000/journal" "Mozilla/5.0 (Macintosh; Intel Mac OS X 10.15; rv:74.0) Gecko/20100101 Firefox/74.0"
...
```

--------------------------------

### Example journal entry to add

Source: https://hledger.org/add.html

The journal entry used as the example in the walkthrough: a starting balance transaction dated 2025-07-01.

```plaintext
2025-07-01 starting balances
    assets:cash              $10
    equity:start            $-10

```

--------------------------------

### Render and serve new manuals snapshot

Source: https://hledger.org/RELEASING.html

On the site server, run `make build3-VER && make build` to render and serve the new manuals snapshot. Use `make caddy-reload` if the caddy config changed. Do not use `make all` as it re-renders every version.

```shell
make build3-VER && make build
```

```shell
make caddy-reload
```

--------------------------------

### hledger add examples

Source: https://hledger.org/manual.html

Examples of using the add command: basic invocation, specifying multiple files, and providing initial answers.

```shell
hledger add
```

```shell
hledger add --file 2024.journal --file 2023.journal
```

```shell
hledger add today 'best buy' expenses:supplies '$20'
```

--------------------------------

### hledger register with forecast and start date

Source: https://hledger.org/release-notes.html

Example of using the register command with --forecast and a start date. On a journal with only periodic transaction rules, forecast transactions now start from the specified date rather than today.

```shell
hledger reg --forecast -b 2020-01-01
```

--------------------------------

### Run bittytax_price to set up config

Source: https://hledger.org/prices.html

Initializes the config file by running the version command.

```bash
$ bittytax_price --version
```

--------------------------------

### Check hledger-web version

Source: https://hledger.org/web.html

Run in a terminal to verify hledger-web is installed and reasonably up to date. The output shows the version number; if this fails, see the Installing guide.

```bash
$ hledger-web --version
hledger-web 1.17.1
```

--------------------------------

### Starting balances transaction in hledger journal

Source: https://hledger.org/set-starting-balances.html

Add this transaction to your journal file to record a starting balance. Use today's date and the actual currency and amount. The example transfers $10 from equity:start to assets:cash.

```hledger
__
2025-07-01 starting balances
    assets:cash              $10
    equity:start            $-10

```

--------------------------------

### Run the example view command

Source: https://hledger.org/just.html

Runs the `view` command with a dummy argument and optional fzf arguments like `--black`.

```shell
$ just view -
$ just view - --black
```

--------------------------------

### Create temporary journal and start hledger-ui

Source: https://hledger.org/ui.html

Create an empty temporary journal file and launch hledger-ui with it to follow the tutorial without affecting existing data.

```shell
$ echo > tmp.journal
$ hledger-ui -f tmp.journal
```

--------------------------------

### Declare aliases at the start of the top-most file

Source: https://hledger.org/1.52/hledger.html

To affect all entries, declare aliases at the start of the top-most file. The example shows aliases affecting the entry and included files.

```hledger
alias foo=Foo
alias bar=Bar

2023-01-01  ; affected by aliases above
  foo  1
  bar

include c.journal  ; also affected
```

--------------------------------

### Example .args file and usage

Source: https://hledger.org/1.52/hledger.html

Shows a sample .args file (cash.args) and the command to use it with hledger bal. The file contains account patterns and a currency symbol with escaped dollar sign.

```plaintext
# cash.args

assets:cash
assets:charles schwab:sweep
cur:\$
-c=$1.

```

```bash
$ hledger bal @cash.args

```

--------------------------------

### Argument file example: cash.args

Source: https://hledger.org/hledger

Example of an argument file containing account patterns and a currency symbol. Lines starting with # are comments, and option values with spaces are allowed without quotes.

```plaintext
# cash.args

assets:cash
assets:charles schwab:sweep
cur:\$
-c=$1.

```

--------------------------------

### Run quickbench with default and custom options

Source: https://hledger.org/BENCHMARKS.html

Use `just bench` to time commands in bench/bench.sh with the hledger in PATH. The second command compares versions hledger-1.30, hledger-1.31, hledger-1.32 with best of 2 runs, twice. Executables must be in PATH.

```shell
$ just bench                    # time the commands in bench/bench.sh, with the hledger in PATH
```

```shell
$ just bench -f bench/bench10k.sh -w hledger-1.30,hledger-1.31,hledger-1.32 -n2 -N2   # compare versions, best of 2 runs, twice
```

--------------------------------

### hledger register with custom report interval

Source: https://hledger.org/release-notes.html

Example of using the register command with a custom report interval starting on the 15th day of each month. This makes the date column wide enough to show start and end dates.

```shell
hledger reg -p "every 15th day of month"
```

--------------------------------

### Build and install hledger with stack

Source: https://hledger.org/install.html

Build and install hledger from source using stack.

```bash
stack update; stack install
```

--------------------------------

### Smart date period examples

Source: https://hledger.org/1.52/hledger.html

Smart dates that represent the start of a period. Missing parts are inferred as 1 when needed.

```plaintext
2004-10
```

```plaintext
2004q3
```

```plaintext
q3
```

```plaintext
2004
```

```plaintext
10/1
```

```plaintext
oct
```

```plaintext
october
```

```plaintext
21
```

--------------------------------

### Specify report start date with -b or -p

Source: https://hledger.org/faq.html

Shows how to set a custom start date for reports using the -b flag or a period expression. The example uses 'hledger is -Y -b 2020/4/15' and 'hledger is -p 'yearly from 2020/4/15''.

```shell
hledger is -Y -b 2020/4/15

```

```shell
hledger is -p 'yearly from 2020/4/15'

```

--------------------------------

### Sample timeclock queries

Source: https://hledger.org/1.52/hledger.html

Shows example hledger commands for querying a sample timeclock file.

```shell
$ hledger -f sample.timeclock balance                               # current time balances
$ hledger -f sample.timeclock register -p 2009/3                    # sessions in march 2009
$ hledger -f sample.timeclock register -p weekly --depth 1 --empty  # time summary by week
```

--------------------------------

### Start hledger-ui with @simple.args and assets

Source: https://hledger.org/save-frequently-used-options.html

Command to launch hledger-ui in watch mode with the argument file and an 'assets' query, showing simplified asset accounts.

```bash
$ hledger-ui --watch @simple.args assets

```

--------------------------------

### Opening balances journal entry

Source: https://hledger.org/gain.html

Journal entry showing opening balances with $100 cash and equity. Use this as the starting point for the gain calculation example.

```hledger
__
2021-01-04 opening balances
    assets:cash                      $100.00
    equity:opening/closing balances

```

--------------------------------

### Start hledger web UI

Source: https://hledger.org/5-minute-quick-start.html

Use `hledger-web` to start the web UI for hledger.

```bash
$ hledger-web    # start the web UI

```

--------------------------------

### hledger-edit: edit queried transactions

Source: https://hledger.org/scripts.html

The hledger-utils python package provides a hledger-edit command to edit the queried transactions in your $EDITOR no matter what file they reside in. Install or upgrade with pip. The first example opens your editor with only costs in Florida (if named and tagged like that). The second example automates changes by setting $EDITOR to a script.

```shell
$ pip install -U hledger-utils    # might be slightly different on your system
```

```shell
# Opens your $EDITOR or $VISUAL with only costs in Florida 
# (if you named and tagged them like that)
# edit the transactions, save and exit your editor, 
# then the changes are distributed to the original files
$ hledger edit Cost tag:location=Florida
```

```shell
# Automate changes by setting `$EDITOR` to a script
# (here all food we had on that one day in Florida was Fast Food 🌭 and we initially forgot to write that) 
EDITOR='perl -pi -e "s|Cost:Food|Cost:Food:Fast Food|g"' hledger edit tag:location=Florida date:2022-12-20
```

--------------------------------

### hledger add example: provide answers

Source: https://hledger.org/1.52/hledger.html

Provides answers for the first four prompts: date, description, account, and amount.

```bash
hledger add today 'best buy' expenses:supplies '$20'
```
Tokens:
Raw