pp-monarch-money

Monarch Money — Printing Press CLI

前置条件：安装 CLI

此技能通过 monarch-money-pp-cli 二进制文件运行。**调用此技能中的任何命令前，必须确认 CLI 已安装。**如果尚未安装，请先安装：

1. 通过 Printing Press 安装程序安装。在 macOS/Linux 上，二进制文件默认安装到 $HOME/.local/bin；在 Windows 上，默认安装到 %LOCALAPPDATA%\Programs\PrintingPress\bin：

   npx -y @mvanhorn/printing-press-library install monarch-money --cli-only
   

2. 验证：monarch-money-pp-cli --version
3. 确保报告的安装目录位于将调用此技能的 Agent/运行时的 $PATH 中。

如果 npx 安装失败（没有 Node、处于离线状态等），则改用直接通过 Go 安装（需要 Go 1.26.6 或更高版本）：

go install github.com/mvanhorn/printing-press-library/library/payments/monarch-money/cmd/monarch-money-pp-cli@latest

如果安装后 --version 报告“command not found”，说明运行时无法通过 $PATH 找到该二进制文件目录。验证成功前，请勿执行此技能中的命令。

何时使用此 CLI

用户询问以下内容时，请使用此 CLI：

• Monarch Money 账户余额
• Monarch Money 交易标签
• 最近的 Monarch 交易或按日期筛选的 Monarch 交易
• 按月或自定义时段的现金流
• 创建、更新、添加标签或删除某笔 Monarch 交易
• 只读的特定 Monarch GraphQL 查询

不要将其用于规则更改、账户刷新、预算更改或广泛的远程写入。交易写入仅可通过明确的专用命令进行；这些命令默认先试运行，且需要使用 --yes 才会应用更改。

身份验证

此 CLI 支持已保存的会话或环境令牌。建议使用环境变量，避免将机密直接写入 shell 历史记录：

MONARCH_EMAIL='[email protected]' MONARCH_PASSWORD='...' monarch-money-pp-cli login

如果需要 MFA：

MONARCH_EMAIL='[email protected]' MONARCH_PASSWORD='...' monarch-money-pp-cli login --mfa 123456

也可以设置现有令牌：

export MONARCH_TOKEN='...'

然后验证：

monarch-money-pp-cli doctor

独特功能

通过常规 shell 访问 Monarch 数据时，无法使用以下功能。

• query — 运行自定义只读 GraphQL 查询文件，同时拒绝包含 GraphQL mutation 的文件。

  当内置的账户、标签、交易和现金流命令无法满足需求，但工作流仍需要只读保护时使用。

monarch-money-pp-cli query query.graphql --operation OperationName --variables '{"limit":10}'

• 交易 CRUD 命令 — 通过精简的 mutation 命令创建、更新、添加标签和删除单笔交易。

  用户确认目标交易后，使用这些命令进行交易整理。先省略 --yes，以检查试运行载荷。

monarch-money-pp-cli transactions update TRANSACTION_ID --notes 'Reviewed'
monarch-money-pp-cli transactions update TRANSACTION_ID --notes 'Reviewed' --yes

最佳命令映射

• “Monarch 连接正常吗？” → monarch-money-pp-cli status
• “显示账户余额” → monarch-money-pp-cli accounts
• “有哪些标签？” → monarch-money-pp-cli tags --limit 200
• “最近的交易” → monarch-money-pp-cli transactions --days 30 --limit 50
• “本月现金流” → monarch-money-pp-cli cashflow
• “一月份的现金流” → monarch-money-pp-cli cashflow --start 2026-01-01 --end 2026-01-31
• “更新这笔交易的备注” → monarch-money-pp-cli transactions update TRANSACTION_ID --notes 'NOTE'，审核后再使用 --yes 重新运行
• “为这笔交易添加这些标签” → monarch-money-pp-cli transactions set-tags TRANSACTION_ID --tag-id TAG_ID，审核后再使用 --yes 重新运行
• “需要原始输出进行分析” → 添加 --json

命令参考

accounts — 列出财务账户及其余额、账户类型和所属机构。

• monarch-money-pp-cli accounts — 以表格形式列出账户余额。
• monarch-money-pp-cli accounts --limit 10 — 显示前 10 个账户。
• monarch-money-pp-cli accounts --json — 返回原始 GraphQL 账户载荷。

tags — 列出家庭交易标签及交易数量。

• monarch-money-pp-cli tags — 列出标签及交易数量。
• monarch-money-pp-cli tags --search travel --limit 20 — 按名称搜索标签。

transactions — 列出近期交易，包括日期、商户、类别、账户、金额和标签。

• monarch-money-pp-cli transactions — 使用默认的 30 天时间范围列出近期交易。
• monarch-money-pp-cli transactions --days 7 --limit 25 — 列出较短时间范围内的近期交易。
• monarch-money-pp-cli transactions --start 2026-01-01 --end 2026-01-31 --json — 以 JSON 格式返回自定义日期范围的交易。
• monarch-money-pp-cli transactions --tag-id TAG_ID — 按 Monarch 标签 ID 筛选。

transactions create — 创建手动交易。除非传入 --yes，否则只进行试运行。

• monarch-money-pp-cli transactions create --date 2026-01-15 --account-id ACCOUNT_ID --amount -42.50 --merchant 'Coffee Shop' --category-id CATEGORY_ID — 预览创建操作。
• 检查试运行载荷后，添加 --yes 以应用更改。

transactions update — 按 ID 更新交易。除非传入 --yes，否则只进行试运行。

• monarch-money-pp-cli transactions update TRANSACTION_ID --category-id CATEGORY_ID --notes 'Reviewed' — 预览交易更新。
• 支持的更新标志包括 --category-id、--merchant、--goal-id、--amount、--date、--hide-from-reports true|false、--needs-review true|false 和 --notes。

transactions set-tags — 替换交易的所有标签。除非传入 --yes，否则只进行试运行。

• monarch-money-pp-cli transactions set-tags TRANSACTION_ID --tag-id TAG_ID --tag-id ANOTHER_TAG_ID — 预览替换标签。
• monarch-money-pp-cli transactions set-tags TRANSACTION_ID --clear — 预览清除标签。

transactions delete — 按 ID 删除交易。除非传入 --yes，否则只进行试运行。

• monarch-money-pp-cli transactions delete TRANSACTION_ID — 预览删除交易。

cashflow — 汇总指定日期范围内的收入、支出、净储蓄和储蓄率。

• monarch-money-pp-cli cashflow — 汇总当月数据。
• monarch-money-pp-cli cashflow --start 2026-01-01 --end 2026-01-31 — 汇总自定义时段的数据。

query — 从文件运行只读 GraphQL 查询，用于高级或调试工作流。

• monarch-money-pp-cli query query.graphql --operation OperationName --variables '{"limit":10}' — 运行只读查询文件。

doctor — 检查本地配置和 Monarch 连通性。

• monarch-money-pp-cli doctor — 验证身份验证和连通性。

status — 通过发起只读 GraphQL 请求，验证当前 Monarch Money 会话。

• monarch-money-pp-cli status — 确认当前会话可以连接到 Monarch。

安全说明

交易写入命令默认只进行试运行；向 Monarch 发送变更操作前，必须传入 --yes。写入时请使用交易 ID；不要根据商户名称或金额猜测不明确的目标。

高级 query 命令会拒绝包含 mutation 的 GraphQL 文件；请勿将其用作绕过写入限制的途径。

请勿打印或暴露 MONARCH_TOKEN、保存的会话内容、电子邮件或密码值，或原始身份验证响应。