Can I use Matrix as a CLI?

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

Can I expose Matrix through MCP?

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

Where are Matrix credentials stored?

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

Can I deny write access for Matrix MCP tools?

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

communication

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.

7 functions 5 read 2 write Bearer token auth

Submit Matrix feedback View package source

Matrix CLI Setup

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

# 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 use the same stored profile from scripts, coding CLIs, Lua code mode, and the MCP gateway.

Key	Env var	Type	Required	Label
`access_token`	`MATRIX_ACCESS_TOKEN`	Secret `secret`	yes	Access Token
`url`	`MATRIX_URL`	URL `url`	no	Homeserver URL

Call Matrix Headlessly

Use the generic call form when another coding CLI or script needs a stable universal interface.

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

Use the provider shortcut form for shorter human-facing commands.

kosmo integrations:matrix matrix_list_rooms '{
  "limit": 1,
  "from": "example_from"
}' --json

Agent Discovery Commands

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

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

All CLI Functions

Every function below can be called headlessly. The generic form is stable across all integrations; the provider shortcut is shorter but specific to Matrix.

`matrix.matrix_list_rooms`

Read read

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

Parameters: limit, from

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

`matrix.matrix_get_room`

Read read

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

Parameters: room_id

Generic CLI call

kosmo integrations:call matrix.matrix_get_room '{"room_id":"example_room_id"}' --json

Provider shortcut

kosmo integrations:matrix matrix_get_room '{"room_id":"example_room_id"}' --json

`matrix.matrix_create_room`

Write write

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

Parameters: name, topic, visibility, preset

Generic CLI call

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

Provider shortcut

kosmo integrations:matrix matrix_create_room '{"name":"example_name","topic":"example_topic","visibility":"example_visibility","preset":"example_preset"}' --json

`matrix.matrix_send_message`

Write write

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

Parameters: room_id, body, msgtype, txn_id

Generic CLI 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

Provider 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`

Read read

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

Parameters: room_id, limit

Generic CLI call

kosmo integrations:call matrix.matrix_list_members '{"room_id":"example_room_id","limit":1}' --json

Provider shortcut

kosmo integrations:matrix matrix_list_members '{"room_id":"example_room_id","limit":1}' --json

`matrix.matrix_get_profile`

Read read

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

Parameters: user_id

Generic CLI call

kosmo integrations:call matrix.matrix_get_profile '{"user_id":"example_user_id"}' --json

Provider shortcut

kosmo integrations:matrix matrix_get_profile '{"user_id":"example_user_id"}' --json

`matrix.matrix_get_current_user`

Read read

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

Parameters: none

Generic CLI call

kosmo integrations:call matrix.matrix_get_current_user '{}' --json

Provider 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`

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

Operation: Read read
Schema command: kosmo integrations:schema matrix.matrix_list_rooms --json

Parameter	Type	Required	Description
`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`

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

Operation: Read read
Schema command: kosmo integrations:schema matrix.matrix_get_room --json

Parameter	Type	Required	Description
`room_id`	string	yes	The room ID (e.g., "!abc123:matrix.org").

`matrix.matrix_create_room`

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

Operation: Write write
Schema command: kosmo integrations:schema matrix.matrix_create_room --json

Parameter	Type	Required	Description
`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`

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

Operation: Write write
Schema command: kosmo integrations:schema matrix.matrix_send_message --json

Parameter	Type	Required	Description
`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`

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

Operation: Read read
Schema command: kosmo integrations:schema matrix.matrix_list_members --json

Parameter	Type	Required	Description
`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`

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

Operation: Read read
Schema command: kosmo integrations:schema matrix.matrix_get_profile --json

Parameter	Type	Required	Description
`user_id`	string	yes	The Matrix user ID (e.g., "@alice:matrix.org").

`matrix.matrix_get_current_user`

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

Operation: Read read
Schema command: kosmo integrations:schema matrix.matrix_get_current_user --json

Parameter	Type	Required	Description
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.