Credentials and Security

PRIMA Bookkeeper keeps no credential in a file, an environment variable or a chat. You enter each one once, in your own terminal, and the operating system’s credential store holds it.

Where Credentials Live

System	Store
macOS	The login Keychain, under the service name prima-bookkeeper
Windows	Credential Manager, as generic credentials with the target prima-bookkeeper

The store holds the client ids and secrets of your vendor apps, the connection tokens each provider issues after you approve access, the Revolut signing key and any mailbox app passwords. The tool reaches the store through a direct system call, so no value appears in a process list or your shell history.

Setting a Credential

Run credentials set with the provider’s name in your own terminal.

prima-bookkeeper credentials set sage

The terminal asks for each value in turn and hides what you type. For Revolut, it asks for the path to your private key file, stores the file’s content and tells you that you can then delete the file.

credentials set and auth refuse to run unless they are attached to a real terminal, so an agent, a script or a pipe cannot drive them.

The First Keychain Dialog on macOS

The first time the tool reads an item, macOS may ask whether node may use it. Enter your login password and choose Always Allow.

The Keychain trusts the program that saved each item. If a different Node.js runs the tool later, such as a second install or an upgrade, the dialog appears again. Use the same Node.js for credentials set, auth and keepalive --install, and run which node to check which one you are using.

Why Your Agent Cannot Reach Them

• A safety hook guards the store. The Claude Code plugin refuses, before it runs, any agent tool call that names the Keychain or its command-line clients, the Windows credential tools, .env files, key files or an environment dump.
• The MCP server takes no secret. It has no tool that accepts, stores or returns a credential, and it refuses any argument that looks like one.
• Reports show status only. credentials list and doctor say whether a value is set and when a connection lapses, never the value itself.
• The keepalive log holds no secret. It records provider names and lapse dates only.

Caution

Never paste a client id, secret, key or code into a chat with your agent. If you start to, the setup skill stops you and points you back to the terminal. A person who will not use a terminal can ask a developer they trust to run the terminal steps with them.

Keeping Connections Alive

Most providers issue tokens that lapse when they go unused. prima-bookkeeper keepalive --install refreshes every stored connection every 72 hours and at login. doctor fails when keepalive has not run for seven days, and it reports each connection’s lapse date.

GoCardless bank consents last 90 days or less, depending on the bank. When one lapses, run prima-bookkeeper auth gocardless again.

Rotating and Removing Credentials

• To replace a value, run credentials set for the provider again. Press Return at a prompt to keep the stored value.
• To remove a provider, run prima-bookkeeper credentials remove sage with your provider in place of sage, after which the provider needs credentials set and auth again.
• To end access completely, revoke the app or certificate on the vendor’s side as well, in your accounts package’s app settings, your Revolut Business API settings or your GoCardless requisitions.