Can I use Celestial as a CLI?

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

Can I expose Celestial through MCP?

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

Where are Celestial credentials stored?

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

Can I deny write access for Celestial MCP tools?

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

data

Celestial Lua API for KosmoKrator Agents

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

Lua Namespace

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

Inline Lua call

kosmo integrations:lua --eval 'dump(app.integrations.celestial.moon_phase({date = "example_date", timezone = "example_timezone"}))' --json

Read Lua docs headlessly

kosmo integrations:lua --eval 'print(docs.read("celestial"))' --json
kosmo integrations:lua --eval 'print(docs.read("celestial.moon_phase"))' --json

Workflow file

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

workflow.lua

local celestial = app.integrations.celestial
local result = celestial.moon_phase({date = "example_date", timezone = "example_timezone"})

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

MCP-only Lua

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

Moon phase report — Lua API Reference

celestial_lunar_eclipse

Get lunar eclipse data for a specific date — eclipse type, magnitude, gamma, contact times (P1-P4, U1-U4), and semi-durations..

Parameters

Name	Type	Required	Description
`date`	string	yes	ISO date (e.g.

Example

local result = app.integrations.celestial.celestial_lunar_eclipse({
  date = ""
})

celestial_moon_info

Get moon position, illumination, and visibility from a specific location..

Parameters

Name	Type	Required	Description
`latitude`	number	yes	Observer latitude (-90 to 90).
`longitude`	number	yes	Observer longitude (-180 to 180).
`date`	string	no	ISO date or datetime (e.g.
`timezone`	string	no	Timezone for display (e.g.

Example

local result = app.integrations.celestial.celestial_moon_info({
  latitude = 0
  longitude = 0
  date = ""
})

celestial_moon_phase

Get current moon phase, illumination percentage, age, zodiac sign, and dates of next new/full moon..

Parameters

Name	Type	Required	Description
`date`	string	no	ISO date or datetime (e.g.
`timezone`	string	no	Timezone for display (e.g.

Example

local result = app.integrations.celestial.celestial_moon_phase({
  date = ""
  timezone = ""
})

celestial_night_sky

Get what.

Parameters

Name	Type	Required	Description
`latitude`	number	yes	Observer latitude (-90 to 90).
`longitude`	number	yes	Observer longitude (-180 to 180).
`timezone`	string	no	Timezone for display (e.g.

Example

local result = app.integrations.celestial.celestial_night_sky({
  latitude = 0
  longitude = 0
  timezone = ""
})

celestial_planet_position

Get planet altitude/azimuth, zodiac position, and rise/set times. Set planet to.

Parameters

Name	Type	Required	Description
`latitude`	number	yes	Observer latitude (-90 to 90).
`longitude`	number	yes	Observer longitude (-180 to 180).
`planet`	string	no	Planet name:
`date`	string	no	ISO date or datetime (e.g.
`timezone`	string	no	Timezone for display (e.g.

Example

local result = app.integrations.celestial.celestial_planet_position({
  latitude = 0
  longitude = 0
  planet = ""
})

celestial_solar_eclipse

Get solar eclipse data for a specific date and location — eclipse type, obscuration, contacts, and magnitude..

Parameters

Name	Type	Required	Description
`date`	string	yes	ISO date (e.g.
`latitude`	number	yes	Observer latitude (-90 to 90).
`longitude`	number	yes	Observer longitude (-180 to 180).

Example

local result = app.integrations.celestial.celestial_solar_eclipse({
  date = ""
  latitude = 0
  longitude = 0
})

celestial_sun_info

Get sunrise/sunset times, solar altitude/azimuth, twilight phase, day length, and zodiac position for a location..

Parameters

Name	Type	Required	Description
`latitude`	number	yes	Observer latitude (-90 to 90).
`longitude`	number	yes	Observer longitude (-180 to 180).
`date`	string	no	ISO date or datetime (e.g.
`timezone`	string	no	Timezone for display (e.g.

Example

local result = app.integrations.celestial.celestial_sun_info({
  latitude = 0
  longitude = 0
  date = ""
})

celestial_time_info

Get astronomical time data — Julian Day, sidereal time (GMST/GAST), and equation of time..

Parameters

Name	Type	Required	Description
`date`	string	no	ISO date or datetime (e.g.

Example

local result = app.integrations.celestial.celestial_time_info({
  date = ""
})

celestial_zodiac_report

Get all celestial bodies mapped to zodiac signs with alignments for a given date..

Parameters

Name	Type	Required	Description
`date`	string	no	ISO date or datetime (e.g.

Example

local result = app.integrations.celestial.celestial_zodiac_report({
  date = ""
})

Raw agent markdown

# Moon phase report — Lua API Reference

## celestial_lunar_eclipse

Get lunar eclipse data for a specific date — eclipse type, magnitude, gamma, contact times (P1-P4, U1-U4), and semi-durations..

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `date` | string | yes | ISO date (e.g.  |

### Example

```lua
local result = app.integrations.celestial.celestial_lunar_eclipse({
  date = ""
})
```

## celestial_moon_info

Get moon position, illumination, and visibility from a specific location..

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `latitude` | number | yes | Observer latitude (-90 to 90). |
| `longitude` | number | yes | Observer longitude (-180 to 180). |
| `date` | string | no | ISO date or datetime (e.g.  |
| `timezone` | string | no | Timezone for display (e.g.  |

### Example

```lua
local result = app.integrations.celestial.celestial_moon_info({
  latitude = 0
  longitude = 0
  date = ""
})
```

## celestial_moon_phase

Get current moon phase, illumination percentage, age, zodiac sign, and dates of next new/full moon..

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `date` | string | no | ISO date or datetime (e.g.  |
| `timezone` | string | no | Timezone for display (e.g.  |

### Example

```lua
local result = app.integrations.celestial.celestial_moon_phase({
  date = ""
  timezone = ""
})
```

## celestial_night_sky

Get what\.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `latitude` | number | yes | Observer latitude (-90 to 90). |
| `longitude` | number | yes | Observer longitude (-180 to 180). |
| `timezone` | string | no | Timezone for display (e.g.  |

### Example

```lua
local result = app.integrations.celestial.celestial_night_sky({
  latitude = 0
  longitude = 0
  timezone = ""
})
```

## celestial_planet_position

Get planet altitude/azimuth, zodiac position, and rise/set times. Set planet to.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `latitude` | number | yes | Observer latitude (-90 to 90). |
| `longitude` | number | yes | Observer longitude (-180 to 180). |
| `planet` | string | no | Planet name:  |
| `date` | string | no | ISO date or datetime (e.g.  |
| `timezone` | string | no | Timezone for display (e.g.  |

### Example

```lua
local result = app.integrations.celestial.celestial_planet_position({
  latitude = 0
  longitude = 0
  planet = ""
})
```

## celestial_solar_eclipse

Get solar eclipse data for a specific date and location — eclipse type, obscuration, contacts, and magnitude..

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `date` | string | yes | ISO date (e.g.  |
| `latitude` | number | yes | Observer latitude (-90 to 90). |
| `longitude` | number | yes | Observer longitude (-180 to 180). |

### Example

```lua
local result = app.integrations.celestial.celestial_solar_eclipse({
  date = ""
  latitude = 0
  longitude = 0
})
```

## celestial_sun_info

Get sunrise/sunset times, solar altitude/azimuth, twilight phase, day length, and zodiac position for a location..

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `latitude` | number | yes | Observer latitude (-90 to 90). |
| `longitude` | number | yes | Observer longitude (-180 to 180). |
| `date` | string | no | ISO date or datetime (e.g.  |
| `timezone` | string | no | Timezone for display (e.g.  |

### Example

```lua
local result = app.integrations.celestial.celestial_sun_info({
  latitude = 0
  longitude = 0
  date = ""
})
```

## celestial_time_info

Get astronomical time data — Julian Day, sidereal time (GMST/GAST), and equation of time..

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `date` | string | no | ISO date or datetime (e.g.  |

### Example

```lua
local result = app.integrations.celestial.celestial_time_info({
  date = ""
})
```

## celestial_zodiac_report

Get all celestial bodies mapped to zodiac signs with alignments for a given date..

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `date` | string | no | ISO date or datetime (e.g.  |

### Example

```lua
local result = app.integrations.celestial.celestial_zodiac_report({
  date = ""
})
```

Metadata-derived Lua example

local result = app.integrations.celestial.moon_phase({date = "example_date", timezone = "example_timezone"})
print(result)

Functions

moon_phase Read

Get current moon phase, illumination percentage, age, zodiac sign, and dates of next new/full moon.

Lua path: app.integrations.celestial.moon_phase
Full name: celestial.celestial_moon_phase

Parameter	Type	Required	Description
`date`	string	no	ISO date or datetime (e.g. '2024-06-15' or '2024-06-15 22:00:00'). Defaults to now.
`timezone`	string	no	Timezone for display (e.g. 'Europe/Amsterdam'). Defaults to org timezone.

sun_info Read

Get sunrise/sunset times, solar altitude/azimuth, twilight phase, day length, and zodiac position for a location.

Lua path: app.integrations.celestial.sun_info
Full name: celestial.celestial_sun_info

Parameter	Type	Required	Description
`latitude`	number	yes	Observer latitude (-90 to 90).
`longitude`	number	yes	Observer longitude (-180 to 180).
`date`	string	no	ISO date or datetime (e.g. '2024-06-15'). Defaults to now.
`timezone`	string	no	Timezone for display (e.g. 'Europe/Amsterdam'). Defaults to org timezone.

moon_info Read

Get moon position, illumination, and visibility from a specific location.

Lua path: app.integrations.celestial.moon_info
Full name: celestial.celestial_moon_info

Parameter	Type	Required	Description
`latitude`	number	yes	Observer latitude (-90 to 90).
`longitude`	number	yes	Observer longitude (-180 to 180).
`date`	string	no	ISO date or datetime (e.g. '2024-06-15'). Defaults to now.
`timezone`	string	no	Timezone for display (e.g. 'Europe/Amsterdam'). Defaults to org timezone.

planet_position Read

Get planet altitude/azimuth, zodiac position, and rise/set times. Set planet to "all" for an overview of all planets.

Lua path: app.integrations.celestial.planet_position
Full name: celestial.celestial_planet_position

Parameter	Type	Required	Description
`latitude`	number	yes	Observer latitude (-90 to 90).
`longitude`	number	yes	Observer longitude (-180 to 180).
`planet`	string	no	Planet name: 'mercury', 'venus', 'mars', 'jupiter', 'saturn', 'uranus', 'neptune', or 'all' (default).
`date`	string	no	ISO date or datetime (e.g. '2024-06-15'). Defaults to now.
`timezone`	string	no	Timezone for display (e.g. 'Europe/Amsterdam'). Defaults to org timezone.

solar_eclipse Read

Get solar eclipse data for a specific date and location — eclipse type, obscuration, contacts, and magnitude.

Lua path: app.integrations.celestial.solar_eclipse
Full name: celestial.celestial_solar_eclipse

Parameter	Type	Required	Description
`date`	string	yes	ISO date (e.g. '2024-04-08'). Defaults to today.
`latitude`	number	yes	Observer latitude (-90 to 90).
`longitude`	number	yes	Observer longitude (-180 to 180).

lunar_eclipse Read

Get lunar eclipse data for a specific date — eclipse type, magnitude, gamma, contact times (P1-P4, U1-U4), and semi-durations.

Lua path: app.integrations.celestial.lunar_eclipse
Full name: celestial.celestial_lunar_eclipse

Parameter	Type	Required	Description
`date`	string	yes	ISO date (e.g. '2024-09-18'). Defaults to today.

night_sky Read

Get what's visible in the night sky right now: sun/moon/planet positions, darkness level, and stargazing quality for a location.

Lua path: app.integrations.celestial.night_sky
Full name: celestial.celestial_night_sky

Parameter	Type	Required	Description
`latitude`	number	yes	Observer latitude (-90 to 90).
`longitude`	number	yes	Observer longitude (-180 to 180).
`timezone`	string	no	Timezone for display (e.g. 'Europe/Amsterdam'). Defaults to org timezone.

zodiac_report Read

Get all celestial bodies mapped to zodiac signs with alignments for a given date.

Lua path: app.integrations.celestial.zodiac_report
Full name: celestial.celestial_zodiac_report

Parameter	Type	Required	Description
`date`	string	no	ISO date or datetime (e.g. '2024-06-15'). Defaults to now.

astronomical_time Read

Get astronomical time data — Julian Day, sidereal time (GMST/GAST), and equation of time.

Lua path: app.integrations.celestial.astronomical_time
Full name: celestial.celestial_time_info

Parameter	Type	Required	Description
`date`	string	no	ISO date or datetime (e.g. '2024-06-15'). Defaults to now.