bus-period — manage accounting periods and year rollover
bus period — manage accounting periods and year rollover
bus period controls when the books are open for posting and when they are closed or locked. Use it to create periods, move them through their lifecycle, and generate opening balances for a new year from a prior workspace.
If a period is not open, normal journal posting should not continue there. This module is what keeps that timeline explicit and reviewable.
Common tasks
Create the period control dataset:
bus period init
Create and open the first month of a new year:
bus period add --period 2026-01 --retained-earnings-account 3200
bus period open --period 2026-01
List current periods and validate the control data:
bus period list
bus period validate
Close and then lock a finished period:
bus period close --period 2026-01
bus period lock --period 2026-01
Freeze a reviewed period without automatic closing journals:
bus period lock --period 2026-02
Reopen a closed period for a controlled correction window:
bus period reopen \
--period 2026-01 \
--reason "Correction to January accrual" \
--approved-by reviewer@example.com
Generate opening balances for the new year from a prior workspace:
bus period opening \
--from ../books-2025 \
--as-of 2025-12-31 \
--post-date 2026-01-01 \
--period 2026-01 \
--equity-account 3200
Create a cross-year custom period:
bus period add \
--period FY2024-2025 \
--start-date 2024-07-01 \
--end-date 2025-06-30 \
--retained-earnings-account 3200
bus period open --period FY2024-2025
Synopsis
bus period init [-C <dir>] [global flags]
bus period add --period <period> [--start-date <YYYY-MM-DD>] [--end-date <YYYY-MM-DD>] [--retained-earnings-account <code>] [-C <dir>] [global flags]
bus period open --period <period> [-C <dir>] [global flags]
bus period close --period <period> [-C <dir>] [global flags]
bus period lock --period <period> [-C <dir>] [global flags]
bus period reopen --period <period> --reason <text> --approved-by <id> [--voucher-id <id>]... [--max-open-days <n>] [-C <dir>] [global flags]
bus period set --period <period> --retained-earnings-account <code> [-C <dir>] [global flags]
bus period list [--history] [-C <dir>] [global flags]
bus period validate [-C <dir>] [global flags]
bus period opening --from <path> --as-of <YYYY-MM-DD> --post-date <YYYY-MM-DD> --period <period> [options] [-C <dir>] [global flags]
Period lifecycle
The normal lifecycle is:
future → open → closed → locked
There is also an administrative freeze path:
open → locked with lock
If a correction is needed, reopen creates a controlled exception path from a closed period. After the corrections, you close it again.
list shows the effective current state. list --history is the command to use when you want to see the full append-only timeline of changes.
Which command should you use?
Use add when the period does not exist yet.
Use open when posting work should begin.
Use close when the period bookkeeping is complete enough to mark a deterministic cut-off and write the carry-forward snapshot.
Use lock when the period should no longer be reopened casually.
Use lock when the period should become non-editable without writing automatic close vouchers.
Use set to repair or define the retained-earnings account for a period.
Use opening when you are rolling a workspace into a new fiscal year and want one deterministic opening entry from the prior year’s closing balances.
Important details
Period identifiers may be arbitrary non-empty strings. The shorthand forms YYYY, YYYY-MM, and YYYYQn remain special because add can derive start and end dates from them automatically.
When you use a custom or cross-year identifier such as FY2024-2025, pass both --start-date and --end-date on add.
Each period needs a retained-earnings account. If you omit it on add, the default is 3200.
close is a non-posting finalization step. It validates the period slice, appends a closed period-control row, updates journal-closed-periods.csv, and writes periods/<period-id>/opening_balances.csv for carry-forward use. If you need year-end or tax adjustments, post those explicitly before closing.
lock is the administrative freeze command. It updates period control and journal-closed-periods.csv, but it does not change the journal and it does not create period-owned artifacts.
opening expects the target period to already exist and be open.
reopen can also record one or more --voucher-id values when you want the reopen window tied to specific correction vouchers.
Storage mode for period-owned datasets is resolved through shared bus-data policy handling. If no explicit workspace, module, or resource storage policy exists, bus period uses ordinary CSV by default. PCSV-1 remains an opt-in storage choice and is not selected by private module-specific _pcsv parsing.
Typical workflow
A common year-start flow is:
bus period init
bus period add --period 2026-01 --retained-earnings-account 3200
bus period open --period 2026-01
bus journal init
bus period opening \
--from ../books-2025 \
--as-of 2025-12-31 \
--post-date 2026-01-01 \
--period 2026-01
For a normal monthly close:
bus period validate
bus reports trial-balance --as-of 2026-01-31
bus period close --period 2026-01
bus period lock --period 2026-01
Files
This module owns periods.csv and periods.schema.json at the workspace root. When you close a period, it also writes the derived carry-forward artifact periods/<period-id>/opening_balances.csv. close does not append synthetic close vouchers or a separate close_entries.csv.
Output and flags
These commands use Standard global flags. list is the main read/report command. --dry-run is especially useful for add, open, close, reopen, set, and opening when you want to preview period-control changes.
For the full flag details, run bus period --help.
Exit status
0 on success. Non-zero on invalid usage, invalid state transitions, missing periods, invalid retained-earnings accounts, or opening-generation failures.
Using from .bus files
Inside a .bus file, write this module target without the bus prefix.
# same as: bus period add --period 2026-01 --retained-earnings-account 3200
period add --period 2026-01 --retained-earnings-account 3200
# same as: bus period open --period 2026-01
period open --period 2026-01
# same as: bus period close --period 2026-01
period close --period 2026-01