Can I use Bluesky as a CLI?

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

Can I expose Bluesky through MCP?

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

Where are Bluesky credentials stored?

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

Can I deny write access for Bluesky MCP tools?

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

data

Bluesky Lua API for KosmoKrator Agents

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

Lua Namespace

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

Inline Lua call

kosmo integrations:lua --eval 'dump(app.integrations.bluesky.create_post({text = "example_text", langs = "example_langs", facets = "example_facets", createdAt = "example_createdAt"}))' --json

Read Lua docs headlessly

kosmo integrations:lua --eval 'print(docs.read("bluesky"))' --json
kosmo integrations:lua --eval 'print(docs.read("bluesky.create_post"))' --json

Workflow file

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

workflow.lua

local bluesky = app.integrations.bluesky
local result = bluesky.create_post({text = "example_text", langs = "example_langs", facets = "example_facets", createdAt = "example_createdAt"})

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

MCP-only Lua

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

Bluesky Lua Reference

Namespace: bluesky

Bluesky tools return raw XRPC JSON. Most app view endpoints return objects such as feed, posts, profile, followers, follows, likes, or cursor.

Common Reads

local profile = app.integrations.bluesky.get_profile({
  actor = "alice.bsky.social",
})

local timeline = app.integrations.bluesky.get_timeline({
  limit = 25,
})

local author = app.integrations.bluesky.get_author_feed({
  actor = "alice.bsky.social",
  filter = "posts_no_replies",
})

local thread = app.integrations.bluesky.get_post_thread({
  uri = "at://did:plc:example/app.bsky.feed.post/3kexample",
  depth = 6,
})

local posts = app.integrations.bluesky.get_posts({
  uris = {
    "at://did:plc:example/app.bsky.feed.post/3kexample",
  },
})

Writes

local post = app.integrations.bluesky.create_post({
  text = "Hello from an agent",
  langs = { "en" },
})

local like = app.integrations.bluesky.like_post({
  uri = post.uri,
  cid = post.cid,
})

local repost = app.integrations.bluesky.repost_post({
  uri = post.uri,
  cid = post.cid,
})

local follow = app.integrations.bluesky.follow_actor({
  subject = "did:plc:example",
})

Generic record writes:

local record = app.integrations.bluesky.create_record({
  collection = "app.bsky.feed.post",
  record = {
    ["$type"] = "app.bsky.feed.post",
    text = "Custom record body",
    createdAt = "2026-05-06T12:00:00Z",
  },
})

app.integrations.bluesky.delete_record({
  collection = "app.bsky.feed.post",
  rkey = "3kexample",
})

Generic XRPC

Use generic XRPC tools for AT Protocol methods not exposed as dedicated tools.

local response = app.integrations.bluesky.xrpc_get({
  method = "app.bsky.actor.searchActors",
  params = {
    q = "opencompany",
    limit = 10,
  },
})

local created = app.integrations.bluesky.xrpc_post({
  method = "com.atproto.repo.createRecord",
  body = {
    repo = "did:plc:example",
    collection = "app.bsky.feed.post",
    record = {
      ["$type"] = "app.bsky.feed.post",
      text = "Via generic XRPC",
      createdAt = "2026-05-06T12:00:00Z",
    },
  },
})

Multi-Account Usage

app.integrations.bluesky.default.get_timeline({ limit = 10 })
app.integrations.bluesky.work.create_post({ text = "Work update" })

Raw agent markdown

# Bluesky Lua Reference

Namespace: `bluesky`

Bluesky tools return raw XRPC JSON. Most app view endpoints return objects such
as `feed`, `posts`, `profile`, `followers`, `follows`, `likes`, or `cursor`.

## Common Reads

```lua
local profile = app.integrations.bluesky.get_profile({
  actor = "alice.bsky.social",
})

local timeline = app.integrations.bluesky.get_timeline({
  limit = 25,
})

local author = app.integrations.bluesky.get_author_feed({
  actor = "alice.bsky.social",
  filter = "posts_no_replies",
})

local thread = app.integrations.bluesky.get_post_thread({
  uri = "at://did:plc:example/app.bsky.feed.post/3kexample",
  depth = 6,
})

local posts = app.integrations.bluesky.get_posts({
  uris = {
    "at://did:plc:example/app.bsky.feed.post/3kexample",
  },
})
```

Other read tools:

- `get_feed({ feed, limit?, cursor? })`
- `get_feed_generator({ feed })`
- `get_likes({ uri, cid?, limit?, cursor? })`
- `get_reposted_by({ uri, cid?, limit?, cursor? })`
- `list_followers({ actor, limit?, cursor? })`
- `list_following({ actor, limit?, cursor? })`
- `search_posts({ q, limit?, cursor? })`
- `list_notifications({ limit?, cursor?, seen_at? })`
- `get_current_user({})`

## Writes

```lua
local post = app.integrations.bluesky.create_post({
  text = "Hello from an agent",
  langs = { "en" },
})

local like = app.integrations.bluesky.like_post({
  uri = post.uri,
  cid = post.cid,
})

local repost = app.integrations.bluesky.repost_post({
  uri = post.uri,
  cid = post.cid,
})

local follow = app.integrations.bluesky.follow_actor({
  subject = "did:plc:example",
})
```

Generic record writes:

```lua
local record = app.integrations.bluesky.create_record({
  collection = "app.bsky.feed.post",
  record = {
    ["$type"] = "app.bsky.feed.post",
    text = "Custom record body",
    createdAt = "2026-05-06T12:00:00Z",
  },
})

app.integrations.bluesky.delete_record({
  collection = "app.bsky.feed.post",
  rkey = "3kexample",
})
```

## Generic XRPC

Use generic XRPC tools for AT Protocol methods not exposed as dedicated tools.

```lua
local response = app.integrations.bluesky.xrpc_get({
  method = "app.bsky.actor.searchActors",
  params = {
    q = "opencompany",
    limit = 10,
  },
})

local created = app.integrations.bluesky.xrpc_post({
  method = "com.atproto.repo.createRecord",
  body = {
    repo = "did:plc:example",
    collection = "app.bsky.feed.post",
    record = {
      ["$type"] = "app.bsky.feed.post",
      text = "Via generic XRPC",
      createdAt = "2026-05-06T12:00:00Z",
    },
  },
})
```

## Multi-Account Usage

```lua
app.integrations.bluesky.default.get_timeline({ limit = 10 })
app.integrations.bluesky.work.create_post({ text = "Work update" })
```

Metadata-derived Lua example

local result = app.integrations.bluesky.create_post({text = "example_text", langs = "example_langs", facets = "example_facets", createdAt = "example_createdAt"})
print(result)

Functions

create_post Write

Create a new post on Bluesky. The post text is required and supports facets (mentions, links, tags) if provided.

Lua path: app.integrations.bluesky.create_post
Full name: bluesky.bluesky_create_post

Parameter	Type	Required	Description
`text`	string	yes	The text content of the post (max 300 graphemes).
`langs`	array	no	BCP-47 language tags (e.g. ["en", "nl"]). Defaults to ["en"].
`facets`	array	no	Optional facets for rich text (mentions, links, tags). Each facet needs index.byteStart, index.byteEnd, and features array.
`createdAt`	string	no	ISO 8601 timestamp. Defaults to now if omitted.

get_profile Read

Get the public profile of a Bluesky user. Provide a handle (e.g. "alice.bsky.social") or DID.

Lua path: app.integrations.bluesky.get_profile
Full name: bluesky.bluesky_get_profile

Parameter	Type	Required	Description
`actor`	string	yes	Handle (e.g. "alice.bsky.social") or DID (e.g. "did:plc:...").

get_timeline Read

Get the authenticated account timeline.

Lua path: app.integrations.bluesky.get_timeline
Full name: bluesky.bluesky_get_timeline

Parameter	Type	Required	Description
No parameters.

get_author_feed Read

Get posts and reposts by an actor.

Lua path: app.integrations.bluesky.get_author_feed
Full name: bluesky.bluesky_get_author_feed

Parameter	Type	Required	Description
No parameters.

get_feed Read

Get posts from a feed generator.

Lua path: app.integrations.bluesky.get_feed
Full name: bluesky.bluesky_get_feed

Parameter	Type	Required	Description
No parameters.

get_feed_generator Read

Get feed generator metadata.

Lua path: app.integrations.bluesky.get_feed_generator
Full name: bluesky.bluesky_get_feed_generator

Parameter	Type	Required	Description
No parameters.

get_post_thread Read

Get a post thread by URI.

Lua path: app.integrations.bluesky.get_post_thread
Full name: bluesky.bluesky_get_post_thread

Parameter	Type	Required	Description
No parameters.

get_posts Read

Get one or more posts by URI.

Lua path: app.integrations.bluesky.get_posts
Full name: bluesky.bluesky_get_posts

Parameter	Type	Required	Description
No parameters.

get_likes Read

Get actors who liked a post.

Lua path: app.integrations.bluesky.get_likes
Full name: bluesky.bluesky_get_likes

Parameter	Type	Required	Description
No parameters.

get_reposted_by Read

Get actors who reposted a post.

Lua path: app.integrations.bluesky.get_reposted_by
Full name: bluesky.bluesky_get_reposted_by

Parameter	Type	Required	Description
No parameters.

list_followers Read

List the followers of a Bluesky account. Returns follower profiles with handles, display names, and avatars.

Lua path: app.integrations.bluesky.list_followers
Full name: bluesky.bluesky_list_followers

Parameter	Type	Required	Description
`actor`	string	yes	Handle or DID of the user whose followers to list.
`limit`	integer	no	Number of results per page (1–100, default 50).
`cursor`	string	no	Pagination cursor from a previous response to fetch the next page.

list_following Read

List the accounts that a Bluesky user follows. Returns profiles with handles, display names, and avatars.

Lua path: app.integrations.bluesky.list_following
Full name: bluesky.bluesky_list_following

Parameter	Type	Required	Description
`actor`	string	yes	Handle or DID of the user whose follows to list.
`limit`	integer	no	Number of results per page (1–100, default 50).
`cursor`	string	no	Pagination cursor from a previous response to fetch the next page.

search_posts Read

Search for posts on Bluesky. Supports full-text search queries. Returns matching posts with author, text, and timestamps.

Lua path: app.integrations.bluesky.search_posts
Full name: bluesky.bluesky_search_posts

Parameter	Type	Required	Description
`q`	string	yes	Search query. Supports search operators like "from:user", "has:images", "lang:en", and boolean combinations.
`limit`	integer	no	Number of results per page (1–100, default 25).
`cursor`	string	no	Pagination cursor from a previous response to fetch the next page.

list_notifications Read

List notifications for the authenticated account.

Lua path: app.integrations.bluesky.list_notifications
Full name: bluesky.bluesky_list_notifications

Parameter	Type	Required	Description
No parameters.

get_current_user Read

Get the authenticated user's own Bluesky profile. No parameters required — uses the configured account.

Lua path: app.integrations.bluesky.get_current_user
Full name: bluesky.bluesky_get_current_user

Parameter	Type	Required	Description
No parameters.

create_record Write

Create an arbitrary AT Protocol record.

Lua path: app.integrations.bluesky.create_record
Full name: bluesky.bluesky_create_record

Parameter	Type	Required	Description
No parameters.

delete_record Write

Delete an AT Protocol record.

Lua path: app.integrations.bluesky.delete_record
Full name: bluesky.bluesky_delete_record

Parameter	Type	Required	Description
No parameters.

like_post Write

Like a Bluesky post.

Lua path: app.integrations.bluesky.like_post
Full name: bluesky.bluesky_like_post

Parameter	Type	Required	Description
No parameters.

repost_post Write

Repost a Bluesky post.

Lua path: app.integrations.bluesky.repost_post
Full name: bluesky.bluesky_repost_post

Parameter	Type	Required	Description
No parameters.

follow_actor Write

Follow an actor DID.

Lua path: app.integrations.bluesky.follow_actor
Full name: bluesky.bluesky_follow_actor

Parameter	Type	Required	Description
No parameters.

xrpc_get Read

Call any GET XRPC method.

Lua path: app.integrations.bluesky.xrpc_get
Full name: bluesky.bluesky_xrpc_get

Parameter	Type	Required	Description
No parameters.

xrpc_post Write

Call any POST XRPC method.

Lua path: app.integrations.bluesky.xrpc_post
Full name: bluesky.bluesky_xrpc_post

Parameter	Type	Required	Description
No parameters.