Hforecast
Documentation menu

Documentation

Examples

The examples/ directory holds runnable configs, from a one-liner to a config that exercises nearly every feature. Each is a good starting point to copy and adapt. Run any of them with -c:

hforecast -c examples/casual.yaml -o hforecast.journal

All amounts are illustrative — none of these are financial advice.

minimal.yaml

The smallest valid config: just an age. Everything else takes its default (a ~10-year horizon, default rates, no accounts). Useful for confirming the tool runs and seeing the baseline output.

hforecast -c examples/minimal.yaml

casual.yaml

A typical starter with no journal — balances and amounts typed in directly. A savings account and a brokerage account (using the synthetic tickers EQUITY and BOND to stand in for asset classes), a salary to 65, Social Security after 67, and a flat effectiveRate for taxes. This is the config most people should copy first.

hforecast -c examples/casual.yaml -o hforecast.journal
hledger -f hforecast.journal bal assets liabilities -Y --depth 2

power-user.yaml

Like casual.yaml, but demonstrates per-ticker growth overrides via symbols:. Holdings use real tickers (VTI, VXUS, TBOND), each with its own growth rate; a ticker you don’t list falls back to its asset-class default. The same symbols: block works when balances are inferred from a journal.

hforecast -c examples/power-user.yaml -o hforecast.journal

journal-user.yaml

Full journal integration. Balances are seeded with infer-from-journal, and income/expenses are derived from query: expressions — so it needs the companion journal via -f:

hforecast -c examples/journal-user.yaml -f examples/journal-user.journal -o hforecast.journal

See Journal inference for how inference resolves each value, and Tagging for the journal tags it reads.

full.yaml

A comprehensive config that exercises most of the surface area: multiple currencies and symbols, several account types (including a 401(k) and HSA), income with retirement contributions and a match, property-tied expenses, incomeRules, and a range of actions (a property purchase with a mortgage, transfers, one-off spends). It’s a reference for how features combine, more than a realistic single plan.

Over a ~65-year horizon at the default monthly granularity this takes tens of seconds; for a quick look, run it annually:

hforecast -c examples/full.yaml -g annual -o hforecast.journal

See Granularity for the trade-off.

defaults.yaml

Not a scenario to run for output, but a reference config: every top-level field with its default value, and commented examples of the optional sections (currencies, symbols, real estate, actions). Keep it open alongside Configuration when building out a config.

taxes/

Bundled tax bracket files (federal-2024.yaml, fica-2024.yaml, state-ny-2024.yaml, local-nyc-2024.yaml) plus the all-states dataset. Install them into your config directory with make install-taxes. See Taxes.

See also