Setting Up Your Books

Setup takes your workspace from a fresh install to your first completed month. In Claude Code, run /bookkeeper-setup and the wizard walks you through it one step per message. This page describes the same sequence, so you can follow it with any agent or by hand.

Note

Setup ends when your first month has gone through, from fetching your transactions to reconciling the bank. A workspace with every file in place and no completed month is not yet set up.

How the Wizard Works

• One step per message. The wizard asks one question or prints one terminal command, then waits for your answer or the result.
• It resumes where you left off. It checks what is already in place before it asks anything, so you can stop and come back.
• You type every credential yourself. Client ids, secrets and codes go into your own terminal at hidden prompts, so they are never part of the conversation with the agent.

Step 1, Choose Your Ledger and Bank Feed

PRIMA Bookkeeper works with four accounts packages and three kinds of bank feed.

Accounts package	Bank feed
Sage Business Cloud Accounting	Revolut Business, by API
Xero	Another bank by API, through GoCardless Bank Account Data
QuickBooks Online	A CSV export from any bank’s online banking
FreshBooks

A CSV export needs no app and no consent, and it works with any bank that lets you export a CSV. You can switch an account to an API feed later.

PRIMA Bookkeeper applies the VAT rules of your country from a country pack. Run prima-bookkeeper packs to list the country packs you have installed. Choose IE for Ireland.

Step 2, Connect Your Accounts Package

Each business registers its own app with its accounts package, so your ledger connects straight to an app you own.

1. Create the app in your accounts package’s developer portal. The wizard walks you through the vendor’s own screens until the client id and secret are on screen.
2. Run prima-bookkeeper credentials set sage in your terminal. Use the name of your own accounts package in place of sage, and type each value at the hidden prompt.
3. Run prima-bookkeeper auth sage. Approve the request in the browser that opens.

The auth command waits for your browser to send the approval back to your computer on port 5555. If you registered a different port number when you created the app, add --port and that number. If your accounts package accepts only a secure https address for this, add --manual. The terminal then asks for the code at a hidden prompt.

Step 3, Connect Your Bank

For Revolut Business or GoCardless, follow the same three steps with revolut or gocardless in place of the ledger name. The auth command ends by printing your bank account ids, which setup needs in Step 4.

For a CSV export, download a recent statement from your online banking and run the command below.

prima-bookkeeper csv-inspect "statement.csv"

Check the detected format and which column holds the date, the amount and the description. If a column is wrong, run prima-bookkeeper formats and try again with --format and the right format id.

Step 4, Describe the Business

Your ledger cannot answer these questions, so the wizard asks you.

1. Is the business registered for VAT, and what is its VAT number?
2. Does it account for VAT on the invoice basis or the cash receipts basis?
3. Which VAT return period does it use, such as bi-monthly or four-monthly?
4. In which month of the year does its financial year start?
5. Should PRIMA Bookkeeper post money coming in as sales in your ledger, or do you enter sales by hand yourself?

Your accountant or your Revenue correspondence holds the answers to the first three. Then run init with your answers, as the example below shows.

prima-bookkeeper init --jurisdiction IE --name "Example Consulting" --ledger sage --bank revolut \
  --bank-accounts <ids> --vat-registered true --vat-number <VAT number> \
  --basis invoice --period fourmonthly --fiscal-year-start 1

init reads your ledger’s business record, tax rates and chart of accounts, writes .prima-bookkeeper/business.json and reports every gap it finds. For a CSV account, save the column profile next with prima-bookkeeper csv-inspect "statement.csv" --save --account <id>.

Step 5, Add Every Other Bank Account

Add each further account, credit card or foreign-currency account with bank add, mapped to its own bank account in the ledger.

prima-bookkeeper bank add aib-current --provider csv --ledger-bank-account <id>

prima-bookkeeper bank ledger-accounts lists the ledger’s bank account ids, and each of your accounts needs its own, because two accounts cannot share one ledger bank account. Run prima-bookkeeper bank list to see what you have configured.

Step 6, Fill the Mapping Gaps

PRIMA Bookkeeper cannot post entries in a category until its ledger account is mapped, and init reports each one it could not map. Run prima-bookkeeper init --json to see the ledger’s own account list. Then add each missing id under ledger.accountMap in business.json.

On Sage, bank and currency charges post against one supplier contact for your bank. If that contact does not exist yet, create it with prima-bookkeeper contact add. Then set its id in ledger.bankFeeContactId.

Step 7, Point It at Your Invoices

PRIMA Bookkeeper links each payment to its invoice or receipt, so it needs to know where your documents are. The wizard asks four things.

1. Which folders already hold your supplier invoices and receipts, a synced cloud folder included.
2. Which folder you will save downloaded invoices to from now on, which becomes the drop folder.
3. Which one folder every document should end up in, which becomes the archive root.
4. Which mailboxes receive invoices from your suppliers.

It then writes the documents block in business.json and runs prima-bookkeeper collect, which reports how many documents it found of each kind. Invoices and Receipts explains sources, matching and filing.

Step 8, Keep the Connections Alive and Run the Health Check

1. Run prima-bookkeeper keepalive --install, which refreshes every stored connection every 72 hours, and on macOS at login as well.
2. Run prima-bookkeeper doctor, the health check, which must pass before you run your first month.

Keepalive sets up a scheduled task with the scheduler built into macOS or Windows. Without it, a Sage connection lapses after 31 idle days and needs auth again. doctor reports each connection’s lapse date and checks that every mapped tax rate still exists in your ledger at the expected percentage.

Step 9, Run Your First Month

Run /bookkeep for the last full calendar month. Then follow The Bookkeeping Cycle from fetching your transactions to reconciling the bank. When the month is done, your transactions are entered and the bank is reconciled, and the VAT figures for the period so far are available from prima-bookkeeper vat-prep.

If your ledger already holds entries for that month, read Taking Over an Existing Ledger before you post anything.