A CLI to import MoneyMoney transactions into Actual Budget, written in TypeScript
Install with NPM:
$ npm i -g actual-moneymoney
The application will be accessible as a CLI tool with the name actual-monmon
.
Details on parameters are available by running actual-monmon --help
.
The application needs to be configured with a TOML document in order to function. You can validate the configuration details by running actual-monmon validate
. Running this for the first time will create an example configuration and print the path. You can pass a custom configuration with the --config
parameter.
A configuration document looks like this:
# Payee transformation
[payeeTransformation]
enabled = false
openAiApiKey = "<openAiKey>"
# Import settings
[import]
importUncheckedTransactions = true
# Actual servers, you can add multiple servers
[[actualServers]]
serverUrl = "http://localhost:5006"
serverPassword = "<password>"
# Budgets for the server, you can add multiple budgets
[[actualServers.budgets]]
syncId = "<syncId>" # Get this value from the Actual advanced settings
# E2E encryption for the budget, if enabled
[actualServers.budgets.e2eEncryption]
enabled = false
password = ""
# Account map for the budget
[actualServers.budgets.accountMapping]
# The key is either the account name, or the account number of a MoneyMoney account
# The value is the account name or the account id (from the url) of the Actual account
"<monMonAcc>" = "<actualAcc>"
A short summary:
Once you have configured your importer, run actual-monmon verify
to verify that the configuration has the correct format.
Once configured, importing is as simple as running actual-monmon import
. Make sure that the Actual servers are running and that MoneyMoney is unlocked. By default, the importer will import 1 month worth of transactions. You can override this by passing the --from
property, like so: actual-monmon import --from=2024-01-01
.
The importer will not track previous imports, so if you wait more than one month between imports, you might need to manually specify the last import date. Running the importer twice in the same month is no problem, as duplicate transactions will automatically be detected and skipped.
The following configuration options can optionally be added
Ignore patterns allow you to specify payee names, comments, or purposes which should be ignored. Note: Currently, the strings are treated as is, meaning they are case-sensitive, and will be checked for inclusion, not exact matches.
[import.ignorePatterns]
commentPatterns = ["[actual-ignore]"]
payeePatterns = []
purposePatterns = []
The above configuration would ignore all transactions that have a comment containing the string [actual-ignore]
.
Each budget can specify an earliest import date. This can be useful when starting to use the importer with an already existing budget in order to prevent duplicates from being imported. The importer will ignore any transactions from before the specified date.
[[actualServers.budgets]]
earliestImportDate = "2024-01-01" # Format is YYYY-MM-DD
Note that the date is a string, not a TOML date.
If you notice any bugs or issues, please file an issue.