Add cash-flow-role metadata to an account's open directive to declare how the cash-flow report classifies that account. One key, four values. Accounts without the metadata keep the default heuristics.
2000-01-01 open Assets:US:Brokerage
cash-flow-role: "investing"
2000-01-01 open Assets:US:Marcus:Savings
cash-flow-role: "cash"Key and values
| Key | Where | Value type | Accepted values |
|---|---|---|---|
cash-flow-role | open directive metadata | string | "cash", "operating", "investing", "financing" |
Matching is case-sensitive and exact. The value must be a quoted string. Other metadata keys on the same directive are ignored by the report, and this key is ignored by every other tool.
What each value does
A declared role answers two questions at once: whether the account is part of the cash pile, and which activity section it belongs to otherwise.
"cash"— the account joins the cash-and-equivalents set. Cash accounts never appear as activity line items. The statement's bottom line, net change in cash and equivalents, equals the sum of their period changes. Transfers between two cash accounts cancel out. Use it for accounts the name heuristic misses, such as a money-market fund or a stablecoin wallet."operating","investing","financing"— the account is not cash, and its period change appears as a line under that activity section. Declaring one of these on an account the name heuristic would treat as cash, such asAssets:US:Bank:CD, both removes it from the cash set and files it under the declared section.
Declarations are trusted over accounting conventions. An Equity account declared "operating" is honored verbatim.
Precedence
Highest wins:
cash-flow-rolemetadata on the account'sopendirective.- The built-in default heuristics below.
Default classifications
An account with no declared role is classified by its root, with a name check deciding cash membership:
| Account root | Default activity |
|---|---|
Income, Expenses | Operating |
Assets (non-cash) | Investing |
Liabilities, Equity | Financing |
Asset accounts whose names contain Cash, Checking, Savings, or Bank are treated as cash and equivalents by default. A declared role overrides the name check in both directions.
Invalid values
An unrecognized value is treated as absent. A typo such as "invsting", a non-string value, or wrong casing falls back to the default heuristic, and the report flags the account in the status panel with an unknown-value note. Nothing fails to render, and nothing is silently accepted.
Changing a classification
Classifications are not date-effective. A statement for any period uses the declarations as they stand today. To change one, edit the open directive; the ledger's version control records what changed and when.
Where declarations apply
One shared resolver produces the final role for each account, and every consumer reads from it:
- The cash-flow report: activity sections, the cash-and-equivalents set, and the bottom-line reconciliation.
- CSV, Markdown, and print exports: the same numbers. The classification-is-inferred disclosure appears only for rows still resolved by the heuristic.
- The overview cash-flow diagram:
"cash"excludes the account from flow nodes, and declared activity roles are honored for non-Income accounts. Income stays the source side and Equity stays excluded from the diagram; declarations never remap those two. - The account-status panel: a declared account no longer appears as an unclassified asset.
Portability
Metadata on open directives is core Beancount syntax. bean-check, Fava, and every v2/v3 tool parse it and ignore the unknown key, so the ledger remains fully usable outside Beancount.io. See Beancount Syntax for the general metadata format.
