Can I use Onfleet as a CLI?

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

Can I expose Onfleet through MCP?

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

Where are Onfleet credentials stored?

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

Can I deny write access for Onfleet MCP tools?

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

data

Onfleet Lua API for KosmoKrator Agents

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

Lua Namespace

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

Inline Lua call

kosmo integrations:lua --eval 'dump(app.integrations.onfleet.list_tasks({state = 1, worker = "example_worker", organization = "example_organization", team = "example_team", completeBeforeAfter = "example_completeBeforeAfter", completeBeforeBefore = "example_completeBeforeBefore", from = "example_from", to = "example_to"}))' --json

Read Lua docs headlessly

kosmo integrations:lua --eval 'print(docs.read("onfleet"))' --json
kosmo integrations:lua --eval 'print(docs.read("onfleet.list_tasks"))' --json

Workflow file

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

workflow.lua

local onfleet = app.integrations.onfleet
local result = onfleet.list_tasks({state = 1, worker = "example_worker", organization = "example_organization", team = "example_team", completeBeforeAfter = "example_completeBeforeAfter", completeBeforeBefore = "example_completeBeforeBefore", from = "example_from", to = "example_to"})

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

MCP-only Lua

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

Onfleet — Lua API Reference

list_tasks

List delivery tasks with optional filters.

Parameters

Name	Type	Required	Description
`state`	integer	no	Task state: 0=unassigned, 1=assigned, 2=active, 3=completed
`worker`	string	no	Filter by worker ID
`organization`	string	no	Filter by organization ID
`team`	string	no	Filter by team ID
`completeBeforeAfter`	string	no	ISO 8601 — tasks completed after this time
`completeBeforeBefore`	string	no	ISO 8601 — tasks with completeBefore before this time
`from`	string	no	ISO 8601 — tasks created after this time
`to`	string	no	ISO 8601 — tasks created before this time
`lastUpdated`	string	no	ISO 8601 — tasks updated after this time
`query`	string	no	Search by recipient name, notes, or tracking URL

Task States

Value	Description
0	Unassigned
1	Assigned
2	Active (in-progress)
3	Completed

Examples

List all unassigned tasks

local result = app.integrations.onfleet.list_tasks({
  state = 0
})

for _, task in ipairs(result.tasks) do
  print(task.id .. ": " .. task.destination.address.street)
end

List completed tasks for a worker

local result = app.integrations.onfleet.list_tasks({
  state = 3,
  worker = "WORKER_ID"
})

List tasks created today

local result = app.integrations.onfleet.list_tasks({
  from = "2026-04-05T00:00:00Z",
  to = "2026-04-05T23:59:59Z"
})

get_task

Get detailed information about a specific task.

Parameters

Name	Type	Required	Description
`task_id`	string	yes	The Onfleet task ID (24-char hex string)

Example

local result = app.integrations.onfleet.get_task({
  task_id = "TASK_ID"
})

print("Status: " .. result.state)
print("Destination: " .. result.destination.address.street)
print("Recipient: " .. result.recipients[1].name)

create_task

Create a new delivery task.

Parameters

Name	Type	Required	Description
`destination_address`	string	yes	Destination street address
`recipient_name`	string	yes	Recipient full name
`recipient_phone`	string	no	Recipient phone (E.164 format)
`recipient_email`	string	no	Recipient email
`notes`	string	no	Driver notes
`complete_after`	string	no	ISO 8601 — earliest completion time
`complete_before`	string	no	ISO 8601 — latest completion deadline
`pickup_task`	boolean	no	True if this is a pickup (default: false)
`worker`	string	no	Worker ID to assign
`team`	string	no	Team ID to assign
`quantity`	integer	no	Number of units
`service_time`	integer	no	Estimated service time in seconds

Example

local result = app.integrations.onfleet.create_task({
  destination_address = "123 Main St, San Francisco, CA 94105",
  recipient_name = "Jane Doe",
  recipient_phone = "+14155551234",
  notes = "Leave at front door",
  complete_before = "2026-04-05T18:00:00Z",
  team = "TEAM_ID"
})

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

update_task

Update an existing task. Only provided fields are changed.

Parameters

Name	Type	Required	Description
`task_id`	string	yes	Task ID to update
`destination_address`	string	no	New destination address
`notes`	string	no	Updated driver notes
`complete_after`	string	no	Updated earliest completion time (ISO 8601)
`complete_before`	string	no	Updated latest completion deadline (ISO 8601)
`worker`	string	no	New worker ID (empty to unassign)
`team`	string	no	New team ID
`quantity`	integer	no	Updated quantity
`service_time`	integer	no	Updated service time in seconds

Example

local result = app.integrations.onfleet.update_task({
  task_id = "TASK_ID",
  notes = "Updated: ring doorbell twice",
  worker = "NEW_WORKER_ID"
})

delete_task

Delete a task permanently.

Parameters

Name	Type	Required	Description
`task_id`	string	yes	Task ID to delete

Example

local result = app.integrations.onfleet.delete_task({
  task_id = "TASK_ID"
})

print(result) -- "Task 'TASK_ID' has been deleted."

list_workers

List all workers (drivers).

Parameters

Name	Type	Required	Description
`teams`	array	no	Array of team IDs to filter by
`states`	array	no	Worker states: 0=off-duty, 1=on-duty
`name`	string	no	Filter by name
`phone`	string	no	Filter by phone
`query`	string	no	General search query

Example

local result = app.integrations.onfleet.list_workers({
  states = {1}
})

for _, worker in ipairs(result.workers) do
  print(worker.name .. " - " .. (worker.vehicle and worker.vehicle.description or "no vehicle"))
end

list_teams

List all teams in the organization.

Parameters

None.

Example

local result = app.integrations.onfleet.list_teams()

for _, team in ipairs(result) do
  print(team.name .. " (" .. #team.workers .. " workers)")
end

list_recipients

List recipients (delivery customers).

Parameters

Name	Type	Required	Description
`name`	string	no	Filter by name
`phone`	string	no	Filter by phone
`email`	string	no	Filter by email
`query`	string	no	General search query

Example

local result = app.integrations.onfleet.list_recipients({
  name = "Jane"
})

for _, recipient in ipairs(result) do
  print(recipient.name .. " - " .. (recipient.phone or "no phone"))
end

get_current_user

Get the currently authenticated Onfleet user profile.

Parameters

None.

Example

local result = app.integrations.onfleet.get_current_user()

print("Logged in as: " .. result.email)
print("Organization: " .. result.organization)

Multi-Account Usage

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

-- Default account (always works)
app.integrations.onfleet.list_tasks({state = 0})

-- Explicit default (portable across setups)
app.integrations.onfleet.default.list_tasks({state = 0})

-- Named accounts
app.integrations.onfleet.us_fleet.list_tasks({})
app.integrations.onfleet.eu_fleet.list_tasks({})

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

Raw agent markdown

# Onfleet — Lua API Reference

## list_tasks

List delivery tasks with optional filters.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `state` | integer | no | Task state: 0=unassigned, 1=assigned, 2=active, 3=completed |
| `worker` | string | no | Filter by worker ID |
| `organization` | string | no | Filter by organization ID |
| `team` | string | no | Filter by team ID |
| `completeBeforeAfter` | string | no | ISO 8601 — tasks completed after this time |
| `completeBeforeBefore` | string | no | ISO 8601 — tasks with completeBefore before this time |
| `from` | string | no | ISO 8601 — tasks created after this time |
| `to` | string | no | ISO 8601 — tasks created before this time |
| `lastUpdated` | string | no | ISO 8601 — tasks updated after this time |
| `query` | string | no | Search by recipient name, notes, or tracking URL |

### Task States

| Value | Description |
|-------|-------------|
| 0 | Unassigned |
| 1 | Assigned |
| 2 | Active (in-progress) |
| 3 | Completed |

### Examples

#### List all unassigned tasks

```lua
local result = app.integrations.onfleet.list_tasks({
  state = 0
})

for _, task in ipairs(result.tasks) do
  print(task.id .. ": " .. task.destination.address.street)
end
```

#### List completed tasks for a worker

```lua
local result = app.integrations.onfleet.list_tasks({
  state = 3,
  worker = "WORKER_ID"
})
```

#### List tasks created today

```lua
local result = app.integrations.onfleet.list_tasks({
  from = "2026-04-05T00:00:00Z",
  to = "2026-04-05T23:59:59Z"
})
```

---

## get_task

Get detailed information about a specific task.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `task_id` | string | yes | The Onfleet task ID (24-char hex string) |

### Example

```lua
local result = app.integrations.onfleet.get_task({
  task_id = "TASK_ID"
})

print("Status: " .. result.state)
print("Destination: " .. result.destination.address.street)
print("Recipient: " .. result.recipients[1].name)
```

---

## create_task

Create a new delivery task.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `destination_address` | string | yes | Destination street address |
| `recipient_name` | string | yes | Recipient full name |
| `recipient_phone` | string | no | Recipient phone (E.164 format) |
| `recipient_email` | string | no | Recipient email |
| `notes` | string | no | Driver notes |
| `complete_after` | string | no | ISO 8601 — earliest completion time |
| `complete_before` | string | no | ISO 8601 — latest completion deadline |
| `pickup_task` | boolean | no | True if this is a pickup (default: false) |
| `worker` | string | no | Worker ID to assign |
| `team` | string | no | Team ID to assign |
| `quantity` | integer | no | Number of units |
| `service_time` | integer | no | Estimated service time in seconds |

### Example

```lua
local result = app.integrations.onfleet.create_task({
  destination_address = "123 Main St, San Francisco, CA 94105",
  recipient_name = "Jane Doe",
  recipient_phone = "+14155551234",
  notes = "Leave at front door",
  complete_before = "2026-04-05T18:00:00Z",
  team = "TEAM_ID"
})

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

---

## update_task

Update an existing task. Only provided fields are changed.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `task_id` | string | yes | Task ID to update |
| `destination_address` | string | no | New destination address |
| `notes` | string | no | Updated driver notes |
| `complete_after` | string | no | Updated earliest completion time (ISO 8601) |
| `complete_before` | string | no | Updated latest completion deadline (ISO 8601) |
| `worker` | string | no | New worker ID (empty to unassign) |
| `team` | string | no | New team ID |
| `quantity` | integer | no | Updated quantity |
| `service_time` | integer | no | Updated service time in seconds |

### Example

```lua
local result = app.integrations.onfleet.update_task({
  task_id = "TASK_ID",
  notes = "Updated: ring doorbell twice",
  worker = "NEW_WORKER_ID"
})
```

---

## delete_task

Delete a task permanently.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `task_id` | string | yes | Task ID to delete |

### Example

```lua
local result = app.integrations.onfleet.delete_task({
  task_id = "TASK_ID"
})

print(result) -- "Task 'TASK_ID' has been deleted."
```

---

## list_workers

List all workers (drivers).

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `teams` | array | no | Array of team IDs to filter by |
| `states` | array | no | Worker states: 0=off-duty, 1=on-duty |
| `name` | string | no | Filter by name |
| `phone` | string | no | Filter by phone |
| `query` | string | no | General search query |

### Example

```lua
local result = app.integrations.onfleet.list_workers({
  states = {1}
})

for _, worker in ipairs(result.workers) do
  print(worker.name .. " - " .. (worker.vehicle and worker.vehicle.description or "no vehicle"))
end
```

---

## list_teams

List all teams in the organization.

### Parameters

None.

### Example

```lua
local result = app.integrations.onfleet.list_teams()

for _, team in ipairs(result) do
  print(team.name .. " (" .. #team.workers .. " workers)")
end
```

---

## list_recipients

List recipients (delivery customers).

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `name` | string | no | Filter by name |
| `phone` | string | no | Filter by phone |
| `email` | string | no | Filter by email |
| `query` | string | no | General search query |

### Example

```lua
local result = app.integrations.onfleet.list_recipients({
  name = "Jane"
})

for _, recipient in ipairs(result) do
  print(recipient.name .. " - " .. (recipient.phone or "no phone"))
end
```

---

## get_current_user

Get the currently authenticated Onfleet user profile.

### Parameters

None.

### Example

```lua
local result = app.integrations.onfleet.get_current_user()

print("Logged in as: " .. result.email)
print("Organization: " .. result.organization)
```

---

## Multi-Account Usage

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

```lua
-- Default account (always works)
app.integrations.onfleet.list_tasks({state = 0})

-- Explicit default (portable across setups)
app.integrations.onfleet.default.list_tasks({state = 0})

-- Named accounts
app.integrations.onfleet.us_fleet.list_tasks({})
app.integrations.onfleet.eu_fleet.list_tasks({})
```

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

Metadata-derived Lua example

local result = app.integrations.onfleet.list_tasks({state = 1, worker = "example_worker", organization = "example_organization", team = "example_team", completeBeforeAfter = "example_completeBeforeAfter", completeBeforeBefore = "example_completeBeforeBefore", from = "example_from", to = "example_to"})
print(result)

Functions

list_tasks Read

List delivery tasks from Onfleet. Filter by state (0=unassigned, 1=assigned, 2=active, 3=completed), worker, team, or time range. Returns task details including destination, recipient, and completion status.

Lua path: app.integrations.onfleet.list_tasks
Full name: onfleet.onfleet_list_tasks

Parameter	Type	Required	Description
`state`	integer	no	Task state filter: 0=unassigned, 1=assigned, 2=active, 3=completed.
`worker`	string	no	Filter tasks assigned to a specific worker ID.
`organization`	string	no	Filter tasks by organization ID.
`team`	string	no	Filter tasks by team ID.
`completeBeforeAfter`	string	no	ISO 8601 timestamp — list tasks completed after this time.
`completeBeforeBefore`	string	no	ISO 8601 timestamp — list tasks with completeBefore before this time.
`from`	string	no	ISO 8601 timestamp — list tasks created after this time.
`to`	string	no	ISO 8601 timestamp — list tasks created before this time.
`lastUpdated`	string	no	ISO 8601 timestamp — list tasks updated after this time.
`query`	string	no	Search query to filter tasks by recipient name, notes, or tracking URL.

get_task Read

Get detailed information about a specific delivery task by its ID. Returns destination, recipient, worker assignment, completion details, and tracking info.

Lua path: app.integrations.onfleet.get_task
Full name: onfleet.onfleet_get_task

Parameter	Type	Required	Description
`task_id`	string	yes	The Onfleet task ID (24-character hex string).

create_task Write

Create a new delivery task in Onfleet. Requires a destination address and recipient details. Optionally assign to a worker or team, set time windows, and add notes.

Lua path: app.integrations.onfleet.create_task
Full name: onfleet.onfleet_create_task

Parameter	Type	Required	Description
`destination_address`	string	yes	Destination street address (e.g., "123 Main St, San Francisco, CA 94105").
`destination_address_unparsed`	string	no	Full unparsed address string if you prefer Onfleet to geocode it.
`recipient_name`	string	yes	Recipient full name.
`recipient_phone`	string	no	Recipient phone number (E.164 format preferred).
`recipient_email`	string	no	Recipient email address.
`notes`	string	no	Notes for the driver about the task.
`complete_after`	string	no	ISO 8601 timestamp — earliest time task can be completed.
`complete_before`	string	no	ISO 8601 timestamp — latest time task must be completed by.
`pickup_task`	boolean	no	Set to true if this is a pickup task instead of a dropoff.
`worker`	string	no	Worker ID to directly assign the task to.
`team`	string	no	Team ID to assign the task to (for auto-dispatch).
`merchant`	string	no	Merchant/organization ID for the task.
`executor`	string	no	Organization ID of the executor (for interconnected fleets).
`quantity`	integer	no	Number of units for the task.
`service_time`	integer	no	Estimated service time in seconds.
`appearance`	array	no	Visual customization: {"triangleColor": "#RRGGBB"}.
`metadata`	array	no	Custom metadata array: [{"name": "key", "value": "val", "visibility": ["worker"]}].

update_task Write

Update an existing delivery task in Onfleet. Only the fields you provide will be changed. You can update destination, assignment, notes, time windows, and more.

Lua path: app.integrations.onfleet.update_task
Full name: onfleet.onfleet_update_task

Parameter	Type	Required	Description
`task_id`	string	yes	The Onfleet task ID to update (24-character hex string).
`destination_address`	string	no	New destination address.
`notes`	string	no	Updated driver notes.
`complete_after`	string	no	ISO 8601 timestamp — earliest completion time.
`complete_before`	string	no	ISO 8601 timestamp — latest completion deadline.
`worker`	string	no	Worker ID to assign (pass null or empty to unassign).
`team`	string	no	Team ID to assign to.
`quantity`	integer	no	Updated quantity.
`service_time`	integer	no	Updated estimated service time in seconds.
`appearance`	array	no	Visual customization: {"triangleColor": "#RRGGBB"}.
`metadata`	array	no	Updated custom metadata.

delete_task Write

Delete a delivery task from Onfleet. Only unassigned or unsuccessfully completed tasks can be deleted. This action is permanent.

Lua path: app.integrations.onfleet.delete_task
Full name: onfleet.onfleet_delete_task

Parameter	Type	Required	Description
`task_id`	string	yes	The Onfleet task ID to delete (24-character hex string).

list_workers Read

List all workers (drivers) in Onfleet. Optionally filter by team or worker state. Returns worker name, phone, vehicle details, and current status.

Lua path: app.integrations.onfleet.list_workers
Full name: onfleet.onfleet_list_workers

Parameter	Type	Required	Description
`teams`	array	no	Array of team IDs to filter workers by.
`states`	array	no	Array of worker states to filter by: 0=off-duty, 1=on-duty.
`name`	string	no	Filter workers by name.
`phone`	string	no	Filter workers by phone number.
`query`	string	no	General search query for workers.

list_teams Read

List all teams in your Onfleet organization. Returns team name, manager, assigned workers, and hub location.

Lua path: app.integrations.onfleet.list_teams
Full name: onfleet.onfleet_list_teams

Parameter	Type	Required	Description
No parameters.

list_recipients Read

List recipients (delivery customers) from Onfleet. Search by name, phone, or email. Returns recipient contact details.

Lua path: app.integrations.onfleet.list_recipients
Full name: onfleet.onfleet_list_recipients

Parameter	Type	Required	Description
`name`	string	no	Filter recipients by name.
`phone`	string	no	Filter recipients by phone number.
`email`	string	no	Filter recipients by email address.
`query`	string	no	General search query for recipients.

get_current_user Read

Get the currently authenticated Onfleet user profile. Returns name, email, organization, and account details. Useful for verifying API connectivity.

Lua path: app.integrations.onfleet.get_current_user
Full name: onfleet.onfleet_get_current_user

Parameter	Type	Required	Description
No parameters.