BetterOff CLI

Read your BetterOff household from the terminal: accounts, net worth, transactions, spending, cash flow, recurring bills, portfolio, and debts.

The CLI is read-only. It cannot move money, change records, or approve anything. It runs on macOS, Linux, and Windows.

$ betteroff accounts
Display name                  Balance     Available balance  Balance as of     Type
Everyday Checking (...1234)   $4,210.55   $4,190.55          2026-10-22 16:00  depository
High-Yield Savings (...8841)  $18,250.00  $18,250.00         2026-10-22 16:00  depository
Rewards Visa (...0912)        $612.40     $9,387.60          2026-10-22 16:00  credit
Brokerage (...5530)           $52,318.09  $1,204.11          2026-10-22 16:00  investment
Solana Wallet (...7xQp)       $88.12      -                  2026-10-22 16:00  crypto
2 more columns hidden; use --json for everything

As of 2026-10-22 16:00 UTC

The accounts above are made up.

Before you start

You need a BetterOff account with the accounts and wallets you want to read connected, on any plan, including Free. Some commands need the Better plan. Every member of the household must turn on Chat data access in BetterOff's Settings before any agent, this CLI included, can read household data.

Install

With Homebrew on macOS or Linux:

brew install betteroff-finance/tap/betteroff

Or download the install script at a fixed commit and inspect it before running:

installer="$(mktemp)"
curl --proto '=https' --tlsv1.2 -fsSL \
  https://raw.githubusercontent.com/betteroff-finance/betteroff.cli/5b51b59219af5845e25c948d78469909bf6363e8/install.sh \
  -o "$installer" && cat "$installer"

After reviewing the downloaded script, run it in the same shell:

sh "$installer"
rm -f "$installer"

The commit pins the installer, not the release it downloads. Review changes before updating this pin.

The script downloads the binary for your system from the latest release into ~/.local/bin and refuses to install it unless it matches the release's SHA256SUMS. If the GitHub CLI is installed and signed in, it also checks the binary's build provenance, which proves it was built by this repository's release workflow. Set BETTEROFF_VERSION=0.1.2 for a specific version or BETTEROFF_INSTALL_DIR for another folder.

You can also download a binary from the release page and compare it with SHA256SUMS. The macOS binaries are signed with a Developer ID and notarized by Apple, so Gatekeeper accepts them. A browser download is not executable yet; run chmod +x on it first. On Windows, download betteroff-windows-x64.exe.

To check any release binary yourself:

gh attestation verify betteroff-darwin-arm64 --repo raintree-technology/betteroff.cli

From source

With Bun 1.4.3 or later:

git clone https://github.com/betteroff-finance/betteroff.cli.git
cd betteroff.cli
bun install --frozen-lockfile
bun run build   # writes dist/betteroff

Sign in

betteroff login

Your browser opens BetterOff's sign-in and consent page. Approve the BetterOff CLI, and the browser hands a one-time code back to the CLI on 127.0.0.1; the CLI never sees your password. The CLI can ask only for read access, and it renews its access on its own for up to 30 days. You can end it at any time under Settings > Agent connections in BetterOff, or with betteroff logout.

Over SSH, the browser runs on your own computer, so its redirect to 127.0.0.1 cannot reach the CLI. betteroff login notices the SSH session and prints the link instead of opening a browser. Open it on your computer and approve; the browser then shows a page that cannot connect. Copy the full address from its address bar and paste it into the terminal. The address only works with the login that is waiting for it.

The sign-in is saved in your system keychain: macOS Keychain (through Apple's security tool, so upgrades never prompt for access), libsecret on Linux, or Windows Credential Manager. betteroff status shows how the CLI is signed in.

With an API token

For CI, or a machine whose keychain is locked:

1. In BetterOff, open Settings > API tokens and create a token with read scopes only.
2. Set BETTEROFF_API_TOKEN to it, or run betteroff login --token and paste it to save it in the keychain.

Use

betteroff overview
betteroff accounts
betteroff transactions --merchant "whole foods" --all-time
betteroff transactions --start-date 2026-09-01 --end-date 2026-09-30 --traits travel
betteroff analyze-spending
betteroff recurring
betteroff portfolio --group-by account
betteroff net-worth-history
betteroff debts

Run betteroff --help for every command and betteroff <command> --help for its flags.

In a terminal, results print as tables and labeled fields, with paging, data quality, and freshness notes at the end. When output is piped, or with --json, the CLI prints the exact JSON result, so it works in scripts and as a tool for AI agents:

betteroff recurring --json | jq '.data'

Lists are paged. When there is more, the footer prints the --cursor value for the next page.

This is the beginning of the README. Read the rest at the original. Read the full README ↗