KosmoKrator

productivity

wallabag Lua API for KosmoKrator Agents

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

Lua Namespace

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

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

Workflow file

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

workflow.lua 
local wallabag = app.integrations.wallabag
local result = wallabag.password_token({})

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

MCP-only Lua

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

wallabag

Namespace: wallabag

Use this integration to create and manage saved articles in a hosted or self-hosted wallabag instance. The API uses OAuth2 bearer tokens. Configure an instance URL such as https://app.wallabag.it or your own wallabag root URL.

OAuth Tokens

Exchange client/user credentials for a token:

wallabag_token_password({
  client_id = "client-id",
  client_secret = "client-secret",
  username = "[email protected]",
  password = "fake-password"
})

Refresh a token:

wallabag_token_refresh({
  client_id = "client-id",
  client_secret = "client-secret",
  refresh_token = "refresh-token"
})

Entries

wallabag_entries_create({
  url = "https://example.test/article",
  payload = {
    title = "Example Article",
    tags = "research,examples"
  }
})

wallabag_entries_list({
  payload = {
    page = 1,
    perPage = 30,
    archive = 0,
    starred = 0
  }
})

Other entry tools include wallabag_entries_exists, wallabag_entries_get, wallabag_entries_update, wallabag_entries_delete, wallabag_entries_reload, and wallabag_entries_export. For export, pass format as epub, mobi, pdf, txt, csv, json, or xml.

Tags And Annotations

wallabag_tags_list({})

wallabag_entry_tags_add({
  entry = "123",
  tags = "research,priority"
})

wallabag_annotations_list({ entry = "123" })

wallabag_annotations_create({
  entry = "123",
  text = "Important passage",
  ranges = {
    { start = "/p[1]", startOffset = 0, ["end"] = "/p[1]", endOffset = 18 }
  }
})

wallabag_entry_tag_delete, wallabag_annotations_update, and wallabag_annotations_delete handle cleanup and edits.

Raw API Calls

wallabag_api_get, wallabag_api_post, wallabag_api_patch, and wallabag_api_delete call safe relative paths with the configured bearer token. Absolute URLs are rejected.

wallabag_api_get({
  path = "/api/entries.json",
  payload = { perPage = 10 }
})
Raw agent markdown 
# wallabag

Namespace: `wallabag`

Use this integration to create and manage saved articles in a hosted or self-hosted wallabag instance. The API uses OAuth2 bearer tokens. Configure an instance URL such as `https://app.wallabag.it` or your own wallabag root URL.

## OAuth Tokens

Exchange client/user credentials for a token:

```lua
wallabag_token_password({
  client_id = "client-id",
  client_secret = "client-secret",
  username = "[email protected]",
  password = "fake-password"
})
```

Refresh a token:

```lua
wallabag_token_refresh({
  client_id = "client-id",
  client_secret = "client-secret",
  refresh_token = "refresh-token"
})
```

## Entries

```lua
wallabag_entries_create({
  url = "https://example.test/article",
  payload = {
    title = "Example Article",
    tags = "research,examples"
  }
})

wallabag_entries_list({
  payload = {
    page = 1,
    perPage = 30,
    archive = 0,
    starred = 0
  }
})
```

Other entry tools include `wallabag_entries_exists`, `wallabag_entries_get`, `wallabag_entries_update`, `wallabag_entries_delete`, `wallabag_entries_reload`, and `wallabag_entries_export`. For export, pass `format` as `epub`, `mobi`, `pdf`, `txt`, `csv`, `json`, or `xml`.

## Tags And Annotations

```lua
wallabag_tags_list({})

wallabag_entry_tags_add({
  entry = "123",
  tags = "research,priority"
})

wallabag_annotations_list({ entry = "123" })

wallabag_annotations_create({
  entry = "123",
  text = "Important passage",
  ranges = {
    { start = "/p[1]", startOffset = 0, ["end"] = "/p[1]", endOffset = 18 }
  }
})
```

`wallabag_entry_tag_delete`, `wallabag_annotations_update`, and `wallabag_annotations_delete` handle cleanup and edits.

## Raw API Calls

`wallabag_api_get`, `wallabag_api_post`, `wallabag_api_patch`, and `wallabag_api_delete` call safe relative paths with the configured bearer token. Absolute URLs are rejected.

```lua
wallabag_api_get({
  path = "/api/entries.json",
  payload = { perPage = 10 }
})
```
Metadata-derived Lua example 
local result = app.integrations.wallabag.password_token({})
print(result)

Functions

password_token Write

Exchange wallabag client and user credentials for an access token.

Lua path
app.integrations.wallabag.password_token
Full name
wallabag.wallabag_token_password
ParameterTypeRequiredDescription
No parameters.
refresh_token Write

Refresh a wallabag access token.

Lua path
app.integrations.wallabag.refresh_token
Full name
wallabag.wallabag_token_refresh
ParameterTypeRequiredDescription
No parameters.
list_entries Read

List wallabag entries with filters and pagination.

Lua path
app.integrations.wallabag.list_entries
Full name
wallabag.wallabag_entries_list
ParameterTypeRequiredDescription
No parameters.
create_entry Write

Create a wallabag entry from a URL.

Lua path
app.integrations.wallabag.create_entry
Full name
wallabag.wallabag_entries_create
ParameterTypeRequiredDescription
No parameters.
entry_exists Read

Check whether a URL already exists in wallabag.

Lua path
app.integrations.wallabag.entry_exists
Full name
wallabag.wallabag_entries_exists
ParameterTypeRequiredDescription
No parameters.
get_entry Read

Get one wallabag entry.

Lua path
app.integrations.wallabag.get_entry
Full name
wallabag.wallabag_entries_get
ParameterTypeRequiredDescription
No parameters.
update_entry Write

Update title, archived/starred state, tags, or other entry fields.

Lua path
app.integrations.wallabag.update_entry
Full name
wallabag.wallabag_entries_update
ParameterTypeRequiredDescription
No parameters.
delete_entry Write

Delete one wallabag entry.

Lua path
app.integrations.wallabag.delete_entry
Full name
wallabag.wallabag_entries_delete
ParameterTypeRequiredDescription
No parameters.
reload_entry Write

Refetch and reload a wallabag entry.

Lua path
app.integrations.wallabag.reload_entry
Full name
wallabag.wallabag_entries_reload
ParameterTypeRequiredDescription
No parameters.
export_entry Read

Export an entry as epub, mobi, pdf, txt, csv, json, or xml.

Lua path
app.integrations.wallabag.export_entry
Full name
wallabag.wallabag_entries_export
ParameterTypeRequiredDescription
No parameters.
list_tags Read

List wallabag tags.

Lua path
app.integrations.wallabag.list_tags
Full name
wallabag.wallabag_tags_list
ParameterTypeRequiredDescription
No parameters.
add_entry_tags Write

Add comma-separated tags to an entry.

Lua path
app.integrations.wallabag.add_entry_tags
Full name
wallabag.wallabag_entry_tags_add
ParameterTypeRequiredDescription
No parameters.
delete_entry_tag Write

Remove one tag from an entry.

Lua path
app.integrations.wallabag.delete_entry_tag
Full name
wallabag.wallabag_entry_tag_delete
ParameterTypeRequiredDescription
No parameters.
list_annotations Read

List annotations for a wallabag entry.

Lua path
app.integrations.wallabag.list_annotations
Full name
wallabag.wallabag_annotations_list
ParameterTypeRequiredDescription
No parameters.
create_annotation Write

Create an annotation for a wallabag entry.

Lua path
app.integrations.wallabag.create_annotation
Full name
wallabag.wallabag_annotations_create
ParameterTypeRequiredDescription
No parameters.
update_annotation Write

Update a wallabag annotation.

Lua path
app.integrations.wallabag.update_annotation
Full name
wallabag.wallabag_annotations_update
ParameterTypeRequiredDescription
No parameters.
delete_annotation Write

Delete a wallabag annotation.

Lua path
app.integrations.wallabag.delete_annotation
Full name
wallabag.wallabag_annotations_delete
ParameterTypeRequiredDescription
No parameters.
api_get Read

Call a safe relative wallabag API GET path.

Lua path
app.integrations.wallabag.api_get
Full name
wallabag.wallabag_api_get
ParameterTypeRequiredDescription
No parameters.
api_post Write

Call a safe relative wallabag API POST path.

Lua path
app.integrations.wallabag.api_post
Full name
wallabag.wallabag_api_post
ParameterTypeRequiredDescription
No parameters.
api_patch Write

Call a safe relative wallabag API PATCH path.

Lua path
app.integrations.wallabag.api_patch
Full name
wallabag.wallabag_api_patch
ParameterTypeRequiredDescription
No parameters.
api_delete Write

Call a safe relative wallabag API DELETE path.

Lua path
app.integrations.wallabag.api_delete
Full name
wallabag.wallabag_api_delete
ParameterTypeRequiredDescription
No parameters.