Can I use Wealthbox as a CLI?

Yes. KosmoKrator exposes a Wealthbox CLI through kosmo integrations:call and the provider shortcut command. Commands can return JSON for scripts, CI, and coding agents.

Can I expose Wealthbox through MCP?

Yes. The KosmoKrator MCP gateway can expose selected Wealthbox tools to clients such as Claude Code, Cursor, Codex, and other MCP-compatible tools.

Where are Wealthbox credentials stored?

Wealthbox credentials are configured in KosmoKrator's local integration settings and reused by CLI, Lua, and MCP gateway surfaces.

Can I deny write access for Wealthbox MCP tools?

Yes. Start the gateway with --write=deny for read-only clients, or use ask/allow only for trusted workspaces.

other

Wealthbox Lua API for KosmoKrator Agents

Agent-facing Lua documentation and function reference for the Wealthbox KosmoKrator integration.

9 functions 7 read 2 write Bearer token auth

Submit Wealthbox feedback View package source

Lua Namespace

Agents call this integration through app.integrations.wealthbox.*. Use lua_read_doc("integrations.wealthbox") inside KosmoKrator to discover the same reference at runtime.

Agent-Facing Lua Docs

This is the rendered version of the full Lua documentation exposed to agents when they inspect the integration namespace.

Wealthbox CRM — Lua API Reference

list_contacts

List contacts from Wealthbox CRM.

Parameters

Name	Type	Required	Description
`page`	integer	no	Page number for pagination (default: 1)
`per_page`	integer	no	Number of contacts per page (default: 25, max: 200)
`search`	string	no	Search term to filter contacts by name or email

Examples

-- List all contacts
local result = app.integrations.wealthbox.list_contacts({})

for _, contact in ipairs(result.contacts) do
  print(contact.first_name .. " " .. contact.last_name)
end

-- Search for a contact
local result = app.integrations.wealthbox.list_contacts({
  search = "John"
})

-- Paginate through contacts
local result = app.integrations.wealthbox.list_contacts({
  page = 2,
  per_page = 50
})

get_contact

Get a specific contact by ID.

Parameters

Name	Type	Required	Description
`id`	integer	yes	The contact ID in Wealthbox

Examples

local result = app.integrations.wealthbox.get_contact({
  id = 12345
})

print(result.first_name .. " " .. result.last_name)
print("Email: " .. (result.email or "N/A"))

create_contact

Create a new contact in Wealthbox CRM.

Parameters

Name	Type	Required	Description
`first_name`	string	no*	Contact’s first name
`last_name`	string	no*	Contact’s last name
`email`	string	no	Contact’s email address
`phone`	string	no	Contact’s phone number
`street`	string	no	Street address
`city`	string	no	City
`state`	string	no	State or province
`zip`	string	no	ZIP or postal code
`type`	string	no	Contact type (e.g., “Client”, “Prospect”, “Lead”)
`tags`	array	no	Tags to assign to the contact

*At least first_name or last_name is required.

Examples

-- Create a basic contact
local result = app.integrations.wealthbox.create_contact({
  first_name = "Jane",
  last_name = "Smith",
  email = "[email protected]"
})

print("Created contact ID: " .. result.id)

-- Create a contact with full details
local result = app.integrations.wealthbox.create_contact({
  first_name = "Jane",
  last_name = "Smith",
  email = "[email protected]",
  phone = "+1-555-0123",
  street = "123 Main St",
  city = "New York",
  state = "NY",
  zip = "10001",
  type = "Client",
  tags = {"VIP", "Referral"}
})

list_tasks

List tasks from Wealthbox CRM.

Parameters

Name	Type	Required	Description
`page`	integer	no	Page number for pagination (default: 1)
`per_page`	integer	no	Number of tasks per page (default: 25, max: 200)
`status`	string	no	Filter by task status (e.g., “open”, “completed”)

Examples

-- List open tasks
local result = app.integrations.wealthbox.list_tasks({
  status = "open"
})

for _, task in ipairs(result.tasks) do
  print(task.name .. " — Due: " .. (task.due_date or "No date"))
end

create_task

Create a new task in Wealthbox CRM.

Parameters

Name	Type	Required	Description
`name`	string	yes	The task name or title
`due_date`	string	no	Due date (ISO 8601, e.g., “2026-04-15”)
`description`	string	no	Task description or notes
`assignee_id`	integer	no	User ID of the assignee
`contact_id`	integer	no	Link the task to a contact by their ID
`priority`	string	no	Task priority (e.g., “high”, “medium”, “low”)

Examples

-- Create a follow-up task
local result = app.integrations.wealthbox.create_task({
  name = "Follow up with Jane Smith",
  due_date = "2026-04-15",
  description = "Discuss portfolio rebalancing",
  contact_id = 12345,
  priority = "high"
})

print("Created task ID: " .. result.id)

list_opportunities

List opportunities (sales pipeline) from Wealthbox CRM.

Parameters

Name	Type	Required	Description
`page`	integer	no	Page number for pagination (default: 1)
`per_page`	integer	no	Number of opportunities per page (default: 25, max: 200)
`status`	string	no	Filter by opportunity status (e.g., “open”, “won”, “lost”)

Examples

-- List open opportunities
local result = app.integrations.wealthbox.list_opportunities({
  status = "open"
})

for _, opp in ipairs(result.opportunities) do
  print(opp.name .. " — Value: $" .. (opp.value or "0"))
end

list_workflows

List workflows from Wealthbox CRM.

Parameters

Name	Type	Required	Description
`page`	integer	no	Page number for pagination (default: 1)
`per_page`	integer	no	Number of workflows per page (default: 25, max: 200)

Examples

local result = app.integrations.wealthbox.list_workflows({})

for _, workflow in ipairs(result.workflows) do
  print(workflow.name .. " — Status: " .. workflow.status)
end

list_events

List calendar events from Wealthbox CRM.

Parameters

Name	Type	Required	Description
`page`	integer	no	Page number for pagination (default: 1)
`per_page`	integer	no	Number of events per page (default: 25, max: 200)
`start_date`	string	no	Filter events starting from this date (ISO 8601)
`end_date`	string	no	Filter events up to this date (ISO 8601)

Examples

-- List upcoming events for April 2026
local result = app.integrations.wealthbox.list_events({
  start_date = "2026-04-01",
  end_date = "2026-04-30"
})

for _, event in ipairs(result.events) do
  print(event.title .. " — " .. event.starts_at)
end

get_current_user

Get the currently authenticated Wealthbox user.

Parameters

None.

Examples

local result = app.integrations.wealthbox.get_current_user({})

print("Logged in as: " .. result.first_name .. " " .. result.last_name)
print("Email: " .. result.email)

Multi-Account Usage

If you have multiple Wealthbox accounts configured, use account-specific namespaces:

-- Default account (always works)
app.integrations.wealthbox.function_name({...})

-- Explicit default (portable across setups)
app.integrations.wealthbox.default.function_name({...})

-- Named accounts
app.integrations.wealthbox.personal.function_name({...})
app.integrations.wealthbox.firm.function_name({...})

All functions are identical across accounts — only the credentials differ.

Raw agent markdown

# Wealthbox CRM — Lua API Reference

## list_contacts

List contacts from Wealthbox CRM.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `page` | integer | no | Page number for pagination (default: 1) |
| `per_page` | integer | no | Number of contacts per page (default: 25, max: 200) |
| `search` | string | no | Search term to filter contacts by name or email |

### Examples

```lua
-- List all contacts
local result = app.integrations.wealthbox.list_contacts({})

for _, contact in ipairs(result.contacts) do
  print(contact.first_name .. " " .. contact.last_name)
end
```

```lua
-- Search for a contact
local result = app.integrations.wealthbox.list_contacts({
  search = "John"
})
```

```lua
-- Paginate through contacts
local result = app.integrations.wealthbox.list_contacts({
  page = 2,
  per_page = 50
})
```

---

## get_contact

Get a specific contact by ID.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `id` | integer | yes | The contact ID in Wealthbox |

### Examples

```lua
local result = app.integrations.wealthbox.get_contact({
  id = 12345
})

print(result.first_name .. " " .. result.last_name)
print("Email: " .. (result.email or "N/A"))
```

---

## create_contact

Create a new contact in Wealthbox CRM.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `first_name` | string | no* | Contact's first name |
| `last_name` | string | no* | Contact's last name |
| `email` | string | no | Contact's email address |
| `phone` | string | no | Contact's phone number |
| `street` | string | no | Street address |
| `city` | string | no | City |
| `state` | string | no | State or province |
| `zip` | string | no | ZIP or postal code |
| `type` | string | no | Contact type (e.g., "Client", "Prospect", "Lead") |
| `tags` | array | no | Tags to assign to the contact |

*At least `first_name` or `last_name` is required.

### Examples

```lua
-- Create a basic contact
local result = app.integrations.wealthbox.create_contact({
  first_name = "Jane",
  last_name = "Smith",
  email = "[email protected]"
})

print("Created contact ID: " .. result.id)
```

```lua
-- Create a contact with full details
local result = app.integrations.wealthbox.create_contact({
  first_name = "Jane",
  last_name = "Smith",
  email = "[email protected]",
  phone = "+1-555-0123",
  street = "123 Main St",
  city = "New York",
  state = "NY",
  zip = "10001",
  type = "Client",
  tags = {"VIP", "Referral"}
})
```

---

## list_tasks

List tasks from Wealthbox CRM.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `page` | integer | no | Page number for pagination (default: 1) |
| `per_page` | integer | no | Number of tasks per page (default: 25, max: 200) |
| `status` | string | no | Filter by task status (e.g., "open", "completed") |

### Examples

```lua
-- List open tasks
local result = app.integrations.wealthbox.list_tasks({
  status = "open"
})

for _, task in ipairs(result.tasks) do
  print(task.name .. " — Due: " .. (task.due_date or "No date"))
end
```

---

## create_task

Create a new task in Wealthbox CRM.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `name` | string | yes | The task name or title |
| `due_date` | string | no | Due date (ISO 8601, e.g., "2026-04-15") |
| `description` | string | no | Task description or notes |
| `assignee_id` | integer | no | User ID of the assignee |
| `contact_id` | integer | no | Link the task to a contact by their ID |
| `priority` | string | no | Task priority (e.g., "high", "medium", "low") |

### Examples

```lua
-- Create a follow-up task
local result = app.integrations.wealthbox.create_task({
  name = "Follow up with Jane Smith",
  due_date = "2026-04-15",
  description = "Discuss portfolio rebalancing",
  contact_id = 12345,
  priority = "high"
})

print("Created task ID: " .. result.id)
```

---

## list_opportunities

List opportunities (sales pipeline) from Wealthbox CRM.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `page` | integer | no | Page number for pagination (default: 1) |
| `per_page` | integer | no | Number of opportunities per page (default: 25, max: 200) |
| `status` | string | no | Filter by opportunity status (e.g., "open", "won", "lost") |

### Examples

```lua
-- List open opportunities
local result = app.integrations.wealthbox.list_opportunities({
  status = "open"
})

for _, opp in ipairs(result.opportunities) do
  print(opp.name .. " — Value: $" .. (opp.value or "0"))
end
```

---

## list_workflows

List workflows from Wealthbox CRM.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `page` | integer | no | Page number for pagination (default: 1) |
| `per_page` | integer | no | Number of workflows per page (default: 25, max: 200) |

### Examples

```lua
local result = app.integrations.wealthbox.list_workflows({})

for _, workflow in ipairs(result.workflows) do
  print(workflow.name .. " — Status: " .. workflow.status)
end
```

---

## list_events

List calendar events from Wealthbox CRM.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `page` | integer | no | Page number for pagination (default: 1) |
| `per_page` | integer | no | Number of events per page (default: 25, max: 200) |
| `start_date` | string | no | Filter events starting from this date (ISO 8601) |
| `end_date` | string | no | Filter events up to this date (ISO 8601) |

### Examples

```lua
-- List upcoming events for April 2026
local result = app.integrations.wealthbox.list_events({
  start_date = "2026-04-01",
  end_date = "2026-04-30"
})

for _, event in ipairs(result.events) do
  print(event.title .. " — " .. event.starts_at)
end
```

---

## get_current_user

Get the currently authenticated Wealthbox user.

### Parameters

None.

### Examples

```lua
local result = app.integrations.wealthbox.get_current_user({})

print("Logged in as: " .. result.first_name .. " " .. result.last_name)
print("Email: " .. result.email)
```

---

## Multi-Account Usage

If you have multiple Wealthbox accounts configured, use account-specific namespaces:

```lua
-- Default account (always works)
app.integrations.wealthbox.function_name({...})

-- Explicit default (portable across setups)
app.integrations.wealthbox.default.function_name({...})

-- Named accounts
app.integrations.wealthbox.personal.function_name({...})
app.integrations.wealthbox.firm.function_name({...})
```

All functions are identical across accounts — only the credentials differ.

Metadata-Derived Lua Example

local result = app.integrations.wealthbox.wealthbox_list_contacts({
  page = 1,
  per_page = 1,
  search = "example_search"
})
print(result)

Functions

`wealthbox_list_contacts`

List contacts from Wealthbox CRM. Returns a paginated list of contacts with their details. Use search to filter by name or email.

Operation: Read read
Full name: wealthbox.wealthbox_list_contacts

Parameter	Type	Required	Description
`page`	integer	no	Page number for pagination (default: 1).
`per_page`	integer	no	Number of contacts per page (default: 25, max: 200).
`search`	string	no	Search term to filter contacts by name or email.

`wealthbox_get_contact`

Get a specific contact from Wealthbox CRM by their ID. Returns full contact details including name, email, phone, address, and custom fields.

Operation: Read read
Full name: wealthbox.wealthbox_get_contact

Parameter	Type	Required	Description
`id`	integer	yes	The contact ID in Wealthbox.

`wealthbox_create_contact`

Create a new contact in Wealthbox CRM. At minimum provide a first name or last name. You can also include email, phone, address, and other contact details.

Operation: Write write
Full name: wealthbox.wealthbox_create_contact

Parameter	Type	Required	Description
`first_name`	string	no	Contact's first name.
`last_name`	string	no	Contact's last name.
`email`	string	no	Contact's email address.
`phone`	string	no	Contact's phone number.
`street`	string	no	Street address.
`city`	string	no	City.
`state`	string	no	State or province.
`zip`	string	no	ZIP or postal code.
`type`	string	no	Contact type (e.g., "Client", "Prospect", "Lead").
`tags`	array	no	Tags to assign to the contact.

`wealthbox_list_tasks`

List tasks from Wealthbox CRM. Returns a paginated list of tasks with their details including name, due date, status, and assignee.

Operation: Read read
Full name: wealthbox.wealthbox_list_tasks

Parameter	Type	Required	Description
`page`	integer	no	Page number for pagination (default: 1).
`per_page`	integer	no	Number of tasks per page (default: 25, max: 200).
`status`	string	no	Filter by task status (e.g., "open", "completed").

`wealthbox_create_task`

Create a new task in Wealthbox CRM. Provide a task name and optionally a due date, description, and assignee.

Operation: Write write
Full name: wealthbox.wealthbox_create_task

Parameter	Type	Required	Description
`name`	string	yes	The task name or title.
`due_date`	string	no	Due date in ISO 8601 format (e.g., "2026-04-15").
`description`	string	no	Task description or notes.
`assignee_id`	integer	no	User ID of the assignee.
`contact_id`	integer	no	Link the task to a contact by their ID.
`priority`	string	no	Task priority (e.g., "high", "medium", "low").

`wealthbox_list_opportunities`

List opportunities (sales pipeline) from Wealthbox CRM. Returns a paginated list of opportunities with details like name, value, stage, and associated contact.

Operation: Read read
Full name: wealthbox.wealthbox_list_opportunities

Parameter	Type	Required	Description
`page`	integer	no	Page number for pagination (default: 1).
`per_page`	integer	no	Number of opportunities per page (default: 25, max: 200).
`status`	string	no	Filter by opportunity status (e.g., "open", "won", "lost").

`wealthbox_list_workflows`

List workflows from Wealthbox CRM. Returns a paginated list of workflows with their steps, status, and associated contacts.

Operation: Read read
Full name: wealthbox.wealthbox_list_workflows

Parameter	Type	Required	Description
`page`	integer	no	Page number for pagination (default: 1).
`per_page`	integer	no	Number of workflows per page (default: 25, max: 200).

`wealthbox_list_events`

List calendar events from Wealthbox CRM. Returns a paginated list of events with their title, date, time, and associated contacts.

Operation: Read read
Full name: wealthbox.wealthbox_list_events

Parameter	Type	Required	Description
`page`	integer	no	Page number for pagination (default: 1).
`per_page`	integer	no	Number of events per page (default: 25, max: 200).
`start_date`	string	no	Filter events starting from this date (ISO 8601, e.g., "2026-04-01").
`end_date`	string	no	Filter events up to this date (ISO 8601, e.g., "2026-04-30").

`wealthbox_get_current_user`

Get the currently authenticated Wealthbox user. Returns user profile information including name, email, and account details.

Operation: Read read
Full name: wealthbox.wealthbox_get_current_user

Parameter	Type	Required	Description
No parameters.