Taking Over an Existing Ledger

A ledger that another tool, a script or a person has already filled holds entries for many of your bank lines. PRIMA Bookkeeper would see those lines as unposted, and post would stop on each one. Two commands record them as posted without writing anything to your ledger.

Adopting What the Ledger Holds

Start with a dry run, which lists what would be adopted and records nothing.

prima-bookkeeper adopt --from 2026-05-01 --to 2026-05-31 --dry-run

adopt reads every completed payment out in the range that is not yet recorded as posted, and asks your ledger for an existing entry. It skips lines you decided as transfers or ignored, and it reports five lists.

List	What it holds	What happens
Adopted	An entry carries the bank line’s id, either as the tool’s own ptx: tag or as an id another tool wrote, at the same amount	Recorded as posted when you run adopt without --dry-run
Probable	An entry for the same supplier and amount within three days that carries no id	Recorded only with --accept-probable, after you check each one
Amount differs	An entry names the bank line’s id at a different amount	Never adopted. Check each one in your ledger
Already linked	The entry is already recorded against another bank line	Never adopted. If one entry covers both lines, link this one by hand with an allocation
Not found	Nothing in your ledger covers the line	Goes through the normal cycle

When the lists look right, run the same command without --dry-run. Add --accept-probable only after you have checked every probable match in your ledger.

Linking One Line by Hand

link-posting records one bank line as posted against a ledger entry you name. Use it for a difference you have accepted, or for an entry the adapter cannot find.

prima-bookkeeper link-posting <bank line id> <ledger entry id> --by "Your Name" --note "deposit, balance paid in June"

It does not read the ledger entry, it needs your name, and it refuses a line that is already recorded as posted. It has no MCP tool, so you run it in your own terminal.

One Entry for Several Payments

One ledger entry can cover several bank lines, such as a deposit and a final payment on one invoice. Link each bank line to the same entry, and give the entry’s total with --entry-total.

prima-bookkeeper link-posting <deposit line id> <invoice id> --by "Your Name" --note "deposit" --entry-total 1230.00
prima-bookkeeper link-posting <final line id> <invoice id> --by "Your Name" --note "balance" --entry-total 1230.00

Each link reports how many bank lines the entry now covers and how much is still to allocate. A link that would take the total over the entry’s total is refused. Add --allocated when only part of a bank line belongs to the entry. post never shares an entry between bank lines by itself, so it stops on a line whose entry another line already holds.

What Each Ledger Can Find

Ledger	What adopt recognises
Sage Business Cloud Accounting	The tool’s own tag, a bank id written by another tool, a fee line by its payment’s id, and an entry at a different amount
QuickBooks Online and FreshBooks	The tool’s own tag, plus the probable match for the same supplier and amount
Xero	The tool’s own tag only

What Changes and What Does Not

Both commands write to the tool’s own records only, and they create, change or delete nothing in your ledger. Neither passes through the review gate in this version. The audit records each run, link-posting under the name you give and adopt under user.

The VAT pack counts an adopted or linked line only when the line has a proposal, and at the proposal’s figures. Your ledger’s own VAT report stays the source for the return, as VAT Return Preparation explains.