Can I use FreshBooks as a CLI?

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

Can I expose FreshBooks through MCP?

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

Where are FreshBooks credentials stored?

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

Can I deny write access for FreshBooks MCP tools?

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

data

FreshBooks Lua API for KosmoKrator Agents

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

Lua Namespace

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

Call Lua from the Headless CLI

Use kosmo integrations:lua when a shell script, CI job, cron job, or another coding CLI should run a deterministic FreshBooks workflow without starting an interactive agent session.

Inline Lua call

kosmo integrations:lua --eval 'dump(app.integrations.freshbooks.list_invoices({search = "example_search", page = 1, per_page = 1}))' --json

Read Lua docs headlessly

kosmo integrations:lua --eval 'print(docs.read("freshbooks"))' --json
kosmo integrations:lua --eval 'print(docs.read("freshbooks.list_invoices"))' --json

Workflow file

Put repeatable logic in a Lua file, then execute it with JSON output for the calling process.

workflow.lua

local freshbooks = app.integrations.freshbooks
local result = freshbooks.list_invoices({search = "example_search", page = 1, per_page = 1})

dump(result)

Run the workflow

kosmo integrations:lua workflow.lua --json
kosmo integrations:lua workflow.lua --force --json

Namespace note. integrations:lua exposes app.integrations.freshbooks, app.mcp.*, docs.*, json.*, and regex.*. Use app.integrations.freshbooks.default.* or app.integrations.freshbooks.work.* when you configured named credential accounts.

MCP-only Lua

If the script only needs configured MCP servers and does not need FreshBooks, use the narrower mcp:lua command.

MCP Lua command

# Use mcp:lua for MCP-only scripts; use integrations:lua for this integration namespace.
kosmo mcp:lua --eval 'dump(mcp.servers())' --json

Agent-Facing Lua Docs

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

FreshBooks — Lua API Reference

list_invoices

List invoices from FreshBooks with optional filtering and pagination.

Parameters

Name	Type	Required	Description
`search`	object	no	Search filters (see below)
`page`	integer	no	Page number (default: 1)
`per_page`	integer	no	Results per page (default: 15, max: 100)

Key	Description
`status`	Invoice status: `draft`, `sent`, `viewed`, `paid`, `disputed`, `overdue`
`clientid`	Filter by client ID
`date_from`	Start date (YYYY-MM-DD)
`date_to`	End date (YYYY-MM-DD)
`invoice_number`	Filter by invoice number

Example

local result = app.integrations.freshbooks.list_invoices({
  search = { status = "sent" },
  per_page = 25
})

for _, invoice in ipairs(result.invoices) do
  print(invoice.invoice_number .. ": " .. invoice.amount.amount .. " " .. invoice.status)
end

get_invoice

Get full details of a specific invoice.

Parameters

Name	Type	Required	Description
`invoice_id`	integer	yes	The FreshBooks invoice ID

Example

local result = app.integrations.freshbooks.get_invoice({ invoice_id = 12345 })
local inv = result.invoice
print(inv.invoice_number .. " - " .. inv.status)
for _, line in ipairs(inv.lines) do
  print("  " .. line.name .. ": " .. line.unit_cost.amount)
end

create_invoice

Create a new invoice in FreshBooks.

Parameters

Name	Type	Required	Description
`client_id`	integer	yes	The client ID to bill
`lines`	array	yes	Array of line items (see below)
`date`	string	no	Invoice date (YYYY-MM-DD), defaults to today
`due_date`	string	no	Due date (YYYY-MM-DD)
`invoice_number`	string	no	Custom invoice number
`notes`	string	no	Notes displayed on the invoice
`terms`	string	no	Payment terms (e.g., “Net 30”)
`discount_value`	number	no	Discount amount or percentage
`discount_type`	string	no	`percentage` or `amount`

Line Item Format

Each line item is an object with:

Key	Type	Required	Description
`name`	string	yes	Line item name
`description`	string	no	Line item description
`qty`	number	yes	Quantity
`unit_cost`	object	yes	Object with `amount` (string) and `code` (currency code)

Example

local result = app.integrations.freshbooks.create_invoice({
  client_id = 100,
  lines = {
    {
      name = "Web Development",
      description = "Frontend development work",
      qty = 40,
      unit_cost = { amount = "150.00", code = "USD" }
    }
  },
  notes = "Thank you for your business!",
  terms = "Net 30"
})
print("Created invoice: " .. result.invoice.invoice_number)

list_clients

List clients from FreshBooks.

Parameters

Name	Type	Required	Description
`search`	object	no	Search filters (see below)
`page`	integer	no	Page number (default: 1)
`per_page`	integer	no	Results per page (default: 15, max: 100)

Key	Description
`email`	Filter by email address
`fname`	Filter by first name
`lname`	Filter by last name
`organization`	Filter by organization name
`state`	`active` or `archived`

Example

local result = app.integrations.freshbooks.list_clients({
  search = { organization = "Acme" },
  per_page = 50
})

for _, client in ipairs(result.clients) do
  print(client.organization .. " - " .. client.email)
end

get_client

Get details of a specific client.

Parameters

Name	Type	Required	Description
`client_id`	integer	yes	The FreshBooks client ID

Example

local result = app.integrations.freshbooks.get_client({ client_id = 100 })
local client = result.client
print(client.organization .. " - Balance: " .. client.outstanding_balance.amount)

list_projects

List projects from FreshBooks.

Parameters

Name	Type	Required	Description
`search`	object	no	Search filters (see below)
`page`	integer	no	Page number (default: 1)
`per_page`	integer	no	Results per page (default: 15, max: 100)

Key	Description
`title`	Filter by project title
`active`	`true` or `false`
`clientid`	Filter by client ID

Example

local result = app.integrations.freshbooks.list_projects({
  search = { active = true }
})

for _, project in ipairs(result.projects) do
  print(project.title .. " - " .. project.billing_method)
end

list_payments

List payments from FreshBooks.

Parameters

Name	Type	Required	Description
`search`	object	no	Search filters (see below)
`page`	integer	no	Page number (default: 1)
`per_page`	integer	no	Results per page (default: 15, max: 100)

Key	Description
`clientid`	Filter by client ID
`invoiceid`	Filter by invoice ID
`date_from`	Start date (YYYY-MM-DD)
`date_to`	End date (YYYY-MM-DD)
`type`	Payment type: `check`, `credit`, `card`, `bank`

Example

local result = app.integrations.freshbooks.list_payments({
  search = { date_from = "2025-01-01", date_to = "2025-01-31" },
  per_page = 50
})

for _, payment in ipairs(result.payments) do
  print(payment.date .. ": " .. payment.amount.amount .. " via " .. payment.type)
end

get_current_user

Get the profile of the currently authenticated FreshBooks user.

Parameters

None.

Example

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

for _, user in ipairs(result.users) do
  print(user.first_name .. " " .. user.last_name .. " - " .. user.email)
end

Multi-Account Usage

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

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

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

-- Named accounts
app.integrations.freshbooks.us_business.function_name({...})
app.integrations.freshbooks.eu_business.function_name({...})

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

Raw agent markdown

# FreshBooks — Lua API Reference

## list_invoices

List invoices from FreshBooks with optional filtering and pagination.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `search` | object | no | Search filters (see below) |
| `page` | integer | no | Page number (default: 1) |
| `per_page` | integer | no | Results per page (default: 15, max: 100) |

### Search Filter Keys

| Key | Description |
|-----|-------------|
| `status` | Invoice status: `draft`, `sent`, `viewed`, `paid`, `disputed`, `overdue` |
| `clientid` | Filter by client ID |
| `date_from` | Start date (YYYY-MM-DD) |
| `date_to` | End date (YYYY-MM-DD) |
| `invoice_number` | Filter by invoice number |

### Example

```lua
local result = app.integrations.freshbooks.list_invoices({
  search = { status = "sent" },
  per_page = 25
})

for _, invoice in ipairs(result.invoices) do
  print(invoice.invoice_number .. ": " .. invoice.amount.amount .. " " .. invoice.status)
end
```

---

## get_invoice

Get full details of a specific invoice.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `invoice_id` | integer | yes | The FreshBooks invoice ID |

### Example

```lua
local result = app.integrations.freshbooks.get_invoice({ invoice_id = 12345 })
local inv = result.invoice
print(inv.invoice_number .. " - " .. inv.status)
for _, line in ipairs(inv.lines) do
  print("  " .. line.name .. ": " .. line.unit_cost.amount)
end
```

---

## create_invoice

Create a new invoice in FreshBooks.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `client_id` | integer | yes | The client ID to bill |
| `lines` | array | yes | Array of line items (see below) |
| `date` | string | no | Invoice date (YYYY-MM-DD), defaults to today |
| `due_date` | string | no | Due date (YYYY-MM-DD) |
| `invoice_number` | string | no | Custom invoice number |
| `notes` | string | no | Notes displayed on the invoice |
| `terms` | string | no | Payment terms (e.g., "Net 30") |
| `discount_value` | number | no | Discount amount or percentage |
| `discount_type` | string | no | `percentage` or `amount` |

### Line Item Format

Each line item is an object with:

| Key | Type | Required | Description |
|-----|------|----------|-------------|
| `name` | string | yes | Line item name |
| `description` | string | no | Line item description |
| `qty` | number | yes | Quantity |
| `unit_cost` | object | yes | Object with `amount` (string) and `code` (currency code) |

### Example

```lua
local result = app.integrations.freshbooks.create_invoice({
  client_id = 100,
  lines = {
    {
      name = "Web Development",
      description = "Frontend development work",
      qty = 40,
      unit_cost = { amount = "150.00", code = "USD" }
    }
  },
  notes = "Thank you for your business!",
  terms = "Net 30"
})
print("Created invoice: " .. result.invoice.invoice_number)
```

---

## list_clients

List clients from FreshBooks.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `search` | object | no | Search filters (see below) |
| `page` | integer | no | Page number (default: 1) |
| `per_page` | integer | no | Results per page (default: 15, max: 100) |

### Search Filter Keys

| Key | Description |
|-----|-------------|
| `email` | Filter by email address |
| `fname` | Filter by first name |
| `lname` | Filter by last name |
| `organization` | Filter by organization name |
| `state` | `active` or `archived` |

### Example

```lua
local result = app.integrations.freshbooks.list_clients({
  search = { organization = "Acme" },
  per_page = 50
})

for _, client in ipairs(result.clients) do
  print(client.organization .. " - " .. client.email)
end
```

---

## get_client

Get details of a specific client.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `client_id` | integer | yes | The FreshBooks client ID |

### Example

```lua
local result = app.integrations.freshbooks.get_client({ client_id = 100 })
local client = result.client
print(client.organization .. " - Balance: " .. client.outstanding_balance.amount)
```

---

## list_projects

List projects from FreshBooks.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `search` | object | no | Search filters (see below) |
| `page` | integer | no | Page number (default: 1) |
| `per_page` | integer | no | Results per page (default: 15, max: 100) |

### Search Filter Keys

| Key | Description |
|-----|-------------|
| `title` | Filter by project title |
| `active` | `true` or `false` |
| `clientid` | Filter by client ID |

### Example

```lua
local result = app.integrations.freshbooks.list_projects({
  search = { active = true }
})

for _, project in ipairs(result.projects) do
  print(project.title .. " - " .. project.billing_method)
end
```

---

## list_payments

List payments from FreshBooks.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `search` | object | no | Search filters (see below) |
| `page` | integer | no | Page number (default: 1) |
| `per_page` | integer | no | Results per page (default: 15, max: 100) |

### Search Filter Keys

| Key | Description |
|-----|-------------|
| `clientid` | Filter by client ID |
| `invoiceid` | Filter by invoice ID |
| `date_from` | Start date (YYYY-MM-DD) |
| `date_to` | End date (YYYY-MM-DD) |
| `type` | Payment type: `check`, `credit`, `card`, `bank` |

### Example

```lua
local result = app.integrations.freshbooks.list_payments({
  search = { date_from = "2025-01-01", date_to = "2025-01-31" },
  per_page = 50
})

for _, payment in ipairs(result.payments) do
  print(payment.date .. ": " .. payment.amount.amount .. " via " .. payment.type)
end
```

---

## get_current_user

Get the profile of the currently authenticated FreshBooks user.

### Parameters

None.

### Example

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

for _, user in ipairs(result.users) do
  print(user.first_name .. " " .. user.last_name .. " - " .. user.email)
end
```

---

## Multi-Account Usage

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

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

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

-- Named accounts
app.integrations.freshbooks.us_business.function_name({...})
app.integrations.freshbooks.eu_business.function_name({...})
```

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

Metadata-derived Lua example

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

Functions

list_invoices Read

List invoices from FreshBooks. Returns invoice details including status, amounts, client info, and dates. Supports filtering by status, client, date range, and more.

Lua path: app.integrations.freshbooks.list_invoices
Full name: freshbooks.freshbooks_list_invoices

Parameter	Type	Required	Description
`search`	object	no	Search filters. Keys: status (e.g., "sent", "paid", "draft"), clientid, date_from, date_to, invoice_number. Pass as an object.
`page`	integer	no	Page number for pagination (default: 1).
`per_page`	integer	no	Results per page (default: 15, max: 100).

get_invoice Read

Get details of a specific FreshBooks invoice by ID. Returns full invoice data including line items, amounts, client details, status, and payment info.

Lua path: app.integrations.freshbooks.get_invoice
Full name: freshbooks.freshbooks_get_invoice

Parameter	Type	Required	Description
`invoice_id`	integer	yes	The FreshBooks invoice ID.

create_invoice Write

Create a new invoice in FreshBooks. Requires at minimum a client ID and line items. Supports setting due date, notes, discount, and other invoice fields.

Lua path: app.integrations.freshbooks.create_invoice
Full name: freshbooks.freshbooks_create_invoice

Parameter	Type	Required	Description
`client_id`	integer	yes	The client ID to bill.
`lines`	array	yes	Array of line items. Each line should have: name (string), description (string, optional), qty (number), unit_cost (object with amount and code).
`date`	string	no	Invoice date (YYYY-MM-DD). Defaults to today.
`due_date`	string	no	Due date (YYYY-MM-DD). Optional.
`invoice_number`	string	no	Custom invoice number. Auto-generated if omitted.
`notes`	string	no	Notes displayed on the invoice.
`terms`	string	no	Payment terms (e.g., "Net 30").
`discount_value`	number	no	Discount amount or percentage.
`discount_type`	string	no	Discount type: "percentage" or "amount".

list_clients Read

List clients from FreshBooks. Returns client details including name, email, company, and balance. Supports filtering and pagination.

Lua path: app.integrations.freshbooks.list_clients
Full name: freshbooks.freshbooks_list_clients

Parameter	Type	Required	Description
`search`	object	no	Search filters. Keys: email, fname, lname, organization, state (active/archived). Pass as an object.
`page`	integer	no	Page number for pagination (default: 1).
`per_page`	integer	no	Results per page (default: 15, max: 100).

get_client Read

Get details of a specific FreshBooks client by ID. Returns full client profile including contact info, company details, and outstanding balance.

Lua path: app.integrations.freshbooks.get_client
Full name: freshbooks.freshbooks_get_client

Parameter	Type	Required	Description
`client_id`	integer	yes	The FreshBooks client ID.

list_projects Read

List projects from FreshBooks. Returns project details including title, description, billing method, budget, and active status. Supports filtering and pagination.

Lua path: app.integrations.freshbooks.list_projects
Full name: freshbooks.freshbooks_list_projects

Parameter	Type	Required	Description
`search`	object	no	Search filters. Keys: title, active (true/false), clientid. Pass as an object.
`page`	integer	no	Page number for pagination (default: 1).
`per_page`	integer	no	Results per page (default: 15, max: 100).

list_payments Read

List payments from FreshBooks. Returns payment details including amount, date, client, invoice, and payment method. Supports filtering and pagination.

Lua path: app.integrations.freshbooks.list_payments
Full name: freshbooks.freshbooks_list_payments

Parameter	Type	Required	Description
`search`	object	no	Search filters. Keys: clientid, invoiceid, date_from, date_to, type (check/credit/card/bank). Pass as an object.
`page`	integer	no	Page number for pagination (default: 1).
`per_page`	integer	no	Results per page (default: 15, max: 100).

get_current_user Read

Get the profile of the currently authenticated FreshBooks user. Returns user details including name, email, and linked business/member information. Useful for verifying connection and identity.

Lua path: app.integrations.freshbooks.get_current_user
Full name: freshbooks.freshbooks_get_current_user

Parameter	Type	Required	Description
No parameters.