Actions reference

Actions are one-off, dated events that don’t fit the declarative model — a lump-sum transfer, a stock trade at a particular time, a one-time expense, a property purchase, a mid-plan rate change. They live under the actions: list in the config. This page documents every action and its fields; for the at-a-glance summary and the dating rules, see Configuration.

Common fields #

Every action is an object selected by its action: field. All actions share these:

When an action actually posts: on the start date of the period its date falls in — the exact date in daily mode, the 1st of the month in monthly mode, January 1 in annual mode. The date only selects and orders the action within its period. Use a finer granularity when an action must be dated exactly. See How it works for why.

Fields marked (inflated) below are given in plan-start dollars and inflated to the action’s date at run time — see How amounts are inflated and grown.

Cash transfers #

transfer-money #

Move a fixed amount between two of your own accounts. The source must hold the funds.

- action: transfer-money
  date: 2030-07-01
  amount: 15000
  account1: assets:bank:checking
  account2: assets:brokerage
  description: Move savings into brokerage

receive-income #

A one-off inflow — a gift, inheritance, or bonus. Like transfer-money, but the source (account1, an income account) is not balance-checked.

transfer-all-money #

Move an account’s entire default-currency balance to another account. Fields: account1, account2.

reimburse #

Credit an amount into an account (e.g. an expense reimbursement). Fields: amount (inflated), account1.

conditional-transfer #

A transfer capped by a target balance and/or a per-period amount — the primitive that incomeRules compile to. You rarely write it by hand; prefer incomeRules in the config.

Income and expenses #

add-income / remove-income #

Add or remove a recurring income stream mid-plan. Added income does not grow (no growthRate); for a growing salary, configure it in the income: section instead.

add-income fields: incomeType (salary | social-security), period, amount, description (optional). remove-income fields: description (optional; removes the last-added income when omitted).

add-expense / remove-expense #

Add or remove a recurring expense mid-plan.

add-expense fields: expenseType (general | rent | property-cost | property-improvement), period, amount, account, and propertyAccount (for the property-tied types). remove-expense fields: account (required, for matching) and description (optional).

spend-money #

A one-time expense, funded from the general account (drawing on the funding cascade if needed).

- action: spend-money
  date: 2035-09-01
  amount: 5000
  account: expenses:travel
  description: Europe trip

Investments #

purchase-stock / purchase-stock-by-amount #

Buy shares of a ticker into an account — either a share count or a dollar amount.

• purchase-stock: ticker, shares, account.
• purchase-stock-by-amount: ticker, amount (inflated), account.

sell-stock / sell-all-stocks #

Sell shares from an account, realizing capital gains.

• sell-stock: ticker, shares, account.
• sell-all-stocks: ticker, account (sells the entire position).

transfer-all-commodities #

Move all commodity holdings from one account to another. Fields: account1, account2.

update-autoinvest #

Retune an account’s auto-investing allocation mid-plan. Fields: account, invest (a bare ticker for 100%, or a ticker→percent map that must sum to 100).

- action: update-autoinvest
  date: 2040-01-01
  account: assets:brokerage
  invest: { VTI: 70, VXUS: 30 }

Real estate and loans #

Real estate is a hub-and-spoke of ordinary building blocks; these actions drive its lifecycle. See Configuration for the full picture.

buy-property #

Create a property account and record its purchase — optionally financed with a mortgage. Only account and purchasePrice are required.

- action: buy-property
  date: 2030-06-01
  account: assets:real-estate:home
  purchasePrice: 400000
  closingCostsRate: 0.03
  residence: true
  liabilityAccount: liabilities:mortgage:home
  downPaymentRate: 0.20
  interestRate: 0.065
  loanTerm: 30

sell-property #

Sell a property at market value, record the capital gain and fees, and pay off every loan linked to it (via propertyAccount: / the hforecast-property: tag). Works on a property owned from the start (seeded from a journal) or one bought during the plan. Selling stops the property’s costs and ends its loans’ amortization.

make-additional-loan-payment #

Pay extra principal against a loan to retire it early. One-off, or recurring with repeat. Fields: account (the loan), amount (inflated).

refinance-loan #

Refinance a loan partway through the plan — as if a fresh loan paid off the old one. Fields: account (the loan), interestRate, and optionally term (years; default: the loan’s current term) and closingCostsRate. The outstanding balance is re-amortized over the term at the new rate, so the payment reflects what is still owed, not the original principal. Closing costs are that fraction of the refinanced balance, paid from cash through the funding cascade. The loan must be a tracked liability with a balance still outstanding; the rate and closing-costs rate must be non-negative and any term must be positive.

set-income-growth #

Retune the growth rate of every income matching a description partway through the plan. Fields: description, growthRate. At least one income must match. A social-security income is rejected — it grows with its statutory COLA (inflation), not a custom rate.

Retirement, taxes, and market parameters #

set-currency-rate #

Change a currency’s inflation and/or interest rate partway through the plan. Fields: currency, and at least one of inflationRate, interestRate. The interest rate drives cash-like interest income; the inflation rate drives how future amounts are inflated from that date forward. The currency must already be tracked (the default currency, or one declared in currencies:).

set-inflation-rate #

Shorthand for the inflation-only case of set-currency-rate. Fields: currency, rate.

register-symbol #

Introduce a new ticker mid-plan (e.g. before buying it). Fields: ticker, and optionally assetClass, growthRate, dividendRate, initialPrice (default 1).

set-symbol-rate #

Retune an already-known symbol’s rates partway through the plan. Fields: ticker, and at least one of growthRate (price appreciation), dividendRate, couponRate (the last two are aliases for the same yield). The ticker must already exist — declared in symbols:, held, or introduced by an earlier register-symbol. A growthRate is rejected on a bond or treasury, whose return is the coupon rather than price appreciation.

Generated actions #

A few actions are normally produced from your config rather than written by hand, though the mechanism is the same:

• receive-paycheck — the per-period salary event compiled from an income: salary entry (gross, growth, and the 401(k)/HSA diversions). Configure salary in income:, not here.
• pay-annual-taxes — the yearly tax reconciliation, scheduled automatically for January 1. Takes only the common fields.
• required-minimum-distribution — the RMD from pre-tax retirement accounts, scheduled automatically once you reach the required age. Takes only the common fields.

See also #

• Configuration — the summary table and dating semantics
• How it works — where actions fall in a period
• Granularity — dating actions exactly