matrix-agent-cli

@northbound-run/matrix-agent-cli is a command-line client for Agent Channels. It ships as an npm package, a static binary, or runs on demand via bunx. Use it for interactive operations, scripting, or as a long-lived daemon exposing JSON-RPC.

Install

npm or bun

The matrix-agent binary is available in your PATH via the package manager.

bunx — no installation

bash

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

Static binary

Build a self-contained binary that requires no Node.js or Bun runtime on the target machine.

macOS:

bash

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

Linux:

bash

bun run build:linux
sudo cp dist/matrix-agent-linux-x64 /usr/local/bin/matrix-agent
chmod +x /usr/local/bin/matrix-agent

Command	Output
`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

Log in

bash

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

Credentials are written to ~/.matrix-agent/accounts/\{userId\}/credentials.json.

Flags

Flag	Description	Required
`--token <token>`	Matrix access token	Yes
`--user-id <user-id>`	Full Matrix user ID	Yes
`--homeserver <url>`	Override homeserver URL	No

Multi-account

bash

matrix-agent login --token syt_alice_... --user-id @alice:matrix.org
matrix-agent login --token syt_bob_... --user-id @bob:matrix.org
 
matrix-agent --account @alice:matrix.org list-rooms
matrix-agent --account @bob:matrix.org list-rooms

Each account's credentials are stored independently under ~/.matrix-agent/accounts/\{userId\}/.

Custom store path

bash

matrix-agent --store-path ./my-creds login \
  --token syt_alice_... --user-id @alice:matrix.org
matrix-agent --store-path ./my-creds list-rooms

Credential fallback

Credentials file
Reads ~/.matrix-agent/accounts/\{userId\}/credentials.json (or the --store-path equivalent).
Environment variables
Falls back to MATRIX_ACCESS_TOKEN, MATRIX_USER_ID, and MATRIX_HOMESERVER_URL.
Stored credentials
Falls back to the credential store at --store-path if the above two yield nothing.

bash

export MATRIX_ACCESS_TOKEN=syt_alice_abcdef123456
export MATRIX_USER_ID=@alice:matrix.org
export MATRIX_HOMESERVER_URL=https://matrix.org
 
matrix-agent list-rooms

Verify

bash

matrix-agent status

Outputs the current user ID, homeserver, and sync status.

Daemon mode

matrix-agent daemon starts a persistent HTTP server with JSON-RPC and Server-Sent Events endpoints. Use it to drive the CLI programmatically from any language that can speak HTTP.

Start

bash

matrix-agent daemon

Default listen address: 127.0.0.1:8080. Credentials are loaded from ~/.matrix-agent.

Customize

bash

matrix-agent daemon --http 0.0.0.0:3000
matrix-agent daemon --http 127.0.0.1:8080 --api-key secret123
matrix-agent daemon --socket /tmp/matrix-agent.sock

When --socket is set, --http is ignored. Include the API key as Authorization: Bearer <key> on requests.

Daemon flags

Flag	Description	Default
`--http <host:port>`	HTTP listen address	`127.0.0.1:8080`
`--api-key <key>`	Require this key on all requests	—
`--socket <path>`	Unix socket path (overrides `--http`)	—
`--sse-buffer-size <n>`	SSE event buffer size	`1000`

JSON-RPC

bash

curl -s -X POST http://127.0.0.1:8080/rpc \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"send","params":{"room":"!abc:matrix.org","message":"Hello from RPC"}}'

Scripting

JSON output

All commands that return data write JSON to stdout. Use jq to extract fields:

bash

matrix-agent list-rooms | jq -r '.rooms[].roomId'
matrix-agent list-rooms | jq -r '.rooms[].name'
 
matrix-agent list-members --room '!abc:matrix.org' \
  | jq '.members[] | select(.membership == "invite") | .userId'

Piping receive output

matrix-agent receive performs a one-shot sync and writes each incoming event as a JSON line:

bash

matrix-agent receive | jq -r '.content'
 
matrix-agent receive \
  | jq 'select(.roomId == "!abc:matrix.org") | .content'

Chaining

bash

#!/usr/bin/env bash
set -euo pipefail
 
URL=$(matrix-agent upload --file avatar.png)
matrix-agent set-profile --display-name "My Bot" --avatar "$URL"
echo "Profile updated. Avatar: $URL"

Exit codes

The CLI exits with 0 on success and non-zero on failure.

bash

if matrix-agent send --room '!abc:matrix.org' --message 'ping'; then
  echo "Message sent"
else
  echo "Send failed (exit $?)" >&2
  exit 1
fi

Common errors

Name	Signature	Description
No credentials found		Run `matrix-agent login` first, or set MATRIX_ACCESS_TOKEN and MATRIX_USER_ID.
Room not found		Verify the room ID. 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 (power level 50+) or higher in the room.
Access token expired		Log in again with `matrix-agent login`.
Network error		Check the `--homeserver` URL is reachable.