Can I use PlanetScale as a CLI?

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

Can I expose PlanetScale through MCP?

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

Where are PlanetScale credentials stored?

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

Can I deny write access for PlanetScale MCP tools?

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

data

PlanetScale Lua API for KosmoKrator Agents

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

Lua Namespace

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

Inline Lua call

kosmo integrations:lua --eval 'dump(app.integrations.planetscale.list_databases({organization = "example_organization", page = 1, limit = 1}))' --json

Read Lua docs headlessly

kosmo integrations:lua --eval 'print(docs.read("planetscale"))' --json
kosmo integrations:lua --eval 'print(docs.read("planetscale.list_databases"))' --json

Workflow file

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

workflow.lua

local planetscale = app.integrations.planetscale
local result = planetscale.list_databases({organization = "example_organization", page = 1, limit = 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.planetscale, app.mcp.*, docs.*, json.*, and regex.*. Use app.integrations.planetscale.default.* or app.integrations.planetscale.work.* when you configured named credential accounts.

MCP-only Lua

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

PlanetScale — Lua API Reference

list_databases

List databases in a PlanetScale organization.

Parameters

Name	Type	Required	Description
`organization`	string	yes	The organization name
`page`	integer	no	Page number (1-based, default: 1)
`limit`	integer	no	Results per page (default: 20, max: 100)

Example

local result = app.integrations.planetscale.list_databases({
  organization = "my-org",
  page = 1,
  limit = 10
})

for _, db in ipairs(result.data) do
  print(db.name .. ": " .. db.state)
end

get_database

Get details of a specific PlanetScale database.

Parameters

Name	Type	Required	Description
`organization`	string	yes	The organization name
`database`	string	yes	The database name

Example

local result = app.integrations.planetscale.get_database({
  organization = "my-org",
  database = "my-database"
})

print("State: " .. result.state)
print("Region: " .. result.region.slug)
print("Branches: " .. result.branches)

create_database

Create a new database in a PlanetScale organization.

Parameters

Name	Type	Required	Description
`organization`	string	yes	The organization name
`name`	string	yes	The database name (lowercase, hyphens allowed)
`region`	string	no	The region slug (e.g., “us-east-1”)
`notes`	string	no	Optional notes about the database

Example

local result = app.integrations.planetscale.create_database({
  organization = "my-org",
  name = "my-new-database",
  region = "us-east-1",
  notes = "Production database for project X"
})

print("Created: " .. result.name)
print("State: " .. result.state)

list_branches

List branches of a PlanetScale database.

Parameters

Name	Type	Required	Description
`organization`	string	yes	The organization name
`database`	string	yes	The database name
`page`	integer	no	Page number (1-based, default: 1)
`limit`	integer	no	Results per page (default: 20, max: 100)

Example

local result = app.integrations.planetscale.list_branches({
  organization = "my-org",
  database = "my-database"
})

for _, branch in ipairs(result.data) do
  print(branch.name .. " (" .. branch.role .. ")")
end

get_branch

Get details of a specific branch of a PlanetScale database.

Parameters

Name	Type	Required	Description
`organization`	string	yes	The organization name
`database`	string	yes	The database name
`branch`	string	yes	The branch name

Example

local result = app.integrations.planetscale.get_branch({
  organization = "my-org",
  database = "my-database",
  branch = "main"
})

print("Role: " .. result.role)
print("Ready: " .. tostring(result.ready))
print("Region: " .. result.region.slug)

list_organizations

List organizations the authenticated user belongs to.

Parameters

None.

Example

local result = app.integrations.planetscale.list_organizations({})

for _, org in ipairs(result.data) do
  print(org.name .. " (" .. org.slug .. ")")
end

get_current_user

Get the profile of the currently authenticated user.

Parameters

None.

Example

local result = app.integrations.planetscale.get_current_user({})
print("User: " .. (result.first_name or "") .. " " .. (result.last_name or ""))
print("Email: " .. result.email)

Multi-Account Usage

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

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

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

-- Named accounts
app.integrations.planetscale.production.function_name({...})
app.integrations.planetscale.staging.function_name({...})

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

Raw agent markdown

# PlanetScale — Lua API Reference

## list_databases

List databases in a PlanetScale organization.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `organization` | string | yes | The organization name |
| `page` | integer | no | Page number (1-based, default: 1) |
| `limit` | integer | no | Results per page (default: 20, max: 100) |

### Example

```lua
local result = app.integrations.planetscale.list_databases({
  organization = "my-org",
  page = 1,
  limit = 10
})

for _, db in ipairs(result.data) do
  print(db.name .. ": " .. db.state)
end
```

---

## get_database

Get details of a specific PlanetScale database.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `organization` | string | yes | The organization name |
| `database` | string | yes | The database name |

### Example

```lua
local result = app.integrations.planetscale.get_database({
  organization = "my-org",
  database = "my-database"
})

print("State: " .. result.state)
print("Region: " .. result.region.slug)
print("Branches: " .. result.branches)
```

---

## create_database

Create a new database in a PlanetScale organization.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `organization` | string | yes | The organization name |
| `name` | string | yes | The database name (lowercase, hyphens allowed) |
| `region` | string | no | The region slug (e.g., "us-east-1") |
| `notes` | string | no | Optional notes about the database |

### Example

```lua
local result = app.integrations.planetscale.create_database({
  organization = "my-org",
  name = "my-new-database",
  region = "us-east-1",
  notes = "Production database for project X"
})

print("Created: " .. result.name)
print("State: " .. result.state)
```

---

## list_branches

List branches of a PlanetScale database.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `organization` | string | yes | The organization name |
| `database` | string | yes | The database name |
| `page` | integer | no | Page number (1-based, default: 1) |
| `limit` | integer | no | Results per page (default: 20, max: 100) |

### Example

```lua
local result = app.integrations.planetscale.list_branches({
  organization = "my-org",
  database = "my-database"
})

for _, branch in ipairs(result.data) do
  print(branch.name .. " (" .. branch.role .. ")")
end
```

---

## get_branch

Get details of a specific branch of a PlanetScale database.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `organization` | string | yes | The organization name |
| `database` | string | yes | The database name |
| `branch` | string | yes | The branch name |

### Example

```lua
local result = app.integrations.planetscale.get_branch({
  organization = "my-org",
  database = "my-database",
  branch = "main"
})

print("Role: " .. result.role)
print("Ready: " .. tostring(result.ready))
print("Region: " .. result.region.slug)
```

---

## list_organizations

List organizations the authenticated user belongs to.

### Parameters

None.

### Example

```lua
local result = app.integrations.planetscale.list_organizations({})

for _, org in ipairs(result.data) do
  print(org.name .. " (" .. org.slug .. ")")
end
```

---

## get_current_user

Get the profile of the currently authenticated user.

### Parameters

None.

### Example

```lua
local result = app.integrations.planetscale.get_current_user({})
print("User: " .. (result.first_name or "") .. " " .. (result.last_name or ""))
print("Email: " .. result.email)
```

---

## Multi-Account Usage

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

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

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

-- Named accounts
app.integrations.planetscale.production.function_name({...})
app.integrations.planetscale.staging.function_name({...})
```

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

Metadata-derived Lua example

local result = app.integrations.planetscale.list_databases({organization = "example_organization", page = 1, limit = 1})
print(result)

Functions

list_databases Read

List databases in a PlanetScale organization. Returns a paginated list of databases with their names, regions, and states.

Lua path: app.integrations.planetscale.list_databases
Full name: planetscale.planetscale_list_databases

Parameter	Type	Required	Description
`organization`	string	yes	The organization name.
`page`	integer	no	Page number (1-based, default: 1).
`limit`	integer	no	Results per page (default: 20, max: 100).

get_database Read

Get details of a specific PlanetScale database, including its state, region, and branch count.

Lua path: app.integrations.planetscale.get_database
Full name: planetscale.planetscale_get_database

Parameter	Type	Required	Description
`organization`	string	yes	The organization name.
`database`	string	yes	The database name.

create_database Write

Create a new database in a PlanetScale organization. Specify the database name and optionally a region and notes.

Lua path: app.integrations.planetscale.create_database
Full name: planetscale.planetscale_create_database

Parameter	Type	Required	Description
`organization`	string	yes	The organization name.
`name`	string	yes	The database name (lowercase, hyphens allowed).
`region`	string	no	The region slug (e.g., "us-east-1"). Defaults to the organization region.
`notes`	string	no	Optional notes about the database.

list_branches Read

List branches of a PlanetScale database. Returns a paginated list of branches with their names, roles, and states.

Lua path: app.integrations.planetscale.list_branches
Full name: planetscale.planetscale_list_branches

Parameter	Type	Required	Description
`organization`	string	yes	The organization name.
`database`	string	yes	The database name.
`page`	integer	no	Page number (1-based, default: 1).
`limit`	integer	no	Results per page (default: 20, max: 100).

get_branch Read

Get details of a specific branch of a PlanetScale database, including its role, region, and readiness.

Lua path: app.integrations.planetscale.get_branch
Full name: planetscale.planetscale_get_branch

Parameter	Type	Required	Description
`organization`	string	yes	The organization name.
`database`	string	yes	The database name.
`branch`	string	yes	The branch name.

list_organizations Read

List organizations the authenticated user belongs to. Useful for discovering organization names needed by other PlanetScale tools.

Lua path: app.integrations.planetscale.list_organizations
Full name: planetscale.planetscale_list_organizations

Parameter	Type	Required	Description
No parameters.

get_current_user Read

Get the profile of the currently authenticated PlanetScale user. Useful for verifying API credentials and retrieving account information.

Lua path: app.integrations.planetscale.get_current_user
Full name: planetscale.planetscale_get_current_user

Parameter	Type	Required	Description
No parameters.