Hforecast
Documentation menu

Documentation

Command-line reference

hforecast reads a YAML config, simulates it period by period, and writes an hledger journal. Every flag is optional; run with no arguments and it reads hforecast.yaml from the current directory and writes the journal to stdout.

hforecast [-f JOURNAL] [-c FILE] [-o FILE] [-g PERIOD] [-v] [--explain]

Options

Flag Argument Default Description
-f, --file JOURNAL (none) Journal file (hledger format) used to infer initial conditions — balances, prices, and queried income/expense amounts. Required whenever the config uses an infer-from-journal balance or a query field.
-c, --config FILE hforecast.yaml The YAML config describing the scenario.
-o, --output FILE - (stdout) Where to write the journal. - means stdout. Written incrementally as the simulation runs.
-g, --granularity PERIOD month Simulation step length: day, month, or annual. See Granularity.
-v, --verbose off Trace every step of the run to stderr. Composes with --explain.
--explain off Print a summary of the resolved plan (with provenance) to stderr before running.
-h, --help Show help text and exit.

Inputs and outputs

Hforecast always reads a config (-c, default hforecast.yaml) and writes a journal (-o, default stdout). A journal (-f) is an additional input, needed only when the config opts into inference:

  • a balance: infer-from-journal on an account, or
  • a query: on an income or expense.

Without any of those, -f is unnecessary — every number comes from the config. See Journal inference.

The output is a standard hledger journal. It is streamed to -o as the simulation runs, so a large plan starts producing output immediately. Because the journal goes to stdout by default and the --explain/--verbose panels go to stderr, you can pipe the journal cleanly while still watching the diagnostics:

hforecast --explain | hledger -f - bal assets

Diagnostics

Two independent stderr streams help you see what the tool decided:

  • --explain prints a scannable summary of the resolved plan before the run: flags, globals, taxes, accounts (with opening balances valued by asset class), income, expenses, real estate, and — with -f — what was inferred. Each value is tagged with its provenance:

    • (no tag) — set explicitly in your config
    • (global) — inherited from your globals block
    • (default) — a built-in fallback
    • (journal) — read from your -f journal
    • (inferred) — derived from a query

  • -v/--verbose additionally traces every step during the run.

They compose. Color is used only on a terminal; set NO_COLOR=1 to disable it. A common dry run is to explain the plan and discard the journal:

hforecast -f ~/.hledger.journal --explain >/dev/null

Exit status

hforecast exits 0 on success and non-zero on error (a malformed config, a missing -f journal for an inferred field, an unreadable file), printing the error to stderr. A run that ends early because the plan runs out of money is reported but is not itself an error.

See also