Can I use BambooHR as a CLI?

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

Can I expose BambooHR through MCP?

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

Where are BambooHR credentials stored?

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

Can I deny write access for BambooHR MCP tools?

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

productivity

BambooHR Lua API for KosmoKrator Agents

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

Lua Namespace

Agents call this integration through app.integrations.bamboohr.*. Use lua_read_doc("integrations.bamboohr") 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 BambooHR workflow without starting an interactive agent session.

Inline Lua call

kosmo integrations:lua --eval 'dump(app.integrations.bamboohr.list_employees({}))' --json

Read Lua docs headlessly

kosmo integrations:lua --eval 'print(docs.read("bamboohr"))' --json
kosmo integrations:lua --eval 'print(docs.read("bamboohr.list_employees"))' --json

Workflow file

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

workflow.lua

local bamboohr = app.integrations.bamboohr
local result = bamboohr.list_employees({})

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.bamboohr, app.mcp.*, docs.*, json.*, and regex.*. Use app.integrations.bamboohr.default.* or app.integrations.bamboohr.work.* when you configured named credential accounts.

MCP-only Lua

If the script only needs configured MCP servers and does not need BambooHR, 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.

BambooHR — Lua API Reference

list_employees

List all employees from the company directory.

Parameters

None.

Example

local result = app.integrations.bamboohr.list_employees({})

for _, emp in ipairs(result.employees) do
  print(emp.id .. ": " .. emp.firstName .. " " .. emp.lastName .. " — " .. (emp.jobTitle or "N/A"))
end

get_employee

Get detailed information for a specific employee.

Parameters

Name	Type	Required	Description
`employee_id`	integer	yes	The BambooHR employee ID
`fields`	array	no	Fields to retrieve (e.g., `{"firstName", "lastName", "jobTitle", "workEmail", "department", "hireDate", "status"}`)

Example

local result = app.integrations.bamboohr.get_employee({
  employee_id = 42,
  fields = {"firstName", "lastName", "jobTitle", "workEmail", "hireDate"}
})

print(result.firstName .. " " .. result.lastName)
print("Title: " .. (result.jobTitle or "N/A"))
print("Email: " .. (result.workEmail or "N/A"))
print("Hired: " .. (result.hireDate or "N/A"))

create_employee

Create a new employee record in BambooHR.

Parameters

Name	Type	Required	Description
`first_name`	string	yes	Employee first name
`last_name`	string	yes	Employee last name
`work_email`	string	no	Work email address
`job_title`	string	no	Job title
`department`	string	no	Department name
`hire_date`	string	no	Hire date (YYYY-MM-DD)
`status`	string	no	Employment status (e.g., “Active”)
`location`	string	no	Work location
`supervisor_id`	integer	no	Employee ID of the supervisor

Example

local result = app.integrations.bamboohr.create_employee({
  first_name = "Jane",
  last_name = "Doe",
  work_email = "jane.doe@example.com",
  job_title = "Software Engineer",
  department = "Engineering",
  hire_date = "2026-04-01"
})

print("Created employee: " .. tostring(result.id or "success"))

update_employee

Update an existing employee record.

Parameters

Name	Type	Required	Description
`employee_id`	integer	yes	The BambooHR employee ID to update
`first_name`	string	no	Updated first name
`last_name`	string	no	Updated last name
`work_email`	string	no	Updated work email
`job_title`	string	no	Updated job title
`department`	string	no	Updated department
`status`	string	no	Updated employment status
`location`	string	no	Updated work location
`supervisor_id`	integer	no	Updated supervisor employee ID

Example

local result = app.integrations.bamboohr.update_employee({
  employee_id = 42,
  job_title = "Senior Software Engineer",
  department = "Engineering"
})

print("Employee updated: " .. tostring(result.success or "done"))

list_departments

List all company departments.

Parameters

None.

Example

local result = app.integrations.bamboohr.list_departments({})

for _, dept in ipairs(result.departments or {}) do
  print(dept.name .. " (ID: " .. tostring(dept.id) .. ")")
end

list_time_off_requests

List time-off requests with optional filters.

Parameters

Name	Type	Required	Description
`start`	string	no	Start date filter (YYYY-MM-DD)
`end`	string	no	End date filter (YYYY-MM-DD)
`status`	string	no	Filter by status (“approved”, “pending”, “denied”)
`employee_id`	integer	no	Filter by employee ID
`type_id`	integer	no	Filter by time-off type ID

Example

local result = app.integrations.bamboohr.list_time_off_requests({
  start = "2026-04-01",
  end = "2026-04-30",
  status = "approved"
})

for _, req in ipairs(result.requests or {}) do
  print("Employee " .. req.employeeId .. ": " .. req.start .. " to " .. req.end .. " (" .. req.typeName .. ")")
end

get_time_off_request

Get detailed information for a specific time-off request by its ID.

Parameters

Name	Type	Required	Description
`request_id`	integer	yes	The BambooHR time-off request ID

Example

local result = app.integrations.bamboohr.get_time_off_request({
  request_id = 123
})

print("Request for employee " .. (result.employeeId or ""))
print("From " .. (result.start or "") .. " to " .. (result.end or ""))
print("Status: " .. (result.status or ""))
print("Type: " .. (result.typeName or ""))

list_reports

Generate a custom report with specified employee fields.

Parameters

Name	Type	Required	Description
`fields`	array	yes	List of employee fields to include (e.g., `{"firstName", "lastName", "jobTitle", "department", "workEmail", "hireDate", "status"}`)
`title`	string	no	Optional title for the report

Available Fields

Common field names: firstName, lastName, jobTitle, department, workEmail, hireDate, status, location, supervisor, workPhone, mobilePhone, address1, city, state, zipcode, country, gender, maritalStatus, birthday, ssn, payRate, payType, payPer, employeeNumber.

Example

local result = app.integrations.bamboohr.list_reports({
  fields = {"firstName", "lastName", "jobTitle", "department", "hireDate"},
  title = "Engineering Team Report"
})

for _, row in ipairs(result.employees or {}) do
  print(row.firstName .. " " .. row.lastName .. " — " .. (row.jobTitle or "N/A"))
end

get_current_user

Get information about the currently authenticated BambooHR user.

Parameters

None.

Example

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

print("User: " .. (result.firstName or "") .. " " .. (result.lastName or ""))
print("Email: " .. (result.email or "N/A"))

Multi-Account Usage

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

-- Default account (always works)
app.integrations.bamboohr.list_employees({})

-- Explicit default (portable across setups)
app.integrations.bamboohr.default.list_employees({})

-- Named accounts
app.integrations.bamboohr.us_office.list_employees({})
app.integrations.bamboohr.eu_office.list_employees({})

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

Raw agent markdown

# BambooHR — Lua API Reference

## list_employees

List all employees from the company directory.

### Parameters

None.

### Example

```lua
local result = app.integrations.bamboohr.list_employees({})

for _, emp in ipairs(result.employees) do
  print(emp.id .. ": " .. emp.firstName .. " " .. emp.lastName .. " — " .. (emp.jobTitle or "N/A"))
end
```

---

## get_employee

Get detailed information for a specific employee.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `employee_id` | integer | yes | The BambooHR employee ID |
| `fields` | array | no | Fields to retrieve (e.g., `{"firstName", "lastName", "jobTitle", "workEmail", "department", "hireDate", "status"}`) |

### Example

```lua
local result = app.integrations.bamboohr.get_employee({
  employee_id = 42,
  fields = {"firstName", "lastName", "jobTitle", "workEmail", "hireDate"}
})

print(result.firstName .. " " .. result.lastName)
print("Title: " .. (result.jobTitle or "N/A"))
print("Email: " .. (result.workEmail or "N/A"))
print("Hired: " .. (result.hireDate or "N/A"))
```

---

## create_employee

Create a new employee record in BambooHR.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `first_name` | string | yes | Employee first name |
| `last_name` | string | yes | Employee last name |
| `work_email` | string | no | Work email address |
| `job_title` | string | no | Job title |
| `department` | string | no | Department name |
| `hire_date` | string | no | Hire date (YYYY-MM-DD) |
| `status` | string | no | Employment status (e.g., "Active") |
| `location` | string | no | Work location |
| `supervisor_id` | integer | no | Employee ID of the supervisor |

### Example

```lua
local result = app.integrations.bamboohr.create_employee({
  first_name = "Jane",
  last_name = "Doe",
  work_email = "jane.doe@example.com",
  job_title = "Software Engineer",
  department = "Engineering",
  hire_date = "2026-04-01"
})

print("Created employee: " .. tostring(result.id or "success"))
```

---

## update_employee

Update an existing employee record.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `employee_id` | integer | yes | The BambooHR employee ID to update |
| `first_name` | string | no | Updated first name |
| `last_name` | string | no | Updated last name |
| `work_email` | string | no | Updated work email |
| `job_title` | string | no | Updated job title |
| `department` | string | no | Updated department |
| `status` | string | no | Updated employment status |
| `location` | string | no | Updated work location |
| `supervisor_id` | integer | no | Updated supervisor employee ID |

### Example

```lua
local result = app.integrations.bamboohr.update_employee({
  employee_id = 42,
  job_title = "Senior Software Engineer",
  department = "Engineering"
})

print("Employee updated: " .. tostring(result.success or "done"))
```

---

## list_departments

List all company departments.

### Parameters

None.

### Example

```lua
local result = app.integrations.bamboohr.list_departments({})

for _, dept in ipairs(result.departments or {}) do
  print(dept.name .. " (ID: " .. tostring(dept.id) .. ")")
end
```

---

## list_time_off_requests

List time-off requests with optional filters.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `start` | string | no | Start date filter (YYYY-MM-DD) |
| `end` | string | no | End date filter (YYYY-MM-DD) |
| `status` | string | no | Filter by status ("approved", "pending", "denied") |
| `employee_id` | integer | no | Filter by employee ID |
| `type_id` | integer | no | Filter by time-off type ID |

### Example

```lua
local result = app.integrations.bamboohr.list_time_off_requests({
  start = "2026-04-01",
  end = "2026-04-30",
  status = "approved"
})

for _, req in ipairs(result.requests or {}) do
  print("Employee " .. req.employeeId .. ": " .. req.start .. " to " .. req.end .. " (" .. req.typeName .. ")")
end
```

---

## get_time_off_request

Get detailed information for a specific time-off request by its ID.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `request_id` | integer | yes | The BambooHR time-off request ID |

### Example

```lua
local result = app.integrations.bamboohr.get_time_off_request({
  request_id = 123
})

print("Request for employee " .. (result.employeeId or ""))
print("From " .. (result.start or "") .. " to " .. (result.end or ""))
print("Status: " .. (result.status or ""))
print("Type: " .. (result.typeName or ""))
```

---

## list_reports

Generate a custom report with specified employee fields.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `fields` | array | yes | List of employee fields to include (e.g., `{"firstName", "lastName", "jobTitle", "department", "workEmail", "hireDate", "status"}`) |
| `title` | string | no | Optional title for the report |

### Available Fields

Common field names: `firstName`, `lastName`, `jobTitle`, `department`, `workEmail`, `hireDate`, `status`, `location`, `supervisor`, `workPhone`, `mobilePhone`, `address1`, `city`, `state`, `zipcode`, `country`, `gender`, `maritalStatus`, `birthday`, `ssn`, `payRate`, `payType`, `payPer`, `employeeNumber`.

### Example

```lua
local result = app.integrations.bamboohr.list_reports({
  fields = {"firstName", "lastName", "jobTitle", "department", "hireDate"},
  title = "Engineering Team Report"
})

for _, row in ipairs(result.employees or {}) do
  print(row.firstName .. " " .. row.lastName .. " — " .. (row.jobTitle or "N/A"))
end
```

---

## get_current_user

Get information about the currently authenticated BambooHR user.

### Parameters

None.

### Example

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

print("User: " .. (result.firstName or "") .. " " .. (result.lastName or ""))
print("Email: " .. (result.email or "N/A"))
```

---

## Multi-Account Usage

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

```lua
-- Default account (always works)
app.integrations.bamboohr.list_employees({})

-- Explicit default (portable across setups)
app.integrations.bamboohr.default.list_employees({})

-- Named accounts
app.integrations.bamboohr.us_office.list_employees({})
app.integrations.bamboohr.eu_office.list_employees({})
```

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

Metadata-derived Lua example

local result = app.integrations.bamboohr.list_employees({})
print(result)

Functions

list_employees Read

List employees from the BambooHR company directory. Returns employee names, job titles, departments, and other directory fields.

Lua path: app.integrations.bamboohr.list_employees
Full name: bamboohr.bamboohr_list_employees

Parameter	Type	Required	Description
No parameters.

get_employee Read

Get detailed information for a specific BambooHR employee by ID. Optionally specify which fields to retrieve.

Lua path: app.integrations.bamboohr.get_employee
Full name: bamboohr.bamboohr_get_employee

Parameter	Type	Required	Description
`employee_id`	integer	yes	The BambooHR employee ID.
`fields`	array	no	List of fields to retrieve (e.g., ["firstName", "lastName", "jobTitle", "workEmail", "department", "hireDate", "status"]). If omitted, returns default fields.

create_employee Write

Create a new employee in BambooHR. Provide employee data such as first name, last name, work email, job title, and department.

Lua path: app.integrations.bamboohr.create_employee
Full name: bamboohr.bamboohr_create_employee

Parameter	Type	Required	Description
`first_name`	string	yes	Employee first name.
`last_name`	string	yes	Employee last name.
`work_email`	string	no	Employee work email address.
`job_title`	string	no	Job title.
`department`	string	no	Department name.
`hire_date`	string	no	Hire date (YYYY-MM-DD).
`status`	string	no	Employment status (e.g., "Active", "Inactive").
`location`	string	no	Work location.
`supervisor_id`	integer	no	Employee ID of the supervisor/manager.

update_employee Write

Update an existing employee in BambooHR. Provide the employee ID and the fields to update.

Lua path: app.integrations.bamboohr.update_employee
Full name: bamboohr.bamboohr_update_employee

Parameter	Type	Required	Description
`employee_id`	integer	yes	The BambooHR employee ID to update.
`first_name`	string	no	Updated first name.
`last_name`	string	no	Updated last name.
`work_email`	string	no	Updated work email.
`job_title`	string	no	Updated job title.
`department`	string	no	Updated department.
`status`	string	no	Updated employment status.
`location`	string	no	Updated work location.
`supervisor_id`	integer	no	Updated supervisor employee ID.

list_departments Read

List all departments in the BambooHR company account.

Lua path: app.integrations.bamboohr.list_departments
Full name: bamboohr.bamboohr_list_departments

Parameter	Type	Required	Description
No parameters.

list_time_off_requests Read

List time-off requests from BambooHR. Optionally filter by date range, status, or employee ID.

Lua path: app.integrations.bamboohr.list_time_off_requests
Full name: bamboohr.bamboohr_list_time_off_requests

Parameter	Type	Required	Description
`start`	string	no	Start date for filtering requests (YYYY-MM-DD).
`end`	string	no	End date for filtering requests (YYYY-MM-DD).
`status`	string	no	Filter by status (e.g., "approved", "pending", "denied").
`employee_id`	integer	no	Filter by employee ID.
`type_id`	integer	no	Filter by time-off type ID.

get_time_off_request Read

Get detailed information for a specific BambooHR time-off request by its ID.

Lua path: app.integrations.bamboohr.get_time_off_request
Full name: bamboohr.bamboohr_get_time_off_request

Parameter	Type	Required	Description
`request_id`	integer	yes	The BambooHR time-off request ID.

list_reports Read

Generate a custom report from BambooHR. Specify which employee fields to include in the report results.

Lua path: app.integrations.bamboohr.list_reports
Full name: bamboohr.bamboohr_list_reports

Parameter	Type	Required	Description
`fields`	array	yes	List of employee fields to include in the report (e.g., ["firstName", "lastName", "jobTitle", "department", "workEmail", "hireDate", "status"]).
`title`	string	no	Optional title for the custom report.

get_current_user Read

Get information about the currently authenticated BambooHR user.

Lua path: app.integrations.bamboohr.get_current_user
Full name: bamboohr.bamboohr_get_current_user

Parameter	Type	Required	Description
No parameters.