wealthbox-cli 1.3.0

CLI and client library for the Wealthbox CRM API

Wealthbox CLI — Command-Line Client for the Wealthbox CRM API

wealthbox-cli (wbox) is a command-line tool and Python client library for the Wealthbox CRM API. It gives financial advisors, developers, and RIA firms full CRUD access to contacts, tasks, events, notes, households, and more — directly from the terminal. Automate your CRM workflows, export data, and integrate Wealthbox into scripts and CI pipelines.

Documentation | PyPI | Changelog | Wealthbox CRM | Wealthbox API Docs

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.

---

Why Use wealthbox-cli?

• No coding required — structured CLI flags replace raw JSON and cURL commands
• Automate CRM workflows — script bulk updates, data exports, and scheduled tasks
• Multiple output formats — pipe JSON, CSV, or TSV directly to files or other tools
• Built for financial advisors and developers — covers contacts, households, tasks, events, notes, categories, and custom fields
• AI-agent ready — pair with Claude Code or other coding agents for natural-language CRM automation
• Open source — Apache 2.0 licensed, community-driven, and extensible

---

Quick Start

No Python? No problem. One-line installer (works on a fresh machine):

Platform	Command
macOS / 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 pulls in uv (which provisions Python automatically), installs wbox, prompts for your Wealthbox API token, and offers to install the AI agent skill.

Already have Python? You can install directly:

pip install wealthbox-cli
wbox config set-token        # paste your Wealthbox API token (masked)
wbox me                      # verify connection

See the Getting Started guide for pipx install, environment variable auth, and other options.

---

Usage Examples

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

# Create a new client 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

# Create a task linked to a contact
wbox tasks add "Follow up call" --due-date "2026-04-10T09:00:00-07:00" --contact 12345

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

# Schedule an event
wbox events add "Annual Review" --starts-at "2026-05-01T10:00:00-07:00" --ends-at "2026-05-01T11:00:00-07:00"

For the full command list, see the CLI Reference.

---

Supported Resources

Resource	List	Get	Create	Update	Delete
Contacts	Yes	Yes	Yes	Yes	Yes
Households	Yes	Yes	Yes	Yes	Yes
Tasks	Yes	Yes	Yes	Yes	Yes
Events	Yes	Yes	Yes	Yes	Yes
Notes	Yes	Yes	Yes	Yes	—
Users	Yes	—	—	—	—
Activity	Yes	—	—	—	—
Categories	Yes	—	—	—	—

---

Use with AI Coding Agents

wealthbox-cli ships with a skill for Claude Code and Codex that lets AI agents manage your CRM through natural language. Instead of memorizing CLI flags, just describe what you want:

create a contact for Jane Doe, she's a new prospect
list my tasks due this week
add a note to contact 123 about today's meeting
find all contacts tagged "VIP" and export to CSV

The skill translates your intent into the correct wbox commands, handles flag construction, and validates inputs — ideal for advisors who want CRM automation without learning CLI syntax.

Install

Two ways depending on which agent you use:

Option A — Claude Code plugin marketplace (recommended for Claude Code users)

Inside Claude Code:

/plugin marketplace add massive-value/wealthbox-cli
/plugin install wealthbox-crm@massive-value

The plugin auto-updates daily. The skill is installed under ~/.claude/plugins/cache/. Firm data is stored at the canonical machine-level path (~/.config/wbox/firm/ or %APPDATA%\wbox\firm\) — see Where firm data lives below — and survives plugin auto-updates.

The wbox CLI is still required as the execution engine. The bundled SKILL.md tells the agent to install it via the Phase 1 bootstrap if missing.

Option B — wbox skills install (Claude Code, Codex, or local project scope)

pip install wealthbox-cli
wbox config set-token        # paste your Wealthbox API token
wbox skills install          # interactive: pick Claude Code (user/project), Codex, or all

The installer asks which platforms to target, copies the skill into the right directory (~/.claude/skills/ for Claude Code, ~/.codex/skills/ for Codex — both use SKILL.md), and offers to bootstrap your firm's customizations from the Wealthbox API.

Option C — Codex marketplace (when the openai/skills PR lands)

Pending submission to openai/skills (status tracked in CHANGELOG). Until then, use Option B for Codex.

Upgrading from < 1.1.6? Earlier versions installed the codex skill as AGENTS.md. That was wrong — codex uses SKILL.md for skills (and AGENTS.md only as the project-level instructions file, in place of CLAUDE.md). If your codex install still has AGENTS.md, reinstall with wbox skills install --platform codex --force.

First agent run captures firm conventions

wbox skills bootstrap populates the API-derived files (categories, custom fields, users) — that's the quantitative half. The qualitative half (firm defaults, naming conventions, named workflows, required fields) happens the first time an agent invokes the skill: it walks you through the questions in bootstrap.md and stamps onboarded_at in the canonical firm _meta.json when done. On subsequent runs the bootstrap path is skipped automatically.

Where firm data lives

Firm data is stored at one canonical machine-level path — not inside each skill install. This way it survives plugin auto-updates, skill template upgrades, and works the same across Claude Code, Codex, or any other host:

Platform	Firm data path
macOS / Linux	~/.config/wbox/firm/
Windows	%APPDATA%\wbox\firm\

Run wbox skills firm-path to print the resolved path. The bundled SKILL.md tells the agent to call this command and read firm files from that directory.

Refresh after firm changes

If your firm adds or renames category values, custom fields, or users:

wbox skills refresh

This updates the generated half (categories, custom-fields, users); hand-edited policy is preserved.

Other commands

wbox skills list             # show install state per platform + canonical firm path
wbox skills doctor           # diagnose install state + token + firm state
wbox skills firm-path        # print canonical firm directory (for the agent)
wbox skills upgrade          # refresh template files in every install; firm data is unaffected
wbox skills mark-onboarded   # stamp onboarded_at in firm meta (the agent calls this for you)
wbox skills uninstall        # remove the skill template; firm data is preserved

When the CLI ships a newer template (improved SKILL.md, new reference docs, etc.), wbox skills upgrade re-copies the bundled template into every installed platform. Firm data lives outside the skill dir, so it's untouched. Each install records the template's CLI version in its own _meta.json, so the agent can detect drift and prompt you to upgrade when needed.

Works with other agents too

The wbox CLI is a standard command-line tool. Any AI coding agent that can execute shell commands — Claude Code, GitHub Copilot CLI, Cursor, or custom agent frameworks — can use it to read and write Wealthbox data. The bundled skill just makes Claude Code and Codex aware of the full command surface.

---

Architecture

src/wealthbox_tools/
    cli/        # Typer commands — user-facing, delegates to client
    client/     # Async HTTP client built from mixins
    models/     # Pydantic v2 models for input validation

Built with Typer, httpx, and Pydantic v2. See Contributing for the full architecture guide and how to add new resources.

---

Contributing

git clone https://github.com/massive-value/wealthbox-cli
cd wealthbox-cli
python -m venv .venv

Activate the virtual environment:

Platform	Command
macOS/Linux	source .venv/bin/activate
Windows (PowerShell)	.venv\Scripts\Activate.ps1
Windows (Command Prompt)	.venv\Scripts\activate.bat

Then install and test:

pip install -e ".[dev]"
pytest

See CONTRIBUTING.md for the full guide.

---

Troubleshooting

401 Unauthorized — Check your API token. Run wbox config show to verify.

Date format errors — Use ISO 8601: "2026-04-01T10:00:00-07:00" or "2026-04-01T10:00:00Z". Date-only fields use "YYYY-MM-DD".

Writes appear to succeed but nothing changed — Some category-constrained writes silently no-op. Check valid values first with wbox contacts categories contact-types.

---

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.