sigil-ledger

A Sigil library for reading, writing, and querying hledger journal files. Build financial automation tools that work with plain-text accounting.

Features

Journal parsing — read hledger journal files into structured records (transactions, postings, amounts, commodities, tags)
Journal writing — write and append transactions in valid hledger format
Multi-currency — full support for cost notation (@ and @@) and balance assertions
Deduplication — filter out already-imported transactions by reference ID tag
Report generation — run hledger CLI commands (balance, register, income statement) and parse output
Round-trip fidelity — parse and re-serialize journals without losing information

Usage

(import (ledger))

;; Parse a journal file
(define txns (read-journal "/path/to/finances.journal"))

;; Create a new transaction
(define txn (journal-transaction
              date: "2026-03-25"
              status: "*"
              description: "Coffee Shop"
              postings: (list
                (journal-posting
                  account: "expenses:food:coffee"
                  amount: (journal-amount quantity: 4.50 commodity: "EUR"))
                (journal-posting
                  account: "assets:wise:eur"))))

;; Append new transactions to journal
(append-transactions "/path/to/finances.journal" (list txn))

Reports via hledger CLI

(import (ledger report))

;; Run a balance report
(hledger-balance "/path/to/finances.journal" "assets" tree: #t)

;; Income statement for a period
(hledger-income-statement "/path/to/finances.journal" period: "2026-03")

Journal Format Support

Handles standard hledger journal syntax:

Dates, status flags (*, !), transaction codes
Payee/note separator (|)
Account names with amounts and commodities
Inline and line comments (;)
Tags in comments (tag:value)
Cost notation (@ PRICE and @@ TOTAL)
Balance assertions (= AMOUNT, == AMOUNT, =* AMOUNT)

Known Limitations

European number format — amounts using period as thousands separator and comma as decimal separator (e.g. 1.000,50 EUR) are not supported. Use US-style formatting (1,000.50 EUR) or omit thousands separators. This matches the most common hledger usage; full decimal-mark directive support may be added in a future release.

Dependencies

sigil-stdlib
sigil-json (for hledger JSON output parsing)

Requires hledger on PATH for report generation features.

Building

sigil deps install
sigil build
sigil test

License

BSD-3-Clause