wealthos

The command-line tool for Wealthos, a personal wealth planning and forecasting app.

What is Wealthos?

Wealthos helps you simulate life's big decisions before you make them (a house, a move, a career change, a sabbatical) and see where each one leaves you years out. It's built on your real balances across every bank and currency you hold: net worth, income and expenses, savings goals, dated plans and long-range forecasts.

It comes in two editions:

• Wealthos Cloud: web app and iOS app, with bank connections and sync across devices.
• Wealthos Local: a macOS app that keeps everything as plain files in a folder you choose. No account, works offline.

Both expose your finances to AI assistants (Claude, ChatGPT, Cursor, Codex) through the Wealthos MCP server.

What this package is for

wealthos brings the same tools to a terminal, for scripts and for AI agents that work through a shell (Claude Code, Codex CLI, cron jobs). Output is JSON.

• Let an agent manage your finances. Ask Claude Code "how much can I put aside each month for a house in 2028?" and it can read your accounts, goals and plans and run the forecast itself, instead of guessing at the arithmetic.
• Check a purchase before you make it. affordability_check returns a verdict plus the trade-offs: a goal pushed back, investments to sell, a safety buffer breached.
• Keep your finances as plain files. A vault is a folder of YAML and JSONL in the documented Open Wealth Format, so it works with git, backups and any editor. Create one, validate it, and print the JSON Schema for any file type. The Wealthos desktop app opens the same folder.
• Automate. Log net worth from a cron job (wealth_get), add income and expenses from a script, pipe any result into jq.
• Look up country money rules, no account needed. Sourced, dated rules for the cost of buying a home in 16 European countries, the Dutch 30% ruling and German freelancer net income.

Needs Node 20 or later.

npx wealthos --help

A local vault

npx wealthos init ~/Documents/Wealthos --currency EUR
npx wealthos call ~/Documents/Wealthos accounts_add name=Current type=bank balance=8200
npx wealthos call ~/Documents/Wealthos wealth_get
npx wealthos call ~/Documents/Wealthos affordability_check amount=1200 what="flight to Lisbon" --text
npx wealthos doctor ~/Documents/Wealthos

If the Wealthos desktop app has the vault open, commands go through the app instead of opening the folder a second time.

Wealthos Cloud

Pass the MCP server URL instead of a folder, with an API token from Settings → Connect to AI tools via MCP in the Wealthos web app:

export WEALTHOS_TOKEN=wos_...
npx wealthos tools https://mcp.wealthos.cc --text
npx wealthos call https://mcp.wealthos.cc goals_list

Country rules

npx wealthos rules                                    # every rule, with review status
npx wealthos rules se.property_purchase_costs price=4500000 --text
npx wealthos rules de.property_purchase_costs price=500000 region=berlin non_resident=true
npx wealthos rules nl.expat_tax_regime gross_annual_salary=70000

Planning estimates, not tax or legal advice. Each rule lists its sources and when it was last checked.

Commands

| Command | | |---|---| | tools <target> [--text] [--schemas] | List tools (JSON, or one line each) | | call <target> <tool> [--args JSON] [key=value …] [--text] | Call a tool. key=value values are read as JSON when they parse; dotted keys nest (date.year=2027) | | schema [name] | Open Wealth Format file types, or one JSON Schema | | rules [id] [key=value …] [--country X] [--topic T] [--due] [--text] | List, show or calculate a country rule | | init <dir> [--email E] [--currency EUR] | Create a vault | | doctor <dir> [--clear-stale-lock] | Validate every file in a vault; changes nothing | | mcp-stdio <dir> | Serve a vault to an MCP client over stdio | | serve <dir> | The local core the desktop app runs |

<target> is a vault folder, or an https:// MCP server URL with --token or $WEALTHOS_TOKEN.

Exit codes: 0 success, 1 the tool reported a failure (its JSON is still printed), 2 bad usage or an unknown tool.

Links

• Wealthos: the app
• Wealthos Local: the macOS app for plain-file vaults
• Wealthos MCP server: connect Claude, ChatGPT and other assistants
• Open Wealth Format: the vault file format
• Country rules: the rules library as JSON
• Issues: report a problem or ask a question

License

MIT