Get started with Expense Sorted Local

1. Install es (macOS primary)

Primary 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 cold buyer path).

Desktop app (macOS / Windows) is an optional UI over the same local DB — download from the product page. Windows CLI tarball is not the primary path yet.

2. Activate license / trial

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: es license set <key> (or run es license set and paste on stdin). Prefer an absolute ES_DB so the key lands in the same DB MCP and Desktop use.

export ES_DB="$HOME/Library/Application Support/com.fstrauf.expensedesktop/expensedesktop.db"
es license set 'YOUR_KEY_HERE'

Need a trial? Start 14-day free Pro trial on the product page (email mint). Buy Local Pro lifetime from pricing.

3. MCP config

Print a Claude Desktop / Cursor snippet and paste it into your client. Set ES_DB to an absolute SQLite path.

es mcp --print-config

Example shape (set your path):

{
  "mcpServers": {
    "expense-sorted": {
      "command": "es",
      "args": ["mcp"],
      "env": {
        "ES_DB": "/absolute/path/to/your.db"
      }
    }
  }
}

4. 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 unlocks local NN / embeddings.

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.

Alternate: use the Desktop UI for import and categorize on the same SQLite file — no MCP required.

5. Free vs Pro

6. Troubleshooting

• Gatekeeper / quarantine blocks extract

  Unsigned builds may be quarantined. Clear with xattr -dr com.apple.quarantine ~/opt/es-macos-*

• DB_NOT_FOUND / wrong database

  Set absolute ES_DB. MCP and es license set do not create a missing DB — open Desktop once or import data first. Discovery: ES_DB → desktop profile → ~/.expensesorted/data.db.

• DB_BUSY

  Another process holds a write lock (Desktop, another es mcp, daemon). Close the other writer or retry shortly.

• EMBEDDING_MODEL_MISSING

  Pro semantic / embed features need the local embedding model available. Rules categorize still works on Free.

• MCP client cannot find es

  Set command in MCP JSON to the absolute path of bin/es, not only the bare name.

• Still Free after pasting a key

  The key is stored even when verify fails (typo, wrong product, expired trial). Check es license set output for tier/verify, confirm the same ES_DB, and re-copy the full token from email.

Still stuck? Support · packaging depth: INSTALL_LOCAL.md