How a book works

A BeanHub book is a Git repository. The website always shows the latest commit on the branch you selected. You need to know where files go and which views read them.

You talk to the website, Git HTTPS, and the API. The book is a Git repository of Beancount files. BeanHub shows journal, reports, import, and inbox.

Files that matter

A sample Git repository looks like this:

main.bean                 # required entry point
accounts.bean             # open directives for accounts
commodities.bean          # commodity declarations
books/2026.bean           # transactions for a year
books/books.bean          # includes yearly files
.beanhub/imports.yaml     # CSV import rules
.beanhub/forms.yaml        # custom forms
import-data/              # CSV files import rules match
README.md

BeanHub loads main.bean and follows include directives. Files not included from main.bean are still in Git, but they do not appear in the journal or reports.

The sample layout comes from the open-source beanhub-beancount-cookiecutter. You can generate the same tree locally with cookiecutter if you prefer not to use the website Sample template.

Website vs Git vs API

Path	Host	Auth	What it is for
Website	`https://app.beanhub.io`	Signed-in session (email/password, optional MFA)	Browse, edit, import, reports, inbox
Git Smart HTTP	`https://app.beanhub.io/repos/<user>/<repo>.git`	HTTP Basic, password = access token	`git clone`, `fetch`, `push`
HTTP API	`https://api.beanhub.io`	Header `access-token`	Programmatic reads and writes

SSH remotes are listed in the clone dropdown as coming soon. They are not available.

What happens on a push

You git push, or the website creates a commit for you (add transaction, import, form submit, edit entries).
BeanHub checks out the tree in a sandbox and loads main.bean.
If Beancount reports errors, the push or website commit is rejected. You see the error in the Git client or as a red banner on the website.
If the tree is valid, BeanHub stores the commit, exports entries for the journal and reports, and runs import matching when .beanhub/imports.yaml exists.

Website edits usually run beancount-black so the files stay formatted.

Branches

The empty-repository help text tells you to git push origin master. Sample repositories are created on master. If you push a different default branch from an empty repo, that branch becomes the one BeanHub tracks. The website has a branch switcher in the breadcrumb once commits exist.

Public vs private

Private: only you (and future collaborators, when that product work ships) can see it. Free accounts get 1 private book.
Public: anyone on the internet can read it. BeanHub uses this for transparent books (non-profits, campaigns). Making a private book public requires typing the repository name and checking a risk checkbox.

Free public books get the higher 100,000 entries quota, same as paid books. Free private books are capped at 1,000 entries. Details: Limits and plans.

Connect-only books

A Connect repository has no hosted Beancount files. The sidebar is mostly Connect Banks and Inbox. You dump CSVs with bh connect dump on your machine. See Connect banks.