KosmoKrator

data

Heroku Lua API for KosmoKrator Agents

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

Lua Namespace

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

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

Workflow file

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

workflow.lua 
local heroku = app.integrations.heroku
local result = heroku.list_apps({})

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

MCP-only Lua

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

Heroku — Lua API Reference

list_apps

List all Heroku apps the authenticated user has access to.

Parameters

None.

Example

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

for _, app in ipairs(result) do
  print(app.name .. " (" .. app.region.name .. ") - " .. app.web_url)
end

get_app

Get details for a specific Heroku app.

Parameters

NameTypeRequiredDescription
app_idstringyesThe app ID or name (e.g., "my-app" or the UUID)

Example

local result = app.integrations.heroku.get_app({ app_id = "my-app" })
print(result.name .. " - " .. result.stack .. " - " .. result.git_url)

list_dynos

List all dynos for a given Heroku app.

Parameters

NameTypeRequiredDescription
app_idstringyesThe app ID or name

Example

local result = app.integrations.heroku.list_dynos({ app_id = "my-app" })

for _, dyno in ipairs(result) do
  print(dyno.name .. " (" .. dyno.type .. ") - " .. dyno.state .. " - size: " .. dyno.size)
end

list_addons

List all add-ons attached to a given Heroku app.

Parameters

NameTypeRequiredDescription
app_idstringyesThe app ID or name

Example

local result = app.integrations.heroku.list_addons({ app_id = "my-app" })

for _, addon in ipairs(result) do
  print(addon.name .. " (" .. addon.plan.name .. ") - " .. addon.state)
end

list_domains

List all domains for a given Heroku app.

Parameters

NameTypeRequiredDescription
app_idstringyesThe app ID or name

Example

local result = app.integrations.heroku.list_domains({ app_id = "my-app" })

for _, domain in ipairs(result) do
  print(domain.hostname .. " (" .. domain.kind .. ") - " .. domain.status)
end

list_collaborators

List all collaborators for a given Heroku app.

Parameters

NameTypeRequiredDescription
app_idstringyesThe app ID or name

Example

local result = app.integrations.heroku.list_collaborators({ app_id = "my-app" })

for _, collab in ipairs(result) do
  print(collab.user.email .. " - role: " .. collab.role)
end

get_current_user

Get the current authenticated account information.

Parameters

None.

Example

local result = app.integrations.heroku.get_current_user({})
print("Account: " .. result.email .. " - verified: " .. tostring(result.verified))

Multi-Account Usage

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

-- Default account (always works)
app.integrations.heroku.list_apps({})

-- Explicit default (portable across setups)
app.integrations.heroku.default.list_apps({})

-- Named accounts
app.integrations.heroku.production.list_apps({})
app.integrations.heroku.staging.list_apps({})

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

Raw agent markdown 
# Heroku — Lua API Reference

## list_apps

List all Heroku apps the authenticated user has access to.

### Parameters

None.

### Example

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

for _, app in ipairs(result) do
  print(app.name .. " (" .. app.region.name .. ") - " .. app.web_url)
end
```

---

## get_app

Get details for a specific Heroku app.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `app_id` | string | yes | The app ID or name (e.g., `"my-app"` or the UUID) |

### Example

```lua
local result = app.integrations.heroku.get_app({ app_id = "my-app" })
print(result.name .. " - " .. result.stack .. " - " .. result.git_url)
```

---

## list_dynos

List all dynos for a given Heroku app.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `app_id` | string | yes | The app ID or name |

### Example

```lua
local result = app.integrations.heroku.list_dynos({ app_id = "my-app" })

for _, dyno in ipairs(result) do
  print(dyno.name .. " (" .. dyno.type .. ") - " .. dyno.state .. " - size: " .. dyno.size)
end
```

---

## list_addons

List all add-ons attached to a given Heroku app.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `app_id` | string | yes | The app ID or name |

### Example

```lua
local result = app.integrations.heroku.list_addons({ app_id = "my-app" })

for _, addon in ipairs(result) do
  print(addon.name .. " (" .. addon.plan.name .. ") - " .. addon.state)
end
```

---

## list_domains

List all domains for a given Heroku app.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `app_id` | string | yes | The app ID or name |

### Example

```lua
local result = app.integrations.heroku.list_domains({ app_id = "my-app" })

for _, domain in ipairs(result) do
  print(domain.hostname .. " (" .. domain.kind .. ") - " .. domain.status)
end
```

---

## list_collaborators

List all collaborators for a given Heroku app.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `app_id` | string | yes | The app ID or name |

### Example

```lua
local result = app.integrations.heroku.list_collaborators({ app_id = "my-app" })

for _, collab in ipairs(result) do
  print(collab.user.email .. " - role: " .. collab.role)
end
```

---

## get_current_user

Get the current authenticated account information.

### Parameters

None.

### Example

```lua
local result = app.integrations.heroku.get_current_user({})
print("Account: " .. result.email .. " - verified: " .. tostring(result.verified))
```

---

## Multi-Account Usage

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

```lua
-- Default account (always works)
app.integrations.heroku.list_apps({})

-- Explicit default (portable across setups)
app.integrations.heroku.default.list_apps({})

-- Named accounts
app.integrations.heroku.production.list_apps({})
app.integrations.heroku.staging.list_apps({})
```

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

Functions

list_apps Read

List all Heroku apps the authenticated user has access to. Returns app names, IDs, regions, and status.

Lua path
app.integrations.heroku.list_apps
Full name
heroku.heroku_list_apps
ParameterTypeRequiredDescription
No parameters.
get_app Read

Get details for a specific Heroku app by ID or name. Returns full app information including region, stack, and Git URL.

Lua path
app.integrations.heroku.get_app
Full name
heroku.heroku_get_app
ParameterTypeRequiredDescription
app_id string yes The app ID or name (e.g., "my-app" or the UUID).
list_dynos Read

List all dynos for a given Heroku app. Returns dyno names, types, sizes, states, and uptime.

Lua path
app.integrations.heroku.list_dynos
Full name
heroku.heroku_list_dynos
ParameterTypeRequiredDescription
app_id string yes The app ID or name.
list_add_ons Read

List all add-ons attached to a given Heroku app. Returns add-on names, plans, states, and provider details.

Lua path
app.integrations.heroku.list_add_ons
Full name
heroku.heroku_list_addons
ParameterTypeRequiredDescription
app_id string yes The app ID or name.
list_domains Read

List all domains for a given Heroku app. Returns domain hostnames, types (custom/Heroku), and status.

Lua path
app.integrations.heroku.list_domains
Full name
heroku.heroku_list_domains
ParameterTypeRequiredDescription
app_id string yes The app ID or name.
list_collaborators Read

List all collaborators for a given Heroku app. Returns collaborator emails, roles, and permissions.

Lua path
app.integrations.heroku.list_collaborators
Full name
heroku.heroku_list_collaborators
ParameterTypeRequiredDescription
app_id string yes The app ID or name.
get_current_user Read

Get information about the current authenticated Heroku account, including email, name, and verified status.

Lua path
app.integrations.heroku.get_current_user
Full name
heroku.heroku_get_current_user
ParameterTypeRequiredDescription
No parameters.