![\"Actual-MoneyMoney](\"./assets/actual-moneymoney.png\")
\n\n \n
\n A TypeScript CLI for importing MoneyMoney transactions into Actual Budget.\n
\n\n\n\n> `actual-moneymoney-importer` started as a fork of [NikxDa/actual-moneymoney](https://github.com/NikxDa/actual-moneymoney) and is now actively maintained and published with added category sync, payee transformation, and richer import controls.\n\nRun `actual-mmi --help` at any time for a full list of commands and options. For per-command help, use `actual-mmi import --help` or `actual-mmi categories map --help`.\n\n## Contents\n\n- [Highlights](#highlights)\n- [Requirements](#requirements)\n- [Installation](#installation)\n- [Quick Start](#quick-start)\n- [Configuration](#configuration)\n - [Environment variables](#environment-variables)\n - [Required configuration](#required-configuration)\n - [Import settings](#import-settings)\n - [Comment import](#comment-import)\n- [Usage](#usage)\n - [Date ranges](#date-ranges)\n - [Scoped imports](#scoped-imports)\n - [Dry run](#dry-run)\n - [Verbose logging](#verbose-logging)\n - [Validate command](#validate-command)\n- [Features](#features)\n - [Category sync](#category-sync)\n - [Payee transformation](#payee-transformation)\n - [Automatic transfers](#automatic-transfers)\n- [Advanced configuration](#advanced-configuration)\n - [Ignore patterns](#ignore-patterns)\n - [Earliest import date](#earliest-import-date)\n- [Security](#security)\n- [Troubleshooting](#troubleshooting)\n- [Support](#support)\n- [Contributing and releases](#contributing-and-releases)\n\n## Highlights\n\n- π·οΈ **Category sync** β map MoneyMoney categories to Actual automatically, with backfill and conflict resolution\n- πΊοΈ **`categories map` CLI** β audit, plan, and write your category mapping from the terminal\n- β οΈ **Auto-rule override detection** β get warned when Actual's rules silently change a synced category\n- π¬ **Scoped imports** β filter by server, budget, or account with repeatable `-s`/`-b`/`-a` flags\n- π€ **AI payee transformation** β configurable prompt, OpenAI or on-device Apple Intelligence, temperature, and error-handling policy\n- π¬ **Comment import** β carry MoneyMoney transaction comments into Actual notes (with configurable prefix)\n\n## Requirements\n\n- macOS with [MoneyMoney](https://moneymoney-app.com) installed\n- An [Actual Budget](https://actualbudget.org) server and budget\n- Node.js >= 22\n\n## Installation\n\n```bash\nnpm i -g actual-moneymoney-importer\n```\n\nThe installed CLI command is `actual-mmi`.\n\n## Quick Start\n\n1. Install the CLI:\n\n ```bash\n npm i -g actual-moneymoney-importer\n ```\n\n2. Generate an example config and print its path:\n\n ```bash\n actual-mmi validate\n ```\n\n3. Open the printed config file and fill in:\n - Actual server URL\n - Budget sync ID (from Actual β Settings β Advanced)\n - Account mapping\n\n4. Validate your config:\n\n ```bash\n actual-mmi validate\n ```\n\n5. Preview the import:\n\n ```bash\n actual-mmi import --dry-run\n ```\n\n6. Run the import:\n\n ```bash\n actual-mmi import\n ```\n\n## Configuration\n\nThe application uses a TOML configuration file. Run `actual-mmi validate` to create or check the config. Pass a custom path with `--config` (alias `-c`).\n\nSee [assets/config.example.toml](assets/config.example.toml) for a full annotated example.\n\n### Environment variables\n\nAny string config value can reference an environment variable with whole-value substitution like `${ENV_VAR}`. Partial interpolation is not supported, and missing variables fail validation and import. This is the recommended way to provide secrets:\n\n```toml\nserverPassword = \"${ACTUAL_PASSWORD}\"\nopenAiApiKey = \"${MMI_OPENAI_KEY}\"\n```\n\n### Required configuration\n\n- **Actual servers** specify which servers should be imported to\n- **Budget configurations** describe the budget files per server. The sync ID is in Actual β Settings β Advanced. If the budget is E2E encrypted, provide the password.\n- **Account mapping** maps MoneyMoney accounts to Actual accounts. MoneyMoney accounts can be identified by UUID (AppleScript API only), account number (IBAN, etc.), or name (in that order). Actual accounts by UUID (from URL) or name. If names duplicate, the first match is used.\n\nOnce configured, run `actual-mmi validate` to verify the format.\n\n### Import settings\n\n| Option | Default | Description |\n| ----------------------------- | ------------------------ | ------------------------------------------------------------------------------------------------------- |\n| `importUncheckedTransactions` | `true` | Import transactions not yet checked in MoneyMoney |\n| `synchronizeClearedStatus` | `true` | Sync MoneyMoney's cleared status to Actual |\n| `categorySync` | none | Category sync policy: `\"off\"` (don't apply), `\"new\"` (new imports only), `\"all\"` (also update existing) |\n| `importComments` | `false` | Import MoneyMoney comments into Actual notes |\n| `commentPrefix` | `\"MoneyMoney Comment: \"` | Prefix added to imported comments |\n\n### Comment import\n\nThe MoneyMoney transaction `purpose` is always written to the Actual notes field when present. When `importComments = true`, the MoneyMoney comment is appended after `|` using the configured `commentPrefix`.\n\n## Usage\n\nOnce configured, importing is as simple as running `actual-mmi import`. Make sure the Actual servers are running and MoneyMoney is unlocked. By default, the importer processes the last month of transactions.\n\n### Date ranges\n\nUse `--from=YYYY-MM-DD` (alias `-f`) and optionally `--to=YYYY-MM-DD` (alias `-t`) to import a specific date range. The importer does not remember the last successful run date, so if you wait more than one month between imports, specify `--from`. Re-running overlapping ranges is safe because imported transactions use deterministic IDs and duplicates are skipped.\n\nIf a mapped Actual account has no existing transactions, the importer creates a synthetic cleared `Starting balance` transaction so the account balance matches MoneyMoney. Its `imported_id` is `{MoneyMoney account UUID}-start`.\n\n### Scoped imports\n\nImports can be scoped with `--server` (alias `-s`), `--budget` (alias `-b`), and `--account` (alias `-a`). Each flag is case-insensitive, can be repeated, and accepts comma-separated values. Server filtering matches against the **server URL** and budget filtering matches against the **sync ID** from your config.\n\n```bash\n# Import specific accounts\nactual-mmi import -a \"DKB Giro\" -a \"DKB Visa\"\nactual-mmi import -a \"DKB Giro,DKB Visa\"\n\n# Restrict to server and budget\nactual-mmi import -s http://localhost:5006 -b![\"CI\"](\"https://github.com/1cu/actual-moneymoney-importer/actions/workflows/ci.yml/badge.svg?branch=main\"){kind=icon}
\n ![\"npm](\"https://img.shields.io/npm/v/actual-moneymoney-importer\")
\n