KosmoKrator

productivity

Matrix CLI for AI Agents

Use the Matrix CLI from KosmoKrator to call Matrix tools headlessly, return JSON, inspect schemas, and automate workflows from coding agents, scripts, and CI.

Matrix CLI Setup

Matrix can be configured headlessly with `kosmokrator integrations:configure matrix`.

Install, configure, and verify 
# Install KosmoKrator first if it is not available on PATH.
curl -fsSL https://raw.githubusercontent.com/OpenCompanyApp/kosmokrator/main/install.sh | bash

# Configure and verify this integration.
kosmokrator integrations:configure matrix --set access_token="$MATRIX_ACCESS_TOKEN" --enable --read allow --write ask --json
kosmokrator integrations:doctor matrix --json
kosmokrator integrations:status --json

Credentials

Authentication type: Bearer token bearer_token. Configure credentials once, then reuse the same stored profile from scripts, coding CLIs, Lua, and MCP.

KeyEnv varTypeRequiredLabel
access_token MATRIX_ACCESS_TOKEN Secret secret yes Access Token
url MATRIX_URL URL url no Homeserver URL

Command Patterns

The generic command is stable across every integration. The provider shortcut is shorter for humans.

Generic CLI call 
kosmo integrations:call matrix.matrix_list_rooms '{"limit":1,"from":"example_from"}' --json
Provider shortcut 
kosmo integrations:matrix matrix_list_rooms '{"limit":1,"from":"example_from"}' --json

Discovery

These commands return structured output for coding agents that need to inspect capabilities before choosing a function.

Discovery commands 
kosmo integrations:docs matrix --json
kosmo integrations:docs matrix.matrix_list_rooms --json
kosmo integrations:schema matrix.matrix_list_rooms --json
kosmo integrations:search "Matrix" --json
kosmo integrations:list --json

Automation Contexts

The same configured command surface works in these environments. The command does not change unless the host wrapper, credentials, or permissions change.

CI Run integration calls from CI jobs with JSON output, explicit credentials, and predictable exit status. Cron Jobs Schedule repeatable integration workflows from cron while keeping credentials in KosmoKrator config. Shell Scripts Call integration functions from shell scripts with stable JSON input and output. Headless Automation Use KosmoKrator as a non-interactive integration runtime for local automations and wrappers. Coding Agents Let coding agents discover schemas and execute integration functions through CLI commands or MCP.

CLI Functions

Every function below can be called headlessly. Commands are highlighted, copyable, and scroll horizontally when payloads are long.

matrix.matrix_list_rooms

List rooms the authenticated user has joined on Matrix. Returns room IDs, names, and aliases.

Read read
Parameters
limit, from
Generic call 
kosmo integrations:call matrix.matrix_list_rooms '{"limit":1,"from":"example_from"}' --json
Shortcut 
kosmo integrations:matrix matrix_list_rooms '{"limit":1,"from":"example_from"}' --json

matrix.matrix_get_room

Get details of a specific Matrix room, including name, topic, members, and aliases.

Read read
Parameters
room_id
Generic call 
kosmo integrations:call matrix.matrix_get_room '{"room_id":"example_room_id"}' --json
Shortcut 
kosmo integrations:matrix matrix_get_room '{"room_id":"example_room_id"}' --json

matrix.matrix_create_room

Create a new room on the Matrix homeserver. Returns the newly created room ID.

Write write
Parameters
name, topic, visibility, preset
Generic call 
kosmo integrations:call matrix.matrix_create_room '{"name":"example_name","topic":"example_topic","visibility":"example_visibility","preset":"example_preset"}' --json
Shortcut 
kosmo integrations:matrix matrix_create_room '{"name":"example_name","topic":"example_topic","visibility":"example_visibility","preset":"example_preset"}' --json

matrix.matrix_send_message

Send a text message to a Matrix room. Uses a unique transaction ID to prevent duplicate messages.

Write write
Parameters
room_id, body, msgtype, txn_id
Generic call 
kosmo integrations:call matrix.matrix_send_message '{"room_id":"example_room_id","body":"example_body","msgtype":"example_msgtype","txn_id":"example_txn_id"}' --json
Shortcut 
kosmo integrations:matrix matrix_send_message '{"room_id":"example_room_id","body":"example_body","msgtype":"example_msgtype","txn_id":"example_txn_id"}' --json

matrix.matrix_list_members

List members of a Matrix room. Returns user IDs, display names, and avatar URLs.

Read read
Parameters
room_id, limit
Generic call 
kosmo integrations:call matrix.matrix_list_members '{"room_id":"example_room_id","limit":1}' --json
Shortcut 
kosmo integrations:matrix matrix_list_members '{"room_id":"example_room_id","limit":1}' --json

matrix.matrix_get_profile

Get a Matrix user's profile information, including display name and avatar URL.

Read read
Parameters
user_id
Generic call 
kosmo integrations:call matrix.matrix_get_profile '{"user_id":"example_user_id"}' --json
Shortcut 
kosmo integrations:matrix matrix_get_profile '{"user_id":"example_user_id"}' --json

matrix.matrix_get_current_user

Get the currently authenticated Matrix user's information, including user ID and device ID.

Read read
Parameters
none
Generic call 
kosmo integrations:call matrix.matrix_get_current_user '{}' --json
Shortcut 
kosmo integrations:matrix matrix_get_current_user '{}' --json

Function Schemas

Use these parameter tables when building CLI payloads without calling integrations:schema first.

matrix.matrix_list_rooms 2 parameters
Schema command 
kosmo integrations:schema matrix.matrix_list_rooms --json
ParameterTypeRequiredDescription
limit integer no Maximum number of rooms to return (default: 50).
from string no Pagination token from a previous response to get the next page.
matrix.matrix_get_room 1 parameters
Schema command 
kosmo integrations:schema matrix.matrix_get_room --json
ParameterTypeRequiredDescription
room_id string yes The room ID (e.g., "!abc123:matrix.org").
matrix.matrix_create_room 4 parameters
Schema command 
kosmo integrations:schema matrix.matrix_create_room --json
ParameterTypeRequiredDescription
name string yes The room name (displayed to users).
topic string no The room topic / description.
visibility string no Room visibility: "public" or "private" (default: "private").
preset string no Room preset: "private_chat", "public_chat", or "trusted_private_chat" (default: "private_chat").
matrix.matrix_send_message 4 parameters
Schema command 
kosmo integrations:schema matrix.matrix_send_message --json
ParameterTypeRequiredDescription
room_id string yes The room ID to send the message to (e.g., "!abc123:matrix.org").
body string yes The message body text.
msgtype string no Message type: "m.text" (default), "m.notice", "m.emote", or "m.html".
txn_id string no Unique transaction ID. If omitted, a random ID is generated.
matrix.matrix_list_members 2 parameters
Schema command 
kosmo integrations:schema matrix.matrix_list_members --json
ParameterTypeRequiredDescription
room_id string yes The room ID (e.g., "!abc123:matrix.org").
limit integer no Maximum number of members to return (default: 100).
matrix.matrix_get_profile 1 parameters
Schema command 
kosmo integrations:schema matrix.matrix_get_profile --json
ParameterTypeRequiredDescription
user_id string yes The Matrix user ID (e.g., "@alice:matrix.org").
matrix.matrix_get_current_user 0 parameters
Schema command 
kosmo integrations:schema matrix.matrix_get_current_user --json
ParameterTypeRequiredDescription
No parameters.

Permissions

Headless calls still follow the integration read/write permission policy. Configure read/write defaults with integrations:configure. Add --force only for trusted automation that should bypass that policy.