KosmoKrator

productivity

Cloudways Lua API for KosmoKrator Agents

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

Lua Namespace

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

Inline Lua call 
kosmo integrations:lua --eval 'dump(app.integrations.cloudways.list_servers({}))' --json
Read Lua docs headlessly 
kosmo integrations:lua --eval 'print(docs.read("cloudways"))' --json
kosmo integrations:lua --eval 'print(docs.read("cloudways.list_servers"))' --json

Workflow file

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

workflow.lua 
local cloudways = app.integrations.cloudways
local result = cloudways.list_servers({})

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

MCP-only Lua

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

Cloudways — Lua API Reference

list_servers

List all servers in the Cloudways account.

Parameters

None.

Example

local result = app.integrations.cloudways.list_servers({})

for _, server in ipairs(result.servers) do
  print(server.label .. " (" .. server.status .. ") - " .. server.server_ips[1])
end

get_server

Get details for a specific Cloudways server.

Parameters

NameTypeRequiredDescription
server_idintegeryesThe server ID to look up

Example

local result = app.integrations.cloudways.get_server({ server_id = 12345 })
local s = result.server
print(s.label .. " - " .. s.server_ips[1] .. " - " .. s.os)

list_apps

List all applications across all servers in the Cloudways account.

Parameters

None.

Example

local result = app.integrations.cloudways.list_apps({})

for _, app in ipairs(result.apps) do
  print(app.label .. " (" .. app.application .. ") on server " .. app.server_id)
end

get_app

Get details for a specific Cloudways application.

Parameters

NameTypeRequiredDescription
server_idintegeryesThe server ID the application belongs to
app_idintegeryesThe application ID to look up

Example

local result = app.integrations.cloudways.get_app({ server_id = 12345, app_id = 67890 })
local a = result.app
print(a.label .. " - " .. a.application .. " - " .. a.app_fqdn)

list_domains

List domains for a specific Cloudways application.

Parameters

NameTypeRequiredDescription
server_idintegeryesThe server ID the application belongs to
app_idintegeryesThe application ID to list domains for

Example

local result = app.integrations.cloudways.list_domains({ server_id = 12345, app_id = 67890 })

for _, domain in ipairs(result.domains) do
  print(domain.fqdn .. " - primary: " .. tostring(domain.is_primary))
end

list_projects

List all projects in the Cloudways account.

Parameters

None.

Example

local result = app.integrations.cloudways.list_projects({})

for _, project in ipairs(result.projects) do
  print(project.name .. " (ID: " .. project.id .. ")")
end

get_current_user

Get the current authenticated Cloudways account information.

Parameters

None.

Example

local result = app.integrations.cloudways.get_current_user({})
print("Account: " .. result.me.email .. " (" .. result.me.name .. ")")

Multi-Account Usage

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

-- Default account (always works)
app.integrations.cloudways.list_servers({})

-- Explicit default (portable across setups)
app.integrations.cloudways.default.list_servers({})

-- Named accounts
app.integrations.cloudways.production.list_servers({})
app.integrations.cloudways.staging.list_servers({})

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

Raw agent markdown 
# Cloudways — Lua API Reference

## list_servers

List all servers in the Cloudways account.

### Parameters

None.

### Example

```lua
local result = app.integrations.cloudways.list_servers({})

for _, server in ipairs(result.servers) do
  print(server.label .. " (" .. server.status .. ") - " .. server.server_ips[1])
end
```

---

## get_server

Get details for a specific Cloudways server.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `server_id` | integer | yes | The server ID to look up |

### Example

```lua
local result = app.integrations.cloudways.get_server({ server_id = 12345 })
local s = result.server
print(s.label .. " - " .. s.server_ips[1] .. " - " .. s.os)
```

---

## list_apps

List all applications across all servers in the Cloudways account.

### Parameters

None.

### Example

```lua
local result = app.integrations.cloudways.list_apps({})

for _, app in ipairs(result.apps) do
  print(app.label .. " (" .. app.application .. ") on server " .. app.server_id)
end
```

---

## get_app

Get details for a specific Cloudways application.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `server_id` | integer | yes | The server ID the application belongs to |
| `app_id` | integer | yes | The application ID to look up |

### Example

```lua
local result = app.integrations.cloudways.get_app({ server_id = 12345, app_id = 67890 })
local a = result.app
print(a.label .. " - " .. a.application .. " - " .. a.app_fqdn)
```

---

## list_domains

List domains for a specific Cloudways application.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `server_id` | integer | yes | The server ID the application belongs to |
| `app_id` | integer | yes | The application ID to list domains for |

### Example

```lua
local result = app.integrations.cloudways.list_domains({ server_id = 12345, app_id = 67890 })

for _, domain in ipairs(result.domains) do
  print(domain.fqdn .. " - primary: " .. tostring(domain.is_primary))
end
```

---

## list_projects

List all projects in the Cloudways account.

### Parameters

None.

### Example

```lua
local result = app.integrations.cloudways.list_projects({})

for _, project in ipairs(result.projects) do
  print(project.name .. " (ID: " .. project.id .. ")")
end
```

---

## get_current_user

Get the current authenticated Cloudways account information.

### Parameters

None.

### Example

```lua
local result = app.integrations.cloudways.get_current_user({})
print("Account: " .. result.me.email .. " (" .. result.me.name .. ")")
```

---

## Multi-Account Usage

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

```lua
-- Default account (always works)
app.integrations.cloudways.list_servers({})

-- Explicit default (portable across setups)
app.integrations.cloudways.default.list_servers({})

-- Named accounts
app.integrations.cloudways.production.list_servers({})
app.integrations.cloudways.staging.list_servers({})
```

All functions are identical across accounts — only the credentials differ.
Metadata-derived Lua example 
local result = app.integrations.cloudways.list_servers({})
print(result)

Functions

list_servers Read

List all servers in the Cloudways account.

Lua path
app.integrations.cloudways.list_servers
Full name
cloudways.cloudways_list_servers
ParameterTypeRequiredDescription
No parameters.
get_server Read

Get details for a specific Cloudways server.

Lua path
app.integrations.cloudways.get_server
Full name
cloudways.cloudways_get_server
ParameterTypeRequiredDescription
server_id integer yes The server ID to look up.
list_apps Read

List all applications across all servers in the Cloudways account.

Lua path
app.integrations.cloudways.list_apps
Full name
cloudways.cloudways_list_apps
ParameterTypeRequiredDescription
No parameters.
get_app Read

Get details for a specific Cloudways application.

Lua path
app.integrations.cloudways.get_app
Full name
cloudways.cloudways_get_app
ParameterTypeRequiredDescription
server_id integer yes The server ID the application belongs to.
app_id integer yes The application ID to look up.
list_domains Read

List domains for a specific Cloudways application.

Lua path
app.integrations.cloudways.list_domains
Full name
cloudways.cloudways_list_domains
ParameterTypeRequiredDescription
server_id integer yes The server ID the application belongs to.
app_id integer yes The application ID to list domains for.
list_projects Read

List all projects in the Cloudways account.

Lua path
app.integrations.cloudways.list_projects
Full name
cloudways.cloudways_list_projects
ParameterTypeRequiredDescription
No parameters.
get_current_user Read

Get the current authenticated Cloudways account information.

Lua path
app.integrations.cloudways.get_current_user
Full name
cloudways.cloudways_get_current_user
ParameterTypeRequiredDescription
No parameters.