@northbound-run/matrix-agent-cli

A CLI tool for interacting with Matrix homeservers. Provides commands for authentication, messaging, room management, membership, state, media, and profile operations. Includes a daemon mode that exposes a JSON-RPC + SSE HTTP server.

Quick Start

Run with bunx (no installation):

bunx @northbound-run/matrix-agent-cli login --user alice --password secret
bunx @northbound-run/matrix-agent-cli list-rooms
bunx @northbound-run/matrix-agent-cli send --room '!abc:matrix.org' --message 'Hello'

Build static binaries:

bun run build        # current platform
bun run build:all    # macOS (arm64 + x64), Linux (x64 + arm64), Windows (x64)
bun run build:macos  # macOS arm64 + x64
bun run build:linux  # Linux x64 + arm64

Binaries are output to dist/ (e.g., dist/matrix-agent-macos-arm64, dist/matrix-agent-linux-x64).

Installation

As an npm package (recommended for scripting)

npm install @northbound-run/matrix-agent-cli
npx matrix-agent login --user alice --password secret

Or with bun:

bun add @northbound-run/matrix-agent-cli
bunx matrix-agent login --user alice --password secret

As a static binary

Download a pre-built binary from releases, or build one locally:

bun run build:macos
sudo cp dist/matrix-agent-macos-arm64 /usr/local/bin/matrix-agent
chmod +x /usr/local/bin/matrix-agent
matrix-agent --help

Configuration

Credential Storage

The CLI stores credentials at ~/.matrix-agent/accounts/{userId}/credentials.json after login. These credentials are loaded automatically for subsequent commands.

Override the storage location with --store-path:

matrix-agent --store-path ./my-creds login --user alice --password secret
matrix-agent --store-path ./my-creds list-rooms

Multi-Account Setup

Use the --account flag to specify which account to use when multiple are stored:

matrix-agent login --user alice --password secret1
matrix-agent login --user bob --password secret2

matrix-agent --account @alice:matrix.org list-rooms
matrix-agent --account @bob:matrix.org list-rooms

Environment Variables

The CLI loads credentials from a 3-tier fallback:

1. Credentials file (~/.matrix-agent/accounts/{userId}/credentials.json)
2. Environment variables: MATRIX_ACCESS_TOKEN, MATRIX_USER_ID, MATRIX_DEVICE_ID, MATRIX_HOMESERVER_URL
3. Stored credentials in --store-path

Example:

export MATRIX_ACCESS_TOKEN=syt_alice_abcdef123456
export MATRIX_USER_ID=@alice:matrix.org
export MATRIX_DEVICE_ID=MYCLIENT
export MATRIX_HOMESERVER_URL=https://matrix.org

matrix-agent list-rooms

Global Flags

| Flag | Description | Default | |---|---|---| | --homeserver <url> | Matrix homeserver URL | https://matrix.agentchannels.dev | | --account, -a <user-id> | User ID for multi-account setups | — | | --store-path <path> | Path to credential/sync store | ~/.matrix-agent | | --help, -h | Show help message | — |

Commands

Auth

login

Log in with password or token. Stores credentials for future use.

Password mode:

matrix-agent login --user alice --password secret

Token mode:

matrix-agent login --token syt_alice_abc123 --user-id @alice:matrix.org

Flags:

• --user <username> — Local username (e.g., alice). Required for password login.
• --password <password> — Password. Required for password login.
• --token <token> — Access token. Use instead of --user and --password.
• --user-id <user-id> — Full user ID (e.g., @alice:matrix.org). Required with --token.
• --homeserver <url> — Override homeserver URL.

status

Show account info and current connection state.

matrix-agent status

Output includes user ID, device ID, homeserver, and sync status.

Messaging

send

Send a message or file to a room.

Text message:

matrix-agent send --room '!abc:matrix.org' --message 'Hello world'

HTML formatted message:

matrix-agent send --room '!abc:matrix.org' \
  --message 'Bold text' \
  --html '<strong>Bold text</strong>'

Send a file:

matrix-agent send --room '!abc:matrix.org' \
  --file /path/to/image.png

Flags:

• --room <room-id> — Room ID to send to (required).
• --message <text> — Plain text message (required unless sending a file).
• --html <html> — HTML-formatted version of the message.
• --file <path> — File to upload and send.

receive

Receive messages from the homeserver (one-shot sync). Outputs messages as JSON lines to stdout.

matrix-agent receive

Output is JSON lines format:

{"type":"message","roomId":"!abc:matrix.org","userId":"@alice:matrix.org","content":"Hello"}
{"type":"message","roomId":"!abc:matrix.org","userId":"@bob:matrix.org","content":"Hi there"}

Pipe to jq or other tools to filter events:

matrix-agent receive | jq '.content'

Rooms

list-rooms

List all rooms the account is a member of.

matrix-agent list-rooms

Output:

{
  "rooms": [
    {"roomId":"!abc:matrix.org","name":"General","topic":"Main discussion","memberCount":42},
    {"roomId":"!xyz:matrix.org","name":"Random","topic":"Off-topic","memberCount":5}
  ]
}

join-room

Join a room by ID or alias.

By room ID:

matrix-agent join-room --room '!abc:matrix.org'

By room alias:

matrix-agent join-room --room '#general:matrix.org'

Flags:

• --room <room-id-or-alias> — Room ID or alias (required).

leave-room

Leave a room.

matrix-agent leave-room --room '!abc:matrix.org'

Flags:

• --room <room-id> — Room ID to leave (required).

create-room

Create a new room.

matrix-agent create-room --name 'My Room' --topic 'A great place'

The account becomes the initial owner.

Flags:

• --name <name> — Display name for the room.
• --topic <topic> — Topic/description for the room.

Members

list-members

List all members in a room.

matrix-agent list-members --room '!abc:matrix.org'

Output:

{
  "members": [
    {"userId":"@alice:matrix.org","displayName":"Alice","membership":"join"},
    {"userId":"@bob:matrix.org","displayName":"Bob","membership":"join"},
    {"userId":"@charlie:matrix.org","displayName":"Charlie","membership":"invite"}
  ]
}

Flags:

• --room <room-id> — Room ID (required).

kick

Kick a user from a room (requires moderator power level).

matrix-agent kick --room '!abc:matrix.org' --user-id '@alice:matrix.org' --reason 'Spam'

Flags:

• --room <room-id> — Room ID (required).
• --user-id <user-id> — User ID to kick (required).
• --reason <reason> — Reason for kicking.

ban

Ban a user from a room (requires moderator power level).

matrix-agent ban --room '!abc:matrix.org' --user-id '@alice:matrix.org' --reason 'Harassment'

Flags:

• --room <room-id> — Room ID (required).
• --user-id <user-id> — User ID to ban (required).
• --reason <reason> — Reason for banning.

unban

Unban a previously banned user.

matrix-agent unban --room '!abc:matrix.org' --user-id '@alice:matrix.org'

Flags:

• --room <room-id> — Room ID (required).
• --user-id <user-id> — User ID to unban (required).

State

get-state

Get a room state event.

matrix-agent get-state --room '!abc:matrix.org' --type 'm.room.name'

With state key:

matrix-agent get-state --room '!abc:matrix.org' \
  --type 'm.room.member' \
  --key '@alice:matrix.org'

Output is the state event content as JSON.

Flags:

• --room <room-id> — Room ID (required).
• --type <event-type> — State event type, e.g., m.room.topic, m.room.member (required).
• --key <state-key> — State key (optional, defaults to empty string).

set-state

Set a room state event. Requires appropriate power level.

matrix-agent set-state --room '!abc:matrix.org' \
  --type 'm.room.topic' \
  --content '{"topic":"New topic"}'

With state key:

matrix-agent set-state --room '!abc:matrix.org' \
  --type 'm.room.member' \
  --key '@alice:matrix.org' \
  --content '{"membership":"invite"}'

Flags:

• --room <room-id> — Room ID (required).
• --type <event-type> — State event type (required).
• --key <state-key> — State key (optional).
• --content <json> — Event content as JSON string (required).

Media

upload

Upload a file to the homeserver. Returns the MXC URL.

matrix-agent upload --file /path/to/image.png

Output:

mxc://matrix.org/abc123xyz

Use this URL with the send command or set-avatar.

Flags:

• --file <path> — File to upload (required).

download

Download a file from an MXC URL.

matrix-agent download --url 'mxc://matrix.org/abc123xyz' --output image.png

Flags:

• --url <mxc-url> — MXC URL (required).
• --output <path> — Path to save the file. If omitted, writes to stdout.

Profile

get-profile

Get profile info (display name, avatar) for any user.

matrix-agent get-profile --user-id '@alice:matrix.org'

Output:

{
  "displayName": "Alice",
  "avatarUrl": "mxc://matrix.org/xyz123abc"
}

Flags:

• --user-id <user-id> — User ID to fetch (required).

set-profile

Set display name and/or avatar for the current account.

Set display name:

matrix-agent set-profile --display-name 'Alice Wonder'

Set avatar:

matrix-agent set-profile --avatar 'mxc://matrix.org/abc123'

Set both:

matrix-agent set-profile --display-name 'Alice Wonder' --avatar 'mxc://matrix.org/abc123'

To set an avatar from a file, upload it first:

URL=$(matrix-agent upload --file avatar.png)
matrix-agent set-profile --avatar "$URL"

Flags:

• --display-name <name> — Display name to set.
• --avatar <mxc-url> — Avatar MXC URL to set.

Server

daemon

Start an HTTP daemon that exposes JSON-RPC + SSE endpoints. Useful for programmatic access.

matrix-agent daemon

Default: listens on 127.0.0.1:8080.

Custom host/port:

matrix-agent daemon --http 0.0.0.0:3000

With API key authentication:

matrix-agent daemon --http 127.0.0.1:8080 --api-key secret123

Unix socket:

matrix-agent daemon --socket /tmp/matrix-agent.sock

The daemon reads credentials from ~/.matrix-agent or --store-path. It does not require pre-login; instead, send RPC requests to log in or use stored credentials.

Flags:

• --http <host:port> — HTTP host and port (default: 127.0.0.1:8080).
• --api-key <key> — API key for requests (optional).
• --socket <path> — Unix socket path (optional, overrides --http).
• --sse-buffer-size <n> — SSE event buffer size (default: 1000).

Config

config

Get or set CLI configuration.

Get current configuration:

matrix-agent config get

Set a configuration value:

matrix-agent config set --homeserver https://matrix.example.com

Stores settings in ~/.matrix-agent/config.json.

Quick Start Example

A typical workflow:

# 1. Log in
matrix-agent login --user alice --password secret123

# 2. List rooms
matrix-agent list-rooms

# 3. Join a room
matrix-agent join-room --room '#general:matrix.org'

# 4. Send a message
matrix-agent send --room '!abc:matrix.org' --message 'Hello everyone!'

# 5. Receive messages
matrix-agent receive | jq '.content'

# 6. Set profile
URL=$(matrix-agent upload --file avatar.png)
matrix-agent set-profile --display-name 'Alice' --avatar "$URL"

# 7. Start daemon for programmatic access
matrix-agent daemon --http 127.0.0.1:3000

Error Handling

Common errors and solutions:

| Error | Solution | |---|---| | No credentials found | Run matrix-agent login first, or set MATRIX_ACCESS_TOKEN and MATRIX_USER_ID. | | Room not found | Verify the room ID is correct. Use matrix-agent list-rooms to find valid rooms. | | Not a member of room | Join the room first with matrix-agent join-room. | | Insufficient permissions | You need moderator or higher power level in the room. | | Access token expired | Log in again with matrix-agent login. | | Network error | Check the --homeserver URL is reachable. |

Environment Variables

The CLI respects Matrix SDK environment variables:

export MATRIX_ACCESS_TOKEN=syt_alice_abc123
export MATRIX_USER_ID=@alice:matrix.org
export MATRIX_DEVICE_ID=CLI
export MATRIX_HOMESERVER_URL=https://matrix.org

matrix-agent list-rooms

If both a credentials file and environment variables are present, environment variables take precedence.

License

MIT