moneymoney-cli 0.1.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- moneymoney_cli-0.1.0/.gitignore +26 -0
- moneymoney_cli-0.1.0/CHANGELOG.md +21 -0
- moneymoney_cli-0.1.0/LICENSE +21 -0
- moneymoney_cli-0.1.0/PKG-INFO +334 -0
- moneymoney_cli-0.1.0/README.md +306 -0
- moneymoney_cli-0.1.0/cliff.toml +51 -0
- moneymoney_cli-0.1.0/mm_cli/__init__.py +3 -0
- moneymoney_cli-0.1.0/mm_cli/analysis.py +678 -0
- moneymoney_cli-0.1.0/mm_cli/applescript.py +674 -0
- moneymoney_cli-0.1.0/mm_cli/cli.py +1657 -0
- moneymoney_cli-0.1.0/mm_cli/config.py +91 -0
- moneymoney_cli-0.1.0/mm_cli/models.py +343 -0
- moneymoney_cli-0.1.0/mm_cli/output.py +1202 -0
- moneymoney_cli-0.1.0/mm_cli/rules.py +251 -0
- moneymoney_cli-0.1.0/pyproject.toml +73 -0
|
@@ -0,0 +1,26 @@
|
|
|
1
|
+
# Python-generated files
|
|
2
|
+
__pycache__/
|
|
3
|
+
*.py[oc]
|
|
4
|
+
build/
|
|
5
|
+
dist/
|
|
6
|
+
wheels/
|
|
7
|
+
*.egg-info
|
|
8
|
+
|
|
9
|
+
# Virtual environments
|
|
10
|
+
.venv
|
|
11
|
+
|
|
12
|
+
# IDE
|
|
13
|
+
.idea/
|
|
14
|
+
.vscode/
|
|
15
|
+
*.swp
|
|
16
|
+
|
|
17
|
+
# Testing
|
|
18
|
+
.coverage
|
|
19
|
+
htmlcov/
|
|
20
|
+
.pytest_cache/
|
|
21
|
+
|
|
22
|
+
# uv
|
|
23
|
+
uv.lock
|
|
24
|
+
|
|
25
|
+
# Claude Code
|
|
26
|
+
.claude
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
## [0.1.0] - 2026-04-16
|
|
4
|
+
|
|
5
|
+
### Added
|
|
6
|
+
- Initial PyPI release as `moneymoney-cli`
|
|
7
|
+
- `mm accounts` — list accounts with balances, hierarchy, and group filtering
|
|
8
|
+
- `mm transactions` — fetch transactions with date ranges, categories, amount filters, sorting, and checkmark filters
|
|
9
|
+
- `mm categories` — view categories with hierarchy and rules
|
|
10
|
+
- `mm category-usage` — show categories ranked by usage
|
|
11
|
+
- `mm set-category`, `mm set-checkmark`, `mm set-comment` — reconciliation workflows
|
|
12
|
+
- `mm analyze spending/cashflow/recurring/merchants/top-customers/balance-history` — financial analysis with transfer filtering and period comparison
|
|
13
|
+
- `mm portfolio` — investment portfolio across depot accounts
|
|
14
|
+
- `mm transfer` — initiate SEPA transfers with dry-run, outbox, and confirmation modes
|
|
15
|
+
- `mm export` — export to MT940/STA, CSV, OFX, CAMT.053, XLS, Numbers
|
|
16
|
+
- `mm suggest-rules` — suggest MoneyMoney categorization rules from uncategorized transactions
|
|
17
|
+
- `mm init` — interactive setup for transfer category and excluded account groups
|
|
18
|
+
- XDG-compliant config at `$XDG_CONFIG_HOME/mm-cli/config.toml` (fallback `~/.config/mm-cli/config.toml`)
|
|
19
|
+
- Global `--version` flag
|
|
20
|
+
- Output formats: `table` (default), `json`, `csv` on all commands
|
|
21
|
+
- MIT license
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Malte Sussdorff
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1,334 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: moneymoney-cli
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: CLI tool for MoneyMoney macOS app - retrieve accounts, transactions, categories and manage categorization via AppleScript
|
|
5
|
+
Project-URL: Homepage, https://github.com/sussdorff/mm-cli
|
|
6
|
+
Project-URL: Repository, https://github.com/sussdorff/mm-cli
|
|
7
|
+
Project-URL: Issues, https://github.com/sussdorff/mm-cli/issues
|
|
8
|
+
Project-URL: Changelog, https://github.com/sussdorff/mm-cli/blob/main/CHANGELOG.md
|
|
9
|
+
Author: Malte Sussdorff
|
|
10
|
+
License-Expression: MIT
|
|
11
|
+
License-File: LICENSE
|
|
12
|
+
Keywords: applescript,banking,cli,finance,macos,moneymoney
|
|
13
|
+
Classifier: Environment :: Console
|
|
14
|
+
Classifier: Intended Audience :: End Users/Desktop
|
|
15
|
+
Classifier: License :: OSI Approved :: MIT License
|
|
16
|
+
Classifier: Operating System :: MacOS
|
|
17
|
+
Classifier: Operating System :: MacOS :: MacOS X
|
|
18
|
+
Classifier: Programming Language :: Python :: 3
|
|
19
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
20
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
21
|
+
Classifier: Programming Language :: Python :: 3.14
|
|
22
|
+
Classifier: Topic :: Office/Business :: Financial :: Accounting
|
|
23
|
+
Classifier: Topic :: Utilities
|
|
24
|
+
Requires-Python: >=3.12
|
|
25
|
+
Requires-Dist: rich>=13.0.0
|
|
26
|
+
Requires-Dist: typer>=0.15.0
|
|
27
|
+
Description-Content-Type: text/markdown
|
|
28
|
+
|
|
29
|
+
# mm-cli
|
|
30
|
+
|
|
31
|
+
[](https://pypi.org/project/moneymoney-cli/)
|
|
32
|
+
[](https://pypi.org/project/moneymoney-cli/)
|
|
33
|
+
[](./LICENSE)
|
|
34
|
+
|
|
35
|
+
A command-line interface for [MoneyMoney](https://moneymoney-app.com/) on macOS. Talks to MoneyMoney via AppleScript to give you fast, scriptable access to your accounts, transactions, and categories — directly from the terminal.
|
|
36
|
+
|
|
37
|
+
> **PyPI package name:** `moneymoney-cli`. The command (after install) is `mm`, and the Python import name is `mm_cli`.
|
|
38
|
+
|
|
39
|
+
## Quickstart
|
|
40
|
+
|
|
41
|
+
```bash
|
|
42
|
+
# 1. Install (globally, via uv)
|
|
43
|
+
uv tool install moneymoney-cli
|
|
44
|
+
|
|
45
|
+
# 2. Launch MoneyMoney and unlock it
|
|
46
|
+
open -a MoneyMoney
|
|
47
|
+
|
|
48
|
+
# 3. Try it
|
|
49
|
+
mm accounts
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
On first run, macOS will ask whether `osascript` may control MoneyMoney. Approve it — otherwise every command will fail with a permissions error. You can manage this later under *System Settings → Privacy & Security → Automation*.
|
|
53
|
+
|
|
54
|
+
## Requirements
|
|
55
|
+
|
|
56
|
+
- macOS (required for AppleScript)
|
|
57
|
+
- [MoneyMoney](https://moneymoney-app.com/) installed and unlocked
|
|
58
|
+
- Python 3.12+ (installed automatically by `uv tool install`)
|
|
59
|
+
|
|
60
|
+
## Installation
|
|
61
|
+
|
|
62
|
+
### From PyPI (recommended)
|
|
63
|
+
|
|
64
|
+
```bash
|
|
65
|
+
uv tool install moneymoney-cli
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
This installs the `mm` command globally via [`uv`](https://docs.astral.sh/uv/). Verify with:
|
|
69
|
+
|
|
70
|
+
```bash
|
|
71
|
+
mm --version
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
If `mm` is not on your `PATH` yet, add the `uv` tool bin directory:
|
|
75
|
+
|
|
76
|
+
```bash
|
|
77
|
+
export PATH="$(uv tool dir --bin):$PATH"
|
|
78
|
+
```
|
|
79
|
+
|
|
80
|
+
Alternatives:
|
|
81
|
+
|
|
82
|
+
```bash
|
|
83
|
+
pipx install moneymoney-cli # pipx
|
|
84
|
+
pip install moneymoney-cli # plain pip (into current venv)
|
|
85
|
+
```
|
|
86
|
+
|
|
87
|
+
### From source
|
|
88
|
+
|
|
89
|
+
```bash
|
|
90
|
+
git clone https://github.com/sussdorff/mm-cli.git
|
|
91
|
+
cd mm-cli
|
|
92
|
+
uv sync
|
|
93
|
+
uv run mm --help
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
For an editable global install during development:
|
|
97
|
+
|
|
98
|
+
```bash
|
|
99
|
+
uv tool install --editable .
|
|
100
|
+
```
|
|
101
|
+
|
|
102
|
+
Re-run with `--force` after changing `pyproject.toml`.
|
|
103
|
+
|
|
104
|
+
All commands are available via `mm`. Run `mm --help` for a full list, or `mm <command> --help` for details on any command.
|
|
105
|
+
|
|
106
|
+
## Configuration
|
|
107
|
+
|
|
108
|
+
Run `mm init` to set up your personal configuration:
|
|
109
|
+
|
|
110
|
+
```bash
|
|
111
|
+
mm init
|
|
112
|
+
```
|
|
113
|
+
|
|
114
|
+
This interactive command reads your MoneyMoney categories and account groups, then asks you to configure:
|
|
115
|
+
|
|
116
|
+
- **Transfer category**: The top-level category group containing internal transfers (e.g., transfers between your own accounts, credit card settlements). Transactions in this category are excluded from analysis by default.
|
|
117
|
+
- **Excluded account groups**: Account groups to hide when using `--active` (e.g., a group for closed/dissolved accounts).
|
|
118
|
+
|
|
119
|
+
Configuration is saved to `$XDG_CONFIG_HOME/mm-cli/config.toml` (default: `~/.config/mm-cli/config.toml`). The tool works without configuration — it just won't filter transfers or exclude account groups until you set it up.
|
|
120
|
+
|
|
121
|
+
## What you can do
|
|
122
|
+
|
|
123
|
+
### See your accounts and balances
|
|
124
|
+
|
|
125
|
+
View all accounts with their current balances, grouped by the account groups you've set up in MoneyMoney:
|
|
126
|
+
|
|
127
|
+
```bash
|
|
128
|
+
mm accounts
|
|
129
|
+
```
|
|
130
|
+
|
|
131
|
+
You can see them organized by group with subtotals using `mm accounts --hierarchy`, or focus on specific groups with `mm accounts --group Privat`. To exclude closed accounts, use `mm accounts --active` (excludes groups configured via `mm init`).
|
|
132
|
+
|
|
133
|
+
### Browse and filter transactions
|
|
134
|
+
|
|
135
|
+
Pull transactions with date ranges, category filters, or find uncategorized ones:
|
|
136
|
+
|
|
137
|
+
```bash
|
|
138
|
+
mm transactions --from 2026-01-01 --to 2026-01-31
|
|
139
|
+
mm transactions --category Lebensmittel
|
|
140
|
+
mm transactions --uncategorized
|
|
141
|
+
```
|
|
142
|
+
|
|
143
|
+
Filter by account with `--account <IBAN>`, or by account group with `--group Privat`.
|
|
144
|
+
|
|
145
|
+
You can also filter by amount range, sort results, and filter by checkmark status:
|
|
146
|
+
|
|
147
|
+
```bash
|
|
148
|
+
mm transactions --min-amount 50 --max-amount 500
|
|
149
|
+
mm transactions --sort amount # biggest first
|
|
150
|
+
mm transactions --sort date --reverse # newest first
|
|
151
|
+
mm transactions --checkmark off # only unchecked
|
|
152
|
+
```
|
|
153
|
+
|
|
154
|
+
### Analyze your finances
|
|
155
|
+
|
|
156
|
+
All analysis commands filter out internal transfers by default — both by IBAN matching against your own accounts and by the transfer category configured via `mm init`. When using `--group`, cross-group transfers (e.g. salary from your company account to your personal account) are kept as real cashflow. Use `--include-transfers` to disable filtering, or `--transfers-only` to show *only* the transfers (useful for reviewing own-account movements like credit card settlements or savings transfers).
|
|
157
|
+
|
|
158
|
+
**Spending by category** — see where your money goes, with budget tracking:
|
|
159
|
+
|
|
160
|
+
```bash
|
|
161
|
+
mm analyze spending
|
|
162
|
+
mm analyze spending --period last-month --compare
|
|
163
|
+
mm analyze spending --type expense --group Privat
|
|
164
|
+
```
|
|
165
|
+
|
|
166
|
+
**Cashflow** — income vs expenses over time:
|
|
167
|
+
|
|
168
|
+
```bash
|
|
169
|
+
mm analyze cashflow --months 6
|
|
170
|
+
mm analyze cashflow --months 12 --period quarterly
|
|
171
|
+
mm analyze cashflow --group Privat
|
|
172
|
+
```
|
|
173
|
+
|
|
174
|
+
**Recurring transactions** — detect subscriptions and standing orders:
|
|
175
|
+
|
|
176
|
+
```bash
|
|
177
|
+
mm analyze recurring --months 12
|
|
178
|
+
mm analyze recurring --min-occurrences 4
|
|
179
|
+
```
|
|
180
|
+
|
|
181
|
+
**Merchants** — top merchants by total spend:
|
|
182
|
+
|
|
183
|
+
```bash
|
|
184
|
+
mm analyze merchants
|
|
185
|
+
mm analyze merchants --type all --limit 20
|
|
186
|
+
```
|
|
187
|
+
|
|
188
|
+
**Top customers** — income grouped by counterparty:
|
|
189
|
+
|
|
190
|
+
```bash
|
|
191
|
+
mm analyze top-customers
|
|
192
|
+
mm analyze top-customers --period this-year
|
|
193
|
+
```
|
|
194
|
+
|
|
195
|
+
**Balance history** — approximate historical balance per account:
|
|
196
|
+
|
|
197
|
+
```bash
|
|
198
|
+
mm analyze balance-history --months 6
|
|
199
|
+
mm analyze balance-history --account Girokonto
|
|
200
|
+
```
|
|
201
|
+
|
|
202
|
+
### Export transactions to other formats
|
|
203
|
+
|
|
204
|
+
Export to MT940/STA (for accounting software), CSV, OFX, CAMT.053, XLS, or Numbers:
|
|
205
|
+
|
|
206
|
+
```bash
|
|
207
|
+
mm export --from 2025-01-01 --to 2025-12-31 --format csv -o ~/export.csv
|
|
208
|
+
mm export --account "DE89..." --format sta
|
|
209
|
+
```
|
|
210
|
+
|
|
211
|
+
### View investment portfolio
|
|
212
|
+
|
|
213
|
+
See your securities holdings, asset allocation, and performance across depot accounts:
|
|
214
|
+
|
|
215
|
+
```bash
|
|
216
|
+
mm portfolio
|
|
217
|
+
mm portfolio --account Depot
|
|
218
|
+
mm portfolio --format json
|
|
219
|
+
```
|
|
220
|
+
|
|
221
|
+
### Create bank transfers
|
|
222
|
+
|
|
223
|
+
Initiate SEPA transfers through MoneyMoney:
|
|
224
|
+
|
|
225
|
+
```bash
|
|
226
|
+
mm transfer -f Girokonto -t "Max Mustermann" -i DE89370400440532013000 -a 100.00 -p "Invoice 2026-001"
|
|
227
|
+
mm transfer -f Girokonto -t "Max Mustermann" -i DE89370400440532013000 -a 100.00 -p "Invoice" --dry-run
|
|
228
|
+
mm transfer -f Girokonto -t "Max Mustermann" -i DE89370400440532013000 -a 100.00 -p "Invoice" --outbox --confirm
|
|
229
|
+
```
|
|
230
|
+
|
|
231
|
+
Use `--dry-run` to preview without executing, `--confirm` to skip interactive confirmation, and `--outbox` to queue the transfer without opening the UI.
|
|
232
|
+
|
|
233
|
+
### Manage categories
|
|
234
|
+
|
|
235
|
+
View all categories with their hierarchy and existing rules:
|
|
236
|
+
|
|
237
|
+
```bash
|
|
238
|
+
mm categories
|
|
239
|
+
```
|
|
240
|
+
|
|
241
|
+
See which categories are used most (by transaction count) with `mm category-usage`.
|
|
242
|
+
|
|
243
|
+
To re-categorize a transaction:
|
|
244
|
+
|
|
245
|
+
```bash
|
|
246
|
+
mm set-category <transaction-id> Lebensmittel
|
|
247
|
+
mm set-category <transaction-id> Lebensmittel --dry-run # preview first
|
|
248
|
+
```
|
|
249
|
+
|
|
250
|
+
Mark transactions as checked or add comments for reconciliation workflows:
|
|
251
|
+
|
|
252
|
+
```bash
|
|
253
|
+
mm set-checkmark <transaction-id> on
|
|
254
|
+
mm set-checkmark <transaction-id> off
|
|
255
|
+
mm set-comment <transaction-id> "Reviewed 2026-01"
|
|
256
|
+
```
|
|
257
|
+
|
|
258
|
+
### Get rule suggestions for uncategorized transactions
|
|
259
|
+
|
|
260
|
+
Analyzes your uncategorized transactions, looks at historical patterns from already-categorized ones, and suggests MoneyMoney rules you could create:
|
|
261
|
+
|
|
262
|
+
```bash
|
|
263
|
+
mm suggest-rules --from 2026-01-01
|
|
264
|
+
mm suggest-rules --history 12 # use 12 months of history for better matches
|
|
265
|
+
```
|
|
266
|
+
|
|
267
|
+
### Output formats
|
|
268
|
+
|
|
269
|
+
Every command supports `--format table` (default), `--format json`, and `--format csv`. JSON and CSV are useful for piping into other tools:
|
|
270
|
+
|
|
271
|
+
```bash
|
|
272
|
+
mm accounts --format json | jq '.[].balance'
|
|
273
|
+
mm transactions --from 2026-01-01 --format csv > transactions.csv
|
|
274
|
+
mm analyze spending --format json | jq '.[] | select(.budget != null)'
|
|
275
|
+
```
|
|
276
|
+
|
|
277
|
+
## Troubleshooting
|
|
278
|
+
|
|
279
|
+
| Symptom | Cause / Fix |
|
|
280
|
+
|---|---|
|
|
281
|
+
| `MoneyMoney is not running` | Launch MoneyMoney (`open -a MoneyMoney`) before running `mm`. |
|
|
282
|
+
| `MoneyMoney is locked` | Unlock MoneyMoney with your password/Touch ID. |
|
|
283
|
+
| `Not authorized to send Apple events to MoneyMoney` | Approve the Automation prompt or enable it under *System Settings → Privacy & Security → Automation → Terminal/iTerm → MoneyMoney*. |
|
|
284
|
+
| `mm: command not found` after install | Add `$(uv tool dir --bin)` to your `PATH`. |
|
|
285
|
+
|
|
286
|
+
## Development
|
|
287
|
+
|
|
288
|
+
```bash
|
|
289
|
+
git clone https://github.com/sussdorff/mm-cli.git
|
|
290
|
+
cd mm-cli
|
|
291
|
+
uv sync --dev
|
|
292
|
+
uv run pytest
|
|
293
|
+
uv run ruff check .
|
|
294
|
+
```
|
|
295
|
+
|
|
296
|
+
### Release workflow
|
|
297
|
+
|
|
298
|
+
`git-cliff` is configured via [`cliff.toml`](./cliff.toml); PyPI publishing runs through GitHub Trusted Publishing via [`.github/workflows/release.yml`](./.github/workflows/release.yml).
|
|
299
|
+
|
|
300
|
+
To cut a release:
|
|
301
|
+
|
|
302
|
+
```bash
|
|
303
|
+
# Bump the version in pyproject.toml and mm_cli/__init__.py, then:
|
|
304
|
+
|
|
305
|
+
# Refresh the unreleased changelog section
|
|
306
|
+
uv run git-cliff --unreleased --prepend CHANGELOG.md
|
|
307
|
+
|
|
308
|
+
# Build sdist + wheel and sanity-check locally
|
|
309
|
+
uv build
|
|
310
|
+
uv publish --dry-run dist/*
|
|
311
|
+
|
|
312
|
+
# Commit the release metadata
|
|
313
|
+
git add CHANGELOG.md pyproject.toml mm_cli/__init__.py uv.lock
|
|
314
|
+
git commit -m "chore(release): prepare v0.2.0"
|
|
315
|
+
|
|
316
|
+
# Push a tag — the release.yml workflow runs tests, publishes to PyPI, and creates a GitHub release
|
|
317
|
+
git tag v0.2.0
|
|
318
|
+
git push origin main --follow-tags
|
|
319
|
+
```
|
|
320
|
+
|
|
321
|
+
PyPI Trusted Publishing is configured with:
|
|
322
|
+
- Project name: `moneymoney-cli`
|
|
323
|
+
- Owner: `sussdorff`
|
|
324
|
+
- Repository: `mm-cli`
|
|
325
|
+
- Workflow: `release.yml`
|
|
326
|
+
- Environment: `pypi` (configure under *Repo Settings → Environments*)
|
|
327
|
+
|
|
328
|
+
## References
|
|
329
|
+
|
|
330
|
+
- [MoneyMoney AppleScript Documentation](https://moneymoney.app/applescript/)
|
|
331
|
+
|
|
332
|
+
## License
|
|
333
|
+
|
|
334
|
+
MIT. See [`LICENSE`](./LICENSE).
|
|
@@ -0,0 +1,306 @@
|
|
|
1
|
+
# mm-cli
|
|
2
|
+
|
|
3
|
+
[](https://pypi.org/project/moneymoney-cli/)
|
|
4
|
+
[](https://pypi.org/project/moneymoney-cli/)
|
|
5
|
+
[](./LICENSE)
|
|
6
|
+
|
|
7
|
+
A command-line interface for [MoneyMoney](https://moneymoney-app.com/) on macOS. Talks to MoneyMoney via AppleScript to give you fast, scriptable access to your accounts, transactions, and categories — directly from the terminal.
|
|
8
|
+
|
|
9
|
+
> **PyPI package name:** `moneymoney-cli`. The command (after install) is `mm`, and the Python import name is `mm_cli`.
|
|
10
|
+
|
|
11
|
+
## Quickstart
|
|
12
|
+
|
|
13
|
+
```bash
|
|
14
|
+
# 1. Install (globally, via uv)
|
|
15
|
+
uv tool install moneymoney-cli
|
|
16
|
+
|
|
17
|
+
# 2. Launch MoneyMoney and unlock it
|
|
18
|
+
open -a MoneyMoney
|
|
19
|
+
|
|
20
|
+
# 3. Try it
|
|
21
|
+
mm accounts
|
|
22
|
+
```
|
|
23
|
+
|
|
24
|
+
On first run, macOS will ask whether `osascript` may control MoneyMoney. Approve it — otherwise every command will fail with a permissions error. You can manage this later under *System Settings → Privacy & Security → Automation*.
|
|
25
|
+
|
|
26
|
+
## Requirements
|
|
27
|
+
|
|
28
|
+
- macOS (required for AppleScript)
|
|
29
|
+
- [MoneyMoney](https://moneymoney-app.com/) installed and unlocked
|
|
30
|
+
- Python 3.12+ (installed automatically by `uv tool install`)
|
|
31
|
+
|
|
32
|
+
## Installation
|
|
33
|
+
|
|
34
|
+
### From PyPI (recommended)
|
|
35
|
+
|
|
36
|
+
```bash
|
|
37
|
+
uv tool install moneymoney-cli
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
This installs the `mm` command globally via [`uv`](https://docs.astral.sh/uv/). Verify with:
|
|
41
|
+
|
|
42
|
+
```bash
|
|
43
|
+
mm --version
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
If `mm` is not on your `PATH` yet, add the `uv` tool bin directory:
|
|
47
|
+
|
|
48
|
+
```bash
|
|
49
|
+
export PATH="$(uv tool dir --bin):$PATH"
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
Alternatives:
|
|
53
|
+
|
|
54
|
+
```bash
|
|
55
|
+
pipx install moneymoney-cli # pipx
|
|
56
|
+
pip install moneymoney-cli # plain pip (into current venv)
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
### From source
|
|
60
|
+
|
|
61
|
+
```bash
|
|
62
|
+
git clone https://github.com/sussdorff/mm-cli.git
|
|
63
|
+
cd mm-cli
|
|
64
|
+
uv sync
|
|
65
|
+
uv run mm --help
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
For an editable global install during development:
|
|
69
|
+
|
|
70
|
+
```bash
|
|
71
|
+
uv tool install --editable .
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
Re-run with `--force` after changing `pyproject.toml`.
|
|
75
|
+
|
|
76
|
+
All commands are available via `mm`. Run `mm --help` for a full list, or `mm <command> --help` for details on any command.
|
|
77
|
+
|
|
78
|
+
## Configuration
|
|
79
|
+
|
|
80
|
+
Run `mm init` to set up your personal configuration:
|
|
81
|
+
|
|
82
|
+
```bash
|
|
83
|
+
mm init
|
|
84
|
+
```
|
|
85
|
+
|
|
86
|
+
This interactive command reads your MoneyMoney categories and account groups, then asks you to configure:
|
|
87
|
+
|
|
88
|
+
- **Transfer category**: The top-level category group containing internal transfers (e.g., transfers between your own accounts, credit card settlements). Transactions in this category are excluded from analysis by default.
|
|
89
|
+
- **Excluded account groups**: Account groups to hide when using `--active` (e.g., a group for closed/dissolved accounts).
|
|
90
|
+
|
|
91
|
+
Configuration is saved to `$XDG_CONFIG_HOME/mm-cli/config.toml` (default: `~/.config/mm-cli/config.toml`). The tool works without configuration — it just won't filter transfers or exclude account groups until you set it up.
|
|
92
|
+
|
|
93
|
+
## What you can do
|
|
94
|
+
|
|
95
|
+
### See your accounts and balances
|
|
96
|
+
|
|
97
|
+
View all accounts with their current balances, grouped by the account groups you've set up in MoneyMoney:
|
|
98
|
+
|
|
99
|
+
```bash
|
|
100
|
+
mm accounts
|
|
101
|
+
```
|
|
102
|
+
|
|
103
|
+
You can see them organized by group with subtotals using `mm accounts --hierarchy`, or focus on specific groups with `mm accounts --group Privat`. To exclude closed accounts, use `mm accounts --active` (excludes groups configured via `mm init`).
|
|
104
|
+
|
|
105
|
+
### Browse and filter transactions
|
|
106
|
+
|
|
107
|
+
Pull transactions with date ranges, category filters, or find uncategorized ones:
|
|
108
|
+
|
|
109
|
+
```bash
|
|
110
|
+
mm transactions --from 2026-01-01 --to 2026-01-31
|
|
111
|
+
mm transactions --category Lebensmittel
|
|
112
|
+
mm transactions --uncategorized
|
|
113
|
+
```
|
|
114
|
+
|
|
115
|
+
Filter by account with `--account <IBAN>`, or by account group with `--group Privat`.
|
|
116
|
+
|
|
117
|
+
You can also filter by amount range, sort results, and filter by checkmark status:
|
|
118
|
+
|
|
119
|
+
```bash
|
|
120
|
+
mm transactions --min-amount 50 --max-amount 500
|
|
121
|
+
mm transactions --sort amount # biggest first
|
|
122
|
+
mm transactions --sort date --reverse # newest first
|
|
123
|
+
mm transactions --checkmark off # only unchecked
|
|
124
|
+
```
|
|
125
|
+
|
|
126
|
+
### Analyze your finances
|
|
127
|
+
|
|
128
|
+
All analysis commands filter out internal transfers by default — both by IBAN matching against your own accounts and by the transfer category configured via `mm init`. When using `--group`, cross-group transfers (e.g. salary from your company account to your personal account) are kept as real cashflow. Use `--include-transfers` to disable filtering, or `--transfers-only` to show *only* the transfers (useful for reviewing own-account movements like credit card settlements or savings transfers).
|
|
129
|
+
|
|
130
|
+
**Spending by category** — see where your money goes, with budget tracking:
|
|
131
|
+
|
|
132
|
+
```bash
|
|
133
|
+
mm analyze spending
|
|
134
|
+
mm analyze spending --period last-month --compare
|
|
135
|
+
mm analyze spending --type expense --group Privat
|
|
136
|
+
```
|
|
137
|
+
|
|
138
|
+
**Cashflow** — income vs expenses over time:
|
|
139
|
+
|
|
140
|
+
```bash
|
|
141
|
+
mm analyze cashflow --months 6
|
|
142
|
+
mm analyze cashflow --months 12 --period quarterly
|
|
143
|
+
mm analyze cashflow --group Privat
|
|
144
|
+
```
|
|
145
|
+
|
|
146
|
+
**Recurring transactions** — detect subscriptions and standing orders:
|
|
147
|
+
|
|
148
|
+
```bash
|
|
149
|
+
mm analyze recurring --months 12
|
|
150
|
+
mm analyze recurring --min-occurrences 4
|
|
151
|
+
```
|
|
152
|
+
|
|
153
|
+
**Merchants** — top merchants by total spend:
|
|
154
|
+
|
|
155
|
+
```bash
|
|
156
|
+
mm analyze merchants
|
|
157
|
+
mm analyze merchants --type all --limit 20
|
|
158
|
+
```
|
|
159
|
+
|
|
160
|
+
**Top customers** — income grouped by counterparty:
|
|
161
|
+
|
|
162
|
+
```bash
|
|
163
|
+
mm analyze top-customers
|
|
164
|
+
mm analyze top-customers --period this-year
|
|
165
|
+
```
|
|
166
|
+
|
|
167
|
+
**Balance history** — approximate historical balance per account:
|
|
168
|
+
|
|
169
|
+
```bash
|
|
170
|
+
mm analyze balance-history --months 6
|
|
171
|
+
mm analyze balance-history --account Girokonto
|
|
172
|
+
```
|
|
173
|
+
|
|
174
|
+
### Export transactions to other formats
|
|
175
|
+
|
|
176
|
+
Export to MT940/STA (for accounting software), CSV, OFX, CAMT.053, XLS, or Numbers:
|
|
177
|
+
|
|
178
|
+
```bash
|
|
179
|
+
mm export --from 2025-01-01 --to 2025-12-31 --format csv -o ~/export.csv
|
|
180
|
+
mm export --account "DE89..." --format sta
|
|
181
|
+
```
|
|
182
|
+
|
|
183
|
+
### View investment portfolio
|
|
184
|
+
|
|
185
|
+
See your securities holdings, asset allocation, and performance across depot accounts:
|
|
186
|
+
|
|
187
|
+
```bash
|
|
188
|
+
mm portfolio
|
|
189
|
+
mm portfolio --account Depot
|
|
190
|
+
mm portfolio --format json
|
|
191
|
+
```
|
|
192
|
+
|
|
193
|
+
### Create bank transfers
|
|
194
|
+
|
|
195
|
+
Initiate SEPA transfers through MoneyMoney:
|
|
196
|
+
|
|
197
|
+
```bash
|
|
198
|
+
mm transfer -f Girokonto -t "Max Mustermann" -i DE89370400440532013000 -a 100.00 -p "Invoice 2026-001"
|
|
199
|
+
mm transfer -f Girokonto -t "Max Mustermann" -i DE89370400440532013000 -a 100.00 -p "Invoice" --dry-run
|
|
200
|
+
mm transfer -f Girokonto -t "Max Mustermann" -i DE89370400440532013000 -a 100.00 -p "Invoice" --outbox --confirm
|
|
201
|
+
```
|
|
202
|
+
|
|
203
|
+
Use `--dry-run` to preview without executing, `--confirm` to skip interactive confirmation, and `--outbox` to queue the transfer without opening the UI.
|
|
204
|
+
|
|
205
|
+
### Manage categories
|
|
206
|
+
|
|
207
|
+
View all categories with their hierarchy and existing rules:
|
|
208
|
+
|
|
209
|
+
```bash
|
|
210
|
+
mm categories
|
|
211
|
+
```
|
|
212
|
+
|
|
213
|
+
See which categories are used most (by transaction count) with `mm category-usage`.
|
|
214
|
+
|
|
215
|
+
To re-categorize a transaction:
|
|
216
|
+
|
|
217
|
+
```bash
|
|
218
|
+
mm set-category <transaction-id> Lebensmittel
|
|
219
|
+
mm set-category <transaction-id> Lebensmittel --dry-run # preview first
|
|
220
|
+
```
|
|
221
|
+
|
|
222
|
+
Mark transactions as checked or add comments for reconciliation workflows:
|
|
223
|
+
|
|
224
|
+
```bash
|
|
225
|
+
mm set-checkmark <transaction-id> on
|
|
226
|
+
mm set-checkmark <transaction-id> off
|
|
227
|
+
mm set-comment <transaction-id> "Reviewed 2026-01"
|
|
228
|
+
```
|
|
229
|
+
|
|
230
|
+
### Get rule suggestions for uncategorized transactions
|
|
231
|
+
|
|
232
|
+
Analyzes your uncategorized transactions, looks at historical patterns from already-categorized ones, and suggests MoneyMoney rules you could create:
|
|
233
|
+
|
|
234
|
+
```bash
|
|
235
|
+
mm suggest-rules --from 2026-01-01
|
|
236
|
+
mm suggest-rules --history 12 # use 12 months of history for better matches
|
|
237
|
+
```
|
|
238
|
+
|
|
239
|
+
### Output formats
|
|
240
|
+
|
|
241
|
+
Every command supports `--format table` (default), `--format json`, and `--format csv`. JSON and CSV are useful for piping into other tools:
|
|
242
|
+
|
|
243
|
+
```bash
|
|
244
|
+
mm accounts --format json | jq '.[].balance'
|
|
245
|
+
mm transactions --from 2026-01-01 --format csv > transactions.csv
|
|
246
|
+
mm analyze spending --format json | jq '.[] | select(.budget != null)'
|
|
247
|
+
```
|
|
248
|
+
|
|
249
|
+
## Troubleshooting
|
|
250
|
+
|
|
251
|
+
| Symptom | Cause / Fix |
|
|
252
|
+
|---|---|
|
|
253
|
+
| `MoneyMoney is not running` | Launch MoneyMoney (`open -a MoneyMoney`) before running `mm`. |
|
|
254
|
+
| `MoneyMoney is locked` | Unlock MoneyMoney with your password/Touch ID. |
|
|
255
|
+
| `Not authorized to send Apple events to MoneyMoney` | Approve the Automation prompt or enable it under *System Settings → Privacy & Security → Automation → Terminal/iTerm → MoneyMoney*. |
|
|
256
|
+
| `mm: command not found` after install | Add `$(uv tool dir --bin)` to your `PATH`. |
|
|
257
|
+
|
|
258
|
+
## Development
|
|
259
|
+
|
|
260
|
+
```bash
|
|
261
|
+
git clone https://github.com/sussdorff/mm-cli.git
|
|
262
|
+
cd mm-cli
|
|
263
|
+
uv sync --dev
|
|
264
|
+
uv run pytest
|
|
265
|
+
uv run ruff check .
|
|
266
|
+
```
|
|
267
|
+
|
|
268
|
+
### Release workflow
|
|
269
|
+
|
|
270
|
+
`git-cliff` is configured via [`cliff.toml`](./cliff.toml); PyPI publishing runs through GitHub Trusted Publishing via [`.github/workflows/release.yml`](./.github/workflows/release.yml).
|
|
271
|
+
|
|
272
|
+
To cut a release:
|
|
273
|
+
|
|
274
|
+
```bash
|
|
275
|
+
# Bump the version in pyproject.toml and mm_cli/__init__.py, then:
|
|
276
|
+
|
|
277
|
+
# Refresh the unreleased changelog section
|
|
278
|
+
uv run git-cliff --unreleased --prepend CHANGELOG.md
|
|
279
|
+
|
|
280
|
+
# Build sdist + wheel and sanity-check locally
|
|
281
|
+
uv build
|
|
282
|
+
uv publish --dry-run dist/*
|
|
283
|
+
|
|
284
|
+
# Commit the release metadata
|
|
285
|
+
git add CHANGELOG.md pyproject.toml mm_cli/__init__.py uv.lock
|
|
286
|
+
git commit -m "chore(release): prepare v0.2.0"
|
|
287
|
+
|
|
288
|
+
# Push a tag — the release.yml workflow runs tests, publishes to PyPI, and creates a GitHub release
|
|
289
|
+
git tag v0.2.0
|
|
290
|
+
git push origin main --follow-tags
|
|
291
|
+
```
|
|
292
|
+
|
|
293
|
+
PyPI Trusted Publishing is configured with:
|
|
294
|
+
- Project name: `moneymoney-cli`
|
|
295
|
+
- Owner: `sussdorff`
|
|
296
|
+
- Repository: `mm-cli`
|
|
297
|
+
- Workflow: `release.yml`
|
|
298
|
+
- Environment: `pypi` (configure under *Repo Settings → Environments*)
|
|
299
|
+
|
|
300
|
+
## References
|
|
301
|
+
|
|
302
|
+
- [MoneyMoney AppleScript Documentation](https://moneymoney.app/applescript/)
|
|
303
|
+
|
|
304
|
+
## License
|
|
305
|
+
|
|
306
|
+
MIT. See [`LICENSE`](./LICENSE).
|