Skip to main content

Planning and Forecasts

Helius includes planning on top of recorded transactions. The main pieces are forecasts, scenarios, planning items, goals, budgets, and recurring rules.

Forecast Basics​

helius forecast show
helius forecast show --days 90 --json
helius forecast bills --days 30 --json

Forecast options:

  • --scenario <name> applies a planning scenario
  • --account <name> narrows the forecast to one account
  • forecast show defaults to 90 days
  • forecast bills defaults to 30 days

Scenarios​

helius scenario add "Downside" --note "Emergency spending month"
helius scenario list --json
helius scenario edit 1 --name "Stress Case"

Planning Items​

Planning items represent future transactions that have not been posted yet.

helius plan item add "Emergency Repair" --scenario Downside --type expense --amount 700.00 --date 2026-03-24 --account Checking --category Housing
helius plan item list --scenario Downside --json
helius plan item post 5

Goals​

Supported goal kinds:

  • sinking-fund
  • balance-target

Examples:

helius goal add "Vacation Fund" --kind sinking-fund --account Checking --target-amount 1500.00 --due-on 2026-08-01
helius goal add "Cash Floor" --kind balance-target --account Checking --minimum-balance 250.00

Budgets and Scenario Overrides​

helius budget set Groceries --month 2026-03 --amount 200.00 --account Checking
helius budget set Groceries --month 2026-03 --amount 500.00 --scenario "Stress Case"
helius budget status 2026-03 --scenario "Stress Case" --json

Recurring Rules in Forecasts​

helius recurring add "Rent" --type expense --amount 900.00 --account Checking --category Housing --cadence monthly --day-of-month 6 --start-on 2026-03-01
helius recurring run --through 2026-04-30

Important behavior:

  • forecast show is read-only and does not advance a recurring rule's stored next due date
  • recurring run is what actually posts due recurring entries into the ledger