wealthbox-cli 2.4.0

CLI and client library for the Wealthbox CRM API

Wealthbox CLI

Run your Wealthbox CRM through Claude or ChatGPT. Tell your AI agent "add a contact for Jane Doe, send her our welcome packet, and put a follow-up on my calendar for next Tuesday" — and it just happens. No coding, no Python, no terminal commands to memorize.

Unofficial, community-built. Not affiliated with or endorsed by Wealthbox.

---

Install (60 seconds, no Python required)

Platform	Paste this into your terminal
Mac / Linux	curl -LsSf https://raw.githubusercontent.com/massive-value/wealthbox-cli/main/scripts/install.sh | bash
Windows (PowerShell)	irm https://raw.githubusercontent.com/massive-value/wealthbox-cli/main/scripts/install.ps1 | iex

The installer:

1. Downloads the prebuilt wbox binary from the latest GitHub Release and verifies its SHA-256 checksum (no Python required).
2. Installs the AI agent skill into Claude Code (and Codex, if you have it).
3. Asks for your Wealthbox API token. Where to find it: in Wealthbox, click your initials in the top right → Settings → API Access → Create Access Token. Paste the token when prompted.

Re-running is idempotent: it keeps your stored token, refreshes the skill template, and leaves PATH alone if already correct. To install just the binary without the AI agent skill, on Windows download install.ps1 and run with -SkipSkills:

iwr https://raw.githubusercontent.com/massive-value/wealthbox-cli/main/scripts/install.ps1 -OutFile install.ps1
.\install.ps1 -SkipSkills

That's it. Open Claude Code and try one of the prompts below.

---

Try this in Claude Code

"Show me my contacts created this week."

"Add Jane Doe as a new prospect — she came in as a referral from Bob Smith."

"Pull up the Smith household, add a task for me to call them on Monday."

"Find notes from my meeting with the Joneses last month and summarize the action items."

"Schedule an annual review with Mary Chen for the second Tuesday of next month."

The first time you ask the agent to do something, it'll walk you through a short Q&A about your firm's conventions (default contact types, naming patterns, common workflows). After that, it just works.

If you're new to Claude Code itself, download it here — it's free for personal use.

---

What it covers

Full read/write access for contacts (people, households, organizations, trusts), tasks, events, notes, opportunities, projects, and workflows. Read access for users, activity, and your firm's category lookups.

Anything you can do in Wealthbox manually, the agent can do for you — usually in one sentence.

---

How it works

Your AI agent uses a small command-line tool called wbox to talk to the Wealthbox CRM API. The skill that ships with this repo teaches the agent two things:

1. Your firm's conventions — the agent walks you through a one-time Q&A on first use ("what's your default contact type for new prospects? what's your household naming convention?"), then remembers your answers. Stored locally on your machine, never sent to a server.
2. The right command for each request — translating "add Jane as a prospect" into the correct API call, handling required fields, validating dropdowns against your firm's actual categories.

You stay in control: the agent shows you what it's about to do before it does it.

---

What gets installed, where

The installer drops a single prebuilt wbox binary onto your PATH (~/.local/bin/wbox on Mac/Linux, %LOCALAPPDATA%\Programs\wbox\wbox.exe on Windows), then registers the AI agent skill with Claude Code (and Codex, if it's installed). Firm data lives at ~/.config/wbox/firm/ (Mac/Linux) or %APPDATA%\wbox\firm\ (Windows) and survives reinstalls and upgrades. Run wbox doctor to see your install status anytime, and wbox skills upgrade to pull the latest skill template.

Upgrading

The upgrade command depends on how you installed:

If you installed via...	Upgrade with
install.sh / install.ps1 (the one-line installer above)	wbox self upgrade
pip install wealthbox-cli	pip install --upgrade wealthbox-cli
pipx install wealthbox-cli	pipx upgrade wealthbox-cli
uv tool install wealthbox-cli	uv tool upgrade wealthbox-cli

wbox self upgrade only swaps the standalone bundle the one-line installer puts in place; on pip/pipx/uv installs it refuses with the correct follow-up command rather than half-replacing a venv-managed shim.

---

For developers and power users

Direct CLI use, scripting, automation

pip install wealthbox-cli
wbox config set-token

# List contacts as a table
wbox contacts list --format table

# Create a contact
wbox contacts add person --first-name Jane --last-name Doe --contact-type Client

# Export tasks to CSV
wbox tasks list --format csv > tasks.csv

# Add a meeting note linked to a contact
wbox notes add "Discussed retirement plan" --contact 12345

Full command reference: CLI Reference. Output formats: json (default), table, csv, tsv. Date format: ISO 8601 (2026-05-01T10:00:00-07:00). See Getting Started for pipx, env-var auth, and project-scoped installs.

Exit codes — wbox returns differentiated exit codes so scripts can branch on the failure class:

Code	Meaning
0	Success
1	Validation / user error (bad input, a non-auth 4xx from the API such as 404/422)
2	Authentication error (API 401/403)
3	Server error (API 5xx)

Note: Click also exits 2 for usage errors (an unknown flag or a missing required argument); that overlap with the auth code is pre-existing and acceptable, since usage errors are caught by the parser before the command runs. Set WBOX_DEBUG=1 to print the full Python traceback to stderr alongside the friendly message (the exit code is unchanged) — handy when reporting bugs.

Brief mode — Wealthbox duplicates every text field as HTML markup (content_html, description_html, body_html, etc.), making responses 3–5x larger. Pass --brief or set WBOX_BRIEF=1 to recursively strip all *_html keys from the JSON output before it is printed. Plain-text counterparts are kept; all other fields are unaffected. Any non-empty value is truthy (same convention as WBOX_DEBUG).

# One-off: flag form
wbox --brief notes list

# Persistent in a script or agent session
export WBOX_BRIEF=1
wbox notes list
wbox tasks list

Manage skill installs (legacy / Codex / project scope)

wbox skills install        # interactive picker — Claude Code, Codex, project scope
wbox skills bootstrap      # populate firm data from your Wealthbox account
wbox skills refresh        # re-fetch generated firm data (categories, users, custom fields)
wbox skills upgrade        # update the bundled SKILL.md / references in every install
wbox skills firm-path      # print the canonical firm data directory
wbox skills uninstall      # remove the skill template (firm data is preserved)
wbox doctor                # comprehensive health check

The one-line installer (top of this README) wires up Claude Code automatically. These commands are for the cases the installer doesn't cover: re-running on a different host, swapping platforms, project-scoped installs, or air-gapped setups where you've placed the wbox binary by hand.

Architecture and contributing

src/wealthbox_tools/
    cli/        # Typer commands
    client/     # Async HTTP client built from mixins
    models/     # Pydantic v2 input validation

Built with Typer, httpx, and Pydantic v2.

git clone https://github.com/massive-value/wealthbox-cli
cd wealthbox-cli
python -m venv .venv
# Activate: source .venv/bin/activate (Mac/Linux) | .venv\Scripts\Activate.ps1 (Windows)
pip install -e ".[dev]"
pytest

See CONTRIBUTING.md and CLAUDE.md for the architecture guide and conventions.

Troubleshooting

• 401 Unauthorized — token expired or wrong. Run wbox config show to see the masked token, wbox config set-token to update.
• wbox self upgrade says "run uv tool upgrade …" (or pipx / pip) — expected. wbox self upgrade only swaps the standalone bundle the one-line installer drops in place. If you installed via pip / pipx / uv, follow the command the gate prints. See Upgrading.
• Windows: "execution policy" error during install — the installer offers to fix this for you. If you skipped it, run Set-ExecutionPolicy RemoteSigned -Scope CurrentUser and re-run the installer.
• Linux: command not found after install — open a new terminal, or run source ~/.local/bin/env in your current shell.
• Date format errors — Wealthbox needs ISO 8601: "2026-05-01T10:00:00-07:00" for datetimes, "YYYY-MM-DD" for date-only fields.
• Writes succeed but nothing changes — some category-constrained fields silently no-op on bad values. Check valid values with wbox categories <type>.

For anything else, open an issue at github.com/massive-value/wealthbox-cli/issues.

---

Links

Documentation · Changelog · PyPI · Wealthbox CRM · Wealthbox API

Disclaimer

This is an unofficial, community-built tool. It is not affiliated with, endorsed by, or supported by Wealthbox or its parent company. "Wealthbox" is a trademark of its respective owner. Use of this tool is subject to the Wealthbox API Terms of Service.

License

Apache 2.0 — see LICENSE.