Get started with the Expense Sorted app

Install es (macOS)

Primary CLI path is a macOS tarball from GitHub Releases with a prebuilt native SQLite binding. Put es on your PATH.

1. Install Node.js 20 or 22 LTS (required on PATH). Prefer matching the Node major used when the tarball was built (releases target 22). nodejs.org
2. Download the asset for your Mac from GitHub Releases: es-macos-arm64-*.tar.gz (Apple Silicon) or es-macos-x64-*.tar.gz (Intel).
3. Extract and add bin to PATH, then verify:

mkdir -p ~/opt
tar -xzf ~/Downloads/es-macos-arm64-*.tar.gz -C ~/opt
# folder name looks like: es-macos-arm64-0.0.1
export PATH="$HOME/opt/es-macos-arm64-0.0.1/bin:$PATH"
# or symlink: ln -sfn "$HOME/opt/es-macos-arm64-0.0.1" "$HOME/opt/es"
#            export PATH="$HOME/opt/es/bin:$PATH"
hash -r
es help

Deep packaging, signing, monorepo build, and smoke helpers: docs/INSTALL_LOCAL.md on GitHub (maintainer SoT — not required for the app path above).

The desktop app is the default path — download from the product page. Windows CLI tarball is not the primary path yet.

Activate license / trial (CLI)

Prefer the app: Settings → License. Trial and purchase keys are emailed to you (signed tokens). There is no machine fingerprint and no phone-home for your transactions. CLI does not self-mint licenses.

• Desktop: paste the key when prompted, or open Settings → License.
• CLI: run es doctor first — it shows which database was discovered and your license tier. If you are on Free, es license activate applies Pro in one step: it reuses your Desktop sign-in when present, syncs entitled cloud accounts, or prints the next step.

export ES_DB="$HOME/Library/Application Support/com.fstrauf.expensedesktop/expensedesktop.db"   # advanced: only to force a specific DB
es license set 'YOUR_KEY_HERE'

# Existing Desktop / Sheets / AI customers (API key):
export ES_API_KEY='your-desktop-api-key'
es license sync

Already a cloud customer? es license activate auto-discovers your Desktop API key and syncs. Need a trial? Start 14-day free Pro trial on the product page (email mint). Buy Local Pro lifetime from pricing.

Prepare local AI (Pro)

Local Pro categorize and semantic search need a one-time MiniLM model on disk (~23MB under ~/.expensesorted/models/). Free skips this and stays rules-only. License alone does not download the model.

Skip the ES_DB line below unless you need to force a specific database — discovery finds the Desktop profile DB on its own.

export ES_DB="$HOME/Library/Application Support/com.fstrauf.expensedesktop/expensedesktop.db"   # only to force a specific DB
es doctor              # should say Next: es embed setup when Pro + model missing
es embed setup         # download/warm model once
es embed backfill      # optional: vectorize existing history for personal NN
es doctor              # green: Local Pro AI ready

After setup, restart MCP clients so long-lived es mcp processes see the model. Use es embed setup --backfill to warm and backfill in one step.

MCP config

Print a Claude Desktop / Cursor snippet and paste it into your client. Leave ES_DB empty and the engine discovers your Desktop profile database automatically. Set an absolute SQLite path only for multi-DB or non-Desktop setups.

es mcp --print-config

Example shape (discovery — ES_DB empty):

{
  "mcpServers": {
    "expense-sorted": {
      "command": "es",
      "args": ["mcp"],
      "env": {
        "ES_DB": ""
      }
    }
  }
}

First workflow (MCP tools)

Honest cold path against your local DB. Import and categorize default to dry-run (apply: false) until you confirm.

1. 1

   es_status

   Confirm DB path, counts, and license tier.

2. 2

   es_import_csv

   Import a bank CSV (path or text). Start with apply: false (dry-run), then apply: true when the mapping looks right.

3. 3

   es_categorize

   Suggest categories. Start with apply: false; Free uses rules-only; Pro uses local NN after es embed setup (not rules fallback).

4. 4

   es_accept_categories

   After review, write accepted category updates (clears needs_review).

5. 5

   es_summarize / es_query

   Totals by category/month, or filter transactions — no free-form SQL.

Default: use the Desktop app for import and categorize on the same file — no MCP required.

Free vs Pro