Surebeans Guide

Surebeans is a privacy-focused budgeting app for Windows, macOS, Linux, and the browser.

This guide covers setup, daily usage, and advanced features. You can start with the Quick Start or jump to the Reference.

For bank transaction scraping, see Beanscrape.

Questions? Send an email or visit the community forum.

Quick Start

To get up and running, choose the most applicable scenario for you:

• New to budgeting? Create a journal from scratch.
• Coming from YNAB? Import your existing data from nYNAB or YNAB 4.
• Have a CSV or OFX file? Import from file.

Create a Journal

A journal is a folder containing plain-text hledger files tracked by git. It holds your accounts, records (that is, transactions), categories, budget allocations, rules, and sync configuration.

my-budget/
├── .git/                  # version history
├── main.journal           # root file. references the other files
├── accounts.journal       # account definitions
├── surebeans.json         # rules, remotes, app config
└── includes/
    ├── 2025.journal       # records for 2025
    └── 2026.journal       # records for 2026

Create the journal

Desktop: Click the hamburger menu (☰) → New Journal. Pick a folder.

Browser: Click ☰ → New Journal. Enter a name.

Surebeans creates a starter journal with example accounts and sample records.

Add an account

Navigate to Plan. Your starter journal includes some default accounts. To add more, go to Records, add a record, and type a new account name. Surebeans creates it automatically.

Add a record

Navigate to Records. Click + Add.

Fill in:

Press Enter or click away to save.

Assign money

Navigate to Plan. This is the envelope budgeting view.

1. Income appears in Ready to Assign at the top.
2. Click a category’s Planned column.
3. Enter the amount to budget for that category.
4. Repeat until Ready to Assign reaches zero.

The Available column shows Planned - Actual for each category. Green means under budget. Red means overspent.

Next steps

• Set up Sync to back up your journal.
• Create Rules to auto-categorize records.
• Import bank records with Beanscrape or SimpleFIN.

Import from nYNAB

Import your budget from YNAB (nYNAB / YNAB 7+). This creates a new journal.

Export from YNAB

1. Log in to app.ynab.com.
2. Go to Settings → Export Budget.
3. Download the .zip file.

Import into Surebeans

1. Click ☰ → Import → From nYNAB.
2. Select the .zip file.
3. Desktop: Choose a destination folder. Browser: Surebeans picks a name automatically.
4. Surebeans creates a new journal with your accounts, categories, and records.

What gets imported

• Accounts (checking, savings, credit cards, etc.)
• Category groups and categories → mapped to budget envelopes
• All records with payee, date, amount, category, memo
• Budget allocations per month

After import

Review the Plan view to verify budget allocations carried over correctly.

Keeping up to date

To add new records after the initial import, export your budget from YNAB again and use ☰ → Import → From nYNAB export… on your existing journal. Surebeans will add only the new records.

The nYNAB API import can also pull new records directly from YNAB without a manual file export.

Import from YNAB 4

Import your budget from YNAB 4 (the classic desktop version). This creates a new journal.

Locate your YNAB 4 data

YNAB 4 stores budgets as .ynab4 folders in your Dropbox or local file system. Typical locations:

• macOS/Linux: ~/Dropbox/YNAB/
• Windows: C:\Users\<you>\Dropbox\YNAB\

Import into Surebeans

1. Click ☰ → Import → From YNAB 4.
2. Select the .ynab4 budget folder (or file).
3. Desktop: Choose a destination folder. Browser: Surebeans picks a name automatically.
4. Surebeans creates a new journal with your data.

What gets imported

• Accounts and account types
• Category groups and categories → budget envelopes
• Records with payee, date, amount, category, memo
• Budget allocations

After import

Review Plan to verify your envelopes. Check Records to confirm history.

Import from File

Import records from a CSV, OFX, or QFX file. Unlike YNAB imports, this adds records to an existing journal. It does not create a new one.

Select a file

1. Click ☰ → Import → From CSV/OFX.
2. Browse for your file.
3. Surebeans auto-detects the format.

CSV import

CSV files require column mapping.

1. Map columns: Assign each CSV column to a record field (Date, Payee, Amount, etc.).
2. Configure options:
   • Date format (e.g., yyyy-MM-dd, MM/dd/yyyy)
   • Delimiter (comma, semicolon, tab)
   • Invert amounts (if your bank uses opposite signs)
   • Split inflow/outflow columns (if amounts are in separate columns)
3. Select account: Choose which account these records belong to.
4. Preview: Review parsed records before importing.
5. Import.

OFX/QFX import

OFX and QFX files are self-describing. Surebeans reads the fields automatically.

1. Select the account to import into.
2. Preview records.
3. Import.

Deduplication

Surebeans assigns an import key to each imported record. Re-importing the same file skips duplicates.

After import

Run Rules to auto-categorize the imported records. Assign money in Plan.

Reference

Detailed documentation for every area of Surebeans.

Open Journal

Click ☰ to access journal options.

Recent

Lists up to 10 recently opened journals. Click one to open it.

Pick Folder Desktop

Opens a native folder picker. Select a folder containing a main.journal file.

Browser: Not available. Journals are stored in browser storage and appear in the Recent list.

Clone from Remote

Downloads a journal from a remote server. See Sync for supported remote types.

1. Select remote type (GitHub, GitLab, S3, etc.).
2. Enter connection details (URL, token, etc.).
3. Desktop: Choose a local destination folder.
4. Surebeans clones the journal and opens it.

Browser: Limited remote types available. See Sync for browser vs desktop support.

Load Demo

Loads a pre-built demo journal with sample accounts, records, categories, and budget allocations. Useful for exploring the app before creating your own data.

New Journal

Creates a fresh journal: a git-tracked folder of plain-text hledger files, with starter accounts and a sample record.

Desktop

1. Click ☰ → New Journal.
2. Pick a destination folder via the native file dialog.
3. Surebeans creates the journal files and initializes a git repository.

Browser

1. Click ☰ → New Journal.
2. Enter a name (e.g., my-budget).
3. Journal is created in browser storage at /journals/<name>.

What gets created

my-budget/
├── .git/                  # created automatically
├── main.journal           # root file with include directives
├── accounts.journal       # account definitions
├── surebeans.json         # rules, remotes, app config
└── includes/
    └── 2026.journal       # records for the current year

A git repository is initialized and an initial commit is created automatically. Surebeans adds a new includes/<year>.journal file as needed.

Plan

Envelope budgeting view. Assign income to categories (envelopes) to control spending.

Ready to Assign

Displayed at the top. Shows unbudgeted income, i.e. money received but not yet allocated to any category. Goal: bring this to zero each month.

Category groups

Collapsible sections that organize categories. Examples: Fixed Expenses, Variable Expenses, Savings Goals. Each group row shows totals for Assigned, Activity, and Available across its categories.

• Add group: Click + Add Group in the header.
• Rename: Click the pencil icon next to the group name.
• Collapse/expand: Click the group row to toggle visibility of its categories.
• Delete: Click the trash icon on the group row. Click again to confirm (two-stage delete). Click the X to cancel.

Categories (envelopes)

Each category represents a spending envelope.

• Add category: Click + Add within a group.
• Rename: Click the pencil icon next to the category name.
• Delete: Click the trash icon on the category row. Click again to confirm. Click the X to cancel.

Uncategorized Records

When records exist without a budget category, an Uncategorized Records row appears at the top of the plan. Its Activity column shows the total uncategorized spending. Click it to jump to those records in the Records tab.

Move Money

Click a category’s Available pill to open the Move Money popup. Enter an amount and select a target category. The budgeted amounts for both categories are adjusted so Available balances shift accordingly.

Month navigation

Use the left/right arrows or month/year picker to navigate between months. Each month has independent assigned amounts.

Responsive layout

On narrow screens (under 600px), the Plan switches from a columnar table layout to a card-based layout with each category shown as a stacked card.

Overspending

When a category’s Available goes negative (red pill), you’ve overspent that envelope. Move money from another category or add more to Assigned.

Records

Ledger showing all records across accounts.

Columns

Each row has the following columns from left to right:

Grip handle. Drag a record up or down to reorder it. Drop it between rows to change its date. The record takes the date of the row below the drop line. Dropping above the first row sets the date to today.

Status dot. A colored circle showing the record’s cleared status:

• Blue - New
• Orange - Pending
• Grey - Cleared

Click the dot to cycle through statuses. If multiple records are selected, clicking any selected dot cycles all of them together. Hover for a tooltip describing the current status and next action.

These map to hledger’s record status markers: New has no marker, Pending is !, and Cleared is *. You can use any workflow you like -for example, mark imported records as Pending and flip them to Cleared once you’ve verified them against your bank statement.

Date, Payee, Memo, Account, Category, Amount, Balance. Standard record fields. Balance is visible only when a single account is selected.

Selecting records

Click a row to select it.

Cmd+Click (macOS) or Ctrl+Click (Windows/Linux) to toggle individual rows in and out of the selection.

Shift+Click to select a range of rows from the current selection anchor to the clicked row.

Filter bar

Narrow the visible records.

Date range. Select a preset (Today, This Month, This Year, All) or a custom date range.

Account. Select one account. When a single account is selected, a cumulative running balance column appears.

Category. Filter to records in a specific budget category.

Search. Free-text search across payee and memo fields.

Adding a record

Click + Add. Fill in date, payee, amount, account, category, and optionally memo. Press Enter or click away to save.

A record is committed to your journal immediately.

Editing a record

Click a field to edit inline. Changes save when you click away or press Enter.

Editable fields: date, payee, amount, account, category, memo.

Splitting a record

Expand a row to view its postings. Split one record across multiple categories (e.g., a store receipt split between Groceries and Household).

Deleting records

Select one or more records. Click Delete or press the Delete key. A confirmation banner appears -press Delete again to confirm, or Escape to cancel (two-stage delete). Selected rows are highlighted in red while pending confirmation.

Renaming multiple records

Click Rename to open the bulk find-and-replace tool. Select a scope (payee, memo, category, or account), search for a value, and replace it across matching records.

Transfers

A transfer is a record between two asset/liability accounts. Enter both account names in the record. Surebeans marks the movement as a transfer. Click the swap icon on a transfer row to filter and show both sides.

Reordering records

Drag a row by its grip handle (the leftmost column). A blue line shows where the record will land. The record takes the date of the row below the drop line, or today’s date if dropped above the first row.

Reconciliation

Click the status dot to cycle a record’s cleared status: New (blue) → Pending (orange) → Cleared (grey). When multiple records are selected, clicking any dot in the selection cycles all selected records to the same status.

Infinite scroll

Records load progressively as you scroll. No pagination controls needed.

Keyboard shortcuts

Accounts

Overview of all accounts and their balances, grouped by type.

Account groups

Accounts are organized into hierarchical groups:

• Assets: checking, savings, cash
• Liabilities: credit cards, loans
• Income: salary, freelance, interest
• Expenses: spending categories

Each group shows a total balance. Expand to see individual accounts.

Viewing account records

Click an account name to navigate to Records filtered to that account. The cumulative balance column becomes visible.

Account balances

Balances are computed from all records in the journal. They update in real time as you add or edit them.

Reflect

Reports and analytics. Select a report type from the pill bar at the top.

Net Worth

Tracks your total assets minus total liabilities over time.

Reading the chart

• Assets (top line): Sum of all asset accounts (checking, savings, investments).
• Liabilities (bottom line): Sum of all liability accounts (credit cards, loans).
• Net Worth (middle area): Assets minus liabilities.

The chart shows monthly data points. Hover over a point to see exact values.

Date range

Adjust the date range to zoom in on a specific period or view the full history.

Spending

Breakdown of expenses by category for a given period.

Reading the chart

Shows each expense category’s share of total spending. Categories are sorted by amount.

Date range

Select a month or custom range to analyze spending for that period.

Trends

Spending patterns over time, broken down by category.

Reading the chart

Line chart showing monthly spending per category. Identify categories where spending is increasing or decreasing.

Date range

Adjust the range to view short-term or long-term trends.

Income vs Expense

Monthly comparison of total income and total expenses.

Reading the chart

• Income bars: Total income received each month.
• Expense bars: Total expenses each month.
• Net: The difference. Positive = you saved money. Negative = you spent more than you earned.

Date range

Shows monthly bars for the selected period.

Cash Flow

Inflows and outflows of money over time.

Reading the chart

• Inflows: Money coming in (income, refunds, transfers in).
• Outflows: Money going out (expenses, transfers out).

Helps identify months with cash shortfalls or surpluses.

Date range

Adjust to view monthly, quarterly, or yearly cash flow patterns.

Buffer

How many days of expenses your current balances can cover.

Reading the chart

Buffer = total liquid assets / average daily spending. A buffer of 30 means you could cover 30 days of expenses with no income.

Interpretation

Track this over time to see if your financial resilience is improving.

Rules

Automate record categorization. Rules match records by pattern and apply actions (set category, memo, etc.).

How rules work

When you run rules, Surebeans evaluates each uncategorized record against the rule list from top to bottom. The first matching rule wins. If no rule matches, the record is unchanged.

Rule structure

Each rule has:

• Condition: Pattern to match against payee and/or memo (e.g., AMAZON matches any record containing “AMAZON”).
• Action: What to do when matched (set category, set memo, etc.).
• Match count: Number of existing records this rule would match.

Operations

Tips

• Put more specific rules higher in the list.
• Use Run on a single rule to preview its effect before running all.
• Rules only apply to records that don’t already have a category (unless the rule is configured to override).

Sync

Sync your journal to a remote server for backup and multi-device access. Sync is manual: click Sync Now to push/pull changes.

How it works

Your journal is a git repository. Sync pushes and pulls commits to/from a remote. If both sides changed since the last sync, Surebeans merges the changes. Conflicts are rare but handled with a resolution UI if they occur.

Adding a remote

1. Navigate to Sync.
2. Click Add Remote.
3. Select a remote type and enter connection details.
4. Click Sync Now to perform the first sync.

Supported remotes

Managing remotes

• Edit: Change connection details for an existing remote.
• Delete: Remove a remote (two-stage confirmation). Does not delete remote data.
• Last sync: Timestamp of the most recent successful sync.

Conflict resolution

If a merge conflict occurs, Surebeans shows the conflicting changes side-by-side. Choose which version to keep or manually edit the result.

Browser limitations

Some remote types require native network access not available in the browser. See the table above. For browser-compatible remotes that require CORS, Surebeans can use a CORS proxy.

GitHub

Sync your journal to a GitHub repository.

Setup

1. Create a private repository on github.com.
2. In Surebeans: Sync → Add Remote → GitHub.
3. Enter the repository URL.
4. Authenticate with one of the methods below.

Option A: Personal Access Token

1. Generate a Personal Access Token with repo scope.
2. Paste the token into the Token field.

Option B: OAuth

1. Toggle Use OAuth in the sync setup.
2. Click Sign in. Your browser opens for GitHub authorization.
3. Approve the request and return to Surebeans.

A default GitHub client ID is built in, so no additional configuration is needed.

Configuration

Platform support

Tips

• Use a private repo to keep financial data confidential.
• The token is stored locally and never sent anywhere except GitHub.

GitLab

Sync your journal to a GitLab repository.

Setup

1. Create a private project on gitlab.com (or your self-hosted instance).
2. In Surebeans: Sync → Add Remote → GitLab.
3. Enter the repository URL.
4. Authenticate with one of the methods below.

Option A: Personal Access Token

1. Generate a Personal Access Token with write_repository scope.
2. Paste the token into the Token field.

Option B: OAuth

1. Create an OAuth application in your GitLab account or instance (Settings → Applications).
2. Enter the Client ID in Surebeans.
3. Click Sign in. On desktop, a redirect flow opens your browser. In the browser version, the device flow is used instead.
4. Approve the request and return to Surebeans.

Configuration

Platform support

Gitea

Sync your journal to a Gitea instance.

Setup

1. Create a private repository on your Gitea server.
2. In Surebeans: Sync → Add Remote → Gitea.
3. Enter the repository URL.
4. Authenticate with one of the methods below.

Option A: Access Token

1. Generate an access token in Settings → Applications on your Gitea instance.
2. Paste the token into the Token field.

Option B: OAuth

1. Create an OAuth application on your Gitea instance (Settings → Applications → Manage OAuth2 Applications).
2. Enter the Client ID in Surebeans.
3. Click Sign in. A redirect flow opens your browser for authorization.
4. Approve the request and return to Surebeans.

Configuration

Platform support

Generic Git

Sync to any git remote accessible via SSH or HTTPS.

Setup

1. Set up a bare git repository on your server.
2. In Surebeans: Sync → Add Remote → Generic Git.
3. Enter the remote URL.

Configuration

Authentication depends on the transport:

• SSH: Uses your system SSH key.
• HTTPS: Enter username and password/token.

Platform support

S3

Sync your journal to an S3-compatible object store (AWS S3, MinIO, Cloudflare R2, Backblaze B2, etc.).

Setup

1. Create a bucket on your S3 provider.
2. Generate access credentials (Access Key ID + Secret Access Key).
3. In Surebeans: Sync → Add Remote → S3.
4. Enter bucket, region, and credentials.

Configuration

Platform support

CORS (browser)

If syncing from the browser, configure your bucket’s CORS policy to allow requests from https://app.surebeans.net (or wherever you host the app).

WebDAV

Sync your journal to a WebDAV server (Nextcloud, ownCloud, etc.).

Setup

1. Ensure you have a WebDAV endpoint. Nextcloud provides one at https://your-instance.com/remote.php/dav/files/USERNAME/.
2. In Surebeans: Sync → Add Remote → WebDAV.
3. Enter the URL and credentials.

Configuration

Platform support

SFTP

Sync your journal to any server with SSH/SFTP access.

Setup

1. Ensure you have SSH access to the target server.
2. In Surebeans: Sync → Add Remote → SFTP.
3. Enter connection details.

Configuration

Platform support

Dropbox

Sync your journal to Dropbox.

Setup

1. In Surebeans: Sync → Add Remote → Dropbox.
2. Authorize Surebeans to access your Dropbox account.
3. Choose a folder path within Dropbox.

Configuration

Authorization uses OAuth. Surebeans never sees your Dropbox password.

Platform support

History

Every change to your journal is a git commit. History shows the full commit log.

Commit log

Displays commits in reverse chronological order.

Use pagination controls (First, Previous, Next, Last) to navigate.

Revert

Select a commit to restore the journal to that point in time. This creates a new commit that undoes all changes after the selected point. No data is destroyed.

Undo / Redo

Undo reverts the most recent commit. Redo re-applies it. Both are global: they affect the entire journal, not just the current view.

How it works

Surebeans uses git under the hood. Each save operation (add record, edit record, change budget allocation, etc.) creates a git commit. The History view is a UI over git log.

This means:

• Every change is tracked and reversible.
• You can sync your journal to any git remote (see Sync).
• Advanced users can interact with the journal’s git repo directly.

Settings

App configuration and status.

Theme

Switch between Light, Dark, and Auto (follows system preference). Changes apply immediately.

Currency

Configure how currency values are displayed. This is a per-journal setting saved to the journal config file.

Presets

Select a preset or enter a custom symbol.

Symbol position

License

• Status: Shows Licensed or Trial.
• Email: Licensed email address (if licensed).
• Record count: Current count and trial limit.
• Enter license key: Paste the license key you received by email or after checkout.
• Buy: Link to purchase a license.

The trial allows a limited number of records. Purchase a license to remove the limit.

Updates Desktop

• Check for updates: Queries for available versions.
• Download and install: Applies the update.
• Current version: Displayed at bottom.

Not available in the browser. The browser version updates automatically.

Beanscrape Desktop

• Installation status: Whether Beanscrape is installed.
• Version: Installed version number.
• Download/Install: Install or update Beanscrape.
• Custom path: Override the Beanscrape executable path.

For full Beanscrape documentation, see the Beanscrape section.

Import

Bring data into Surebeans from external sources.

For bank scraping, see Beanscrape.

nYNAB Import

Import a budget from YNAB (nYNAB / YNAB 7+). Creates a new journal.

See the Quick Start guide for step-by-step instructions.

What gets imported

Export format

YNAB exports a .zip file containing CSV files for accounts, budgets, and records.

Incremental import

You can also add new records to an existing journal. Open the journal you want to update, then go to ☰ → Import → From nYNAB export…. Surebeans adds any records that are not already present rather than creating a new journal.

To skip the manual file export, use the nYNAB API import instead.

Limitations

• Scheduled records are not imported.
• Goal targets are not imported (Surebeans does not have a goal system).
• Loan accounts may need manual review.

nYNAB API Import

Import records directly from the YNAB API using a Personal Access Token.

Unlike the nYNAB file import, this method connects to YNAB’s API so there is no need to manually export and upload a file.

Setup

1. Generate a Personal Access Token in your YNAB account settings.
2. In Surebeans: ☰ → Import → From nYNAB API…
3. Paste your Personal Access Token.
4. Select a budget from the dropdown list.
5. Click Import.

New journal or incremental import

The API import supports two modes:

To do an incremental import, open an existing journal first, then run the import. Surebeans will add any records that are not already present.

Stored settings

Your Personal Access Token and selected budget are saved locally so you do not need to re-enter them on subsequent imports.

What gets imported

See nYNAB Import - What gets imported for the full mapping between YNAB and Surebeans concepts.

Tips

• The Personal Access Token is stored locally and never sent anywhere except the YNAB API.
• Use incremental import to keep your Surebeans journal up to date without re-importing everything.
• The YNAB API limits 200 web requests per hour. If you get errors, wait up to an hour and try again.

YNAB 4 Import

Import a budget from YNAB 4 (classic desktop version). Creates a new journal.

See the Quick Start guide for step-by-step instructions.

What gets imported

Same mapping as nYNAB import: accounts, categories, records, and budget allocations.

Data format

YNAB 4 stores budgets as .ynab4 folders containing JSON/SQLite files. Surebeans reads this format directly.

Typical locations

Limitations

• Scheduled records are not imported.
• YNAB 4’s “Red Arrow Right” behavior is not replicated.

File Import (CSV, OFX/QFX)

Import records from bank-exported files into an existing journal. Does not create a new journal.

See the Quick Start guide for a walkthrough.

Supported formats

• CSV. Comma-separated values. Requires column mapping.
• OFX. Open Financial Exchange. Self-describing, no mapping needed.
• QFX. Quicken variant of OFX. Treated the same as OFX.

CSV column mapping

Map each CSV column to a Surebeans field:

*Provide either Amount or Inflow+Outflow.

Options

• Delimiter: Comma, semicolon, or tab.
• Invert amounts: Flip the sign (some banks export expenses as positive).
• Account: Which account these records belong to.

OFX/QFX

No configuration needed. Select the file, choose the target account, preview, and import.

Deduplication

Each imported record gets an import key derived from its date, amount, and memo. Re-importing the same file skips duplicates.

SimpleFIN

Import records from your bank via SimpleFIN, an account aggregation service.

What is SimpleFIN?

SimpleFIN connects to your bank through a read-only data feed. It retrieves records without screen scraping, using official bank data feeds where available. SimpleFIN is a paid service ($1.50/month at time of writing).

Setup

1. Create a SimpleFIN account.
2. Connect your bank accounts within SimpleFIN.
3. Generate a SimpleFIN access token.
4. In Surebeans: ☰ → Import → From SimpleFIN.
5. Paste the access token.
6. Map SimpleFIN accounts to Surebeans accounts.

Importing records

Once configured, import fetches recent records from all connected accounts. Surebeans deduplicates automatically.

SimpleFIN vs Beanscrape

Choose SimpleFIN for convenience. Choose Beanscrape for full local control and zero cost.

Beanscrape

Beanscrape is a local, privacy-focused CLI tool that scrapes records from financial institution websites using browser automation.

Features

• Fully local. Runs on your machine. No credentials or data leave your computer (except to your bank’s website).
• Free and Open Source (FOSS). You may view, modify, and redistribute the source code.
• Scriptable. Bank scripts are C# scripts.
• Extensible. Create scripts for any bank using the interactive teach command and an LLM.

How it works

1. Beanscrape opens a real browser (Chromium via Playwright).
2. You log in to your bank. If you saved your credentials, it logs in for you.
3. Navigates to the transaction page.
4. Extracts transactions.
5. Outputs JSON or CSV.

You then import the output into Surebeans (or any budgeting tool).

Legal basis

You agree to follow your bank’s terms of service. Most banks have a “use at your own risk” policy toward finance automation tools, but some deploy technical or contractual mechanisms to block them.

In general, accessing your own financial data via automated tools is supported by:

• CFPB Section 1033 (Dodd-Frank Act): consumers have the right to access their financial data.
• GDPR Article 20: right to data portability.
• Van Buren v. United States (2021): accessing data you’re authorized to view is not a CFAA violation.

Sections

Install

Beanscrape is a single-file executable. No runtime dependencies.

From Surebeans (recommended)

1. Open Surebeans → Settings.
2. Scroll to the Beanscrape section.
3. Click Install.

Surebeans downloads and installs the correct version for your platform.

Manual download

Download from surebeans.net/beanscrape.

Place the executable somewhere on your PATH.

First run

On first launch, Beanscrape downloads and installs the Playwright browser engine (~150 MB). This only happens once.

$ beanscrape run amex

Playwright browsers not installed. Installing chromium...

Self-update

$ beanscrape update

Checks for and installs the latest version.

Run

Scrape transactions from one or more banks.

Basic usage

$ beanscrape run ./mybank.csx

Multiple banks

Pass multiple .csx file paths to scrape in parallel (each in its own browser tab):

$ beanscrape run ./amex.csx ./discover.csx ./schwab.csx

Options

Output

Transactions are written to <outdir>/<bank-id>.json (or .csv).

JSON format

{
  "bank": "amex",
  "scrapedAt": "2026-01-13T21:22:25Z",
  "transactions": [
    {
      "date": "2026-01-12",
      "payee": "GROCERY STORE",
      "memo": null,
      "outflow": 85.50,
      "inflow": null,
      "runningBalance": 1228.78,
      "isPending": false,
      "category": "Supermarkets"
    }
  ]
}

CSV format

Columns: date, payee, memo, outflow, inflow, runningBalance, isPending, category.

Progress UI

While scraping, a browser panel shows real-time progress with step indicators. You can pause or cancel from this panel.

2FA

If your bank requires two-factor authentication, Beanscrape pauses and waits for you to complete the verification in the browser. Once you approve, scraping resumes automatically.

Importing results

Import the output into Surebeans via ☰ → Import → From Beanscrape, or use File Import with the generated CSV.

Credentials

Beanscrape stores bank login credentials in your OS-native secure storage.

Storage locations

Credentials never leave your machine.

Add credentials

$ beanscrape credential add <bank-id> -u <username>
Password: ********

The password is read from stdin (not echoed).

List stored credentials

$ beanscrape credential list

Shows which bank IDs have stored credentials (passwords are not displayed).

Update credentials

$ beanscrape credential update <bank-id> -u <new-username>
Password: ********

Remove credentials

$ beanscrape credential remove <bank-id>

Environment variables

As an alternative to the credential store, set environment variables:

export [email protected]
export AMEX_PASSWORD=mysecretpassword

Variable names follow the pattern {BANKID}_USERID and {BANKID}_PASSWORD (uppercase, hyphens replaced with underscores).

You can also use a .env file in the current working directory.

Priority order: Environment variables > .env file > credential store.

Scripts

Bank scripts are C# files (.csx) that tell Beanscrape how to log in, navigate, and extract transactions from a specific bank’s website.

Running a script

Pass a .csx file path to beanscrape run:

$ beanscrape run ./mybank.csx

See Run for details.

Reviewing scripts

Scripts are plain text C# files. Open them in any editor to review what they do before running. You can verify a script doesn’t exfiltrate your credentials.

Creating scripts

See Teach and Script Creation for how to create a new script for your bank.

Teach

The teach command opens an interactive browser session to capture the details Beanscrape needs to generate a bank script.

Usage

$ beanscrape teach <bank-id>

Example:

$ beanscrape teach chase

What happens

1. A browser window opens with the Teach UI panel.
2. Navigate to your bank’s login page.
3. The panel guides you to capture:
   • Login page URL
   • Username and password field selectors
   • Login button selector
   • Transaction page URL and selectors
   • Transaction table structure (date, payee, amount columns)
4. Optionally capture screenshots of each step.

The teach panel opens alongside the bank website. Here’s what a typical session looks like:

Step 1: Navigate to your bank’s website

Step 2: Log in to your account

Step 3: Navigate to transaction history

Step 4: Select account and date range

Step 5: Identify the transaction table

Step 6: Export and finish

Output

Teach generates a markdown file at ./prompts/<bank-id>.md containing:

• Captured URLs
• DOM selectors
• Screenshots (as base64 or file references)
• Structural notes about the page layout

This file is the input for Script Creation.

Options

Tips

• Log in manually during the teach session so the panel can observe the DOM structure.
• If your bank has multiple transaction views (recent, statements, downloads), capture all of them. You can choose the best approach when generating the script.
• The teach session does not store credentials.

Script Creation

Generate a new bank script by combining the output of Teach with an LLM.

Workflow

1. Run beanscrape teach <bank-id> to capture bank website details. Output: ./prompts/<bank-id>.md.
2. Open the prompt file and the script generation guide (bundled with Beanscrape, also at docs/new-script.md in the source repo).
3. Paste both into an LLM (Claude, ChatGPT, etc.).
4. The LLM generates a .csx script.
5. Save the script as <bank-id>.csx.
6. Test: beanscrape run ./<bank-id>.csx --debug.
7. Iterate with the LLM if the script needs adjustments.

Script structure

A bank script is a C# script (.csx) that uses Beanscrape’s runtime API:

// Required: bank metadata
BankId = "mybank";
BankName = "My Bank";
BankUrl = "https://www.mybank.com";

// Required: scrape function
Scrape = async (page) =>
{
    // 1. Navigate to login page
    await NavigateAsync(page, "https://www.mybank.com/login");

    // 2. Enter credentials
    await FillAsync(page.Locator("#username"), Env("MYBANK_USERID"));
    await FillAsync(page.Locator("#password"), Env("MYBANK_PASSWORD"));
    await ClickAsync(page.Locator("#login-button"));

    // 3. Navigate to transactions
    await NavigateAsync(page, "https://www.mybank.com/transactions");

    // 4. Extract transactions
    var rows = await page.Locator(".transaction-row").AllAsync();
    foreach (var row in rows)
    {
        AddTransaction(new Transaction
        {
            Date = ParseDate(await row.Locator(".date").TextContentAsync()),
            Payee = await row.Locator(".payee").TextContentAsync(),
            Outflow = ParseAmount(await row.Locator(".amount").TextContentAsync()),
        });
    }
};

Available API

Environment & logging

Browser helpers

Parsing helpers

File parsing

Available libraries

Scripts have access to:

• Playwright: browser automation
• CsvHelper: CSV parsing
• QFXparser: OFX/QFX parsing
• System.Text.Json: JSON handling
• Standard .NET libraries (Linq, Regex, IO, Collections)

Tips

• Use --debug when testing to see detailed logs.
• Use --keep-open to inspect the browser state after a scrape.
• Some banks serve different content based on viewport size. The default viewport works for most.
• For banks that offer CSV/OFX download, prefer downloading the file and parsing it rather than scraping the DOM. It’s more reliable.

Troubleshooting

Browser fails to install

Beanscrape downloads Chromium via Playwright on first run. If this fails:

1. Check your internet connection.
2. Check firewall/proxy settings. Playwright downloads from Microsoft’s CDN.
3. Try running again. The download resumes where it left off.

Login fails

• Wrong credentials: Run beanscrape credential update <bank-id> to re-enter.
• 2FA timeout: If the 2FA prompt times out, re-run the scrape. Beanscrape waits for manual 2FA completion.
• Bank changed their login page: The script may need updating. Run beanscrape teach <bank-id> to recapture the login flow and regenerate the script.

No transactions returned

• Date range: Some scripts only fetch recent transactions. Check the script or run with --debug to see what date range is being queried.
• Account selection: If the bank has multiple accounts, the script may default to the first one. Check the script source.
• Page structure changed: Bank websites change frequently. The script may need updating.

Script errors

Run with --debug for detailed error output:

$ beanscrape run ./amex.csx --debug

Common issues:

• Selector not found: The bank’s HTML structure changed. Update the script.
• Timeout: The page took too long to load. Try running again; bank websites can be slow.

Browser state issues

Beanscrape saves browser session state (cookies, etc.) between runs. If you’re having persistent issues:

1. Clear browser state:

2. Delete the contents of this directory and re-run.

Getting help

• Community forum
• Email: [email protected]