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.
@@ -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
+ [![PyPI](https://img.shields.io/pypi/v/moneymoney-cli.svg)](https://pypi.org/project/moneymoney-cli/)
32
+ [![Python](https://img.shields.io/pypi/pyversions/moneymoney-cli.svg)](https://pypi.org/project/moneymoney-cli/)
33
+ [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./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
+ [![PyPI](https://img.shields.io/pypi/v/moneymoney-cli.svg)](https://pypi.org/project/moneymoney-cli/)
4
+ [![Python](https://img.shields.io/pypi/pyversions/moneymoney-cli.svg)](https://pypi.org/project/moneymoney-cli/)
5
+ [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./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).