Skip to content

v0.1.2

Choose a tag to compare

View all tags
@ruslanmv ruslanmv released this 25 Aug 22:00
· 34 commits to master since this release
v0.1.2
c084840

matrix-cli 0.1.2 — Release Notes

Date: 2025-08-25

This release tightens security and polish across the board: safe installs, health diagnostics, first-class MCP probing, a smarter process list (with machine-readable modes), and a new uninstaller.

Highlights

  • ✅ New: matrix uninstall — remove one or many aliases safely (with optional file purge).
  • ✅ New: matrix ps --plain / --json — machine-readable process listings for scripts/CI.
  • ✅ New: matrix mcp — probe/call local MCP servers over SSE or WebSocket.
  • ✅ New: matrix connection — quick Hub health check (human + JSON, CI-friendly exits).
  • ✅ Safer installs: no more 500s from leaking local paths; installs are planned with a safe label and materialized locally.
  • ✅ Run UX: after matrix run, we print a clickable URL/health link and practical follow-ups (e.g., matrix mcp probe …).

Added

Uninstaller

matrix uninstall cleans up aliases and (optionally) on-disk artifacts with guardrails.

# Single alias
matrix uninstall hello-sse-server

# Many aliases (prompted)
matrix uninstall a1 a2

# Everything (no prompts) and purge files under ~/.matrix/runners
matrix uninstall --all --purge --force-stop -y

# Dry-run (show actions only)
matrix uninstall --all --dry-run

Safety & behavior

  • Removes alias mappings via SDK store (falls back to ~/.matrix/aliases.json).
  • Stops running processes first (--force-stop), or skip them with --stopped-only.
  • File purge is opt-in (--purge) and restricted to ~/.matrix/runners by default.
  • --force-files can remove targets outside the safe directory (use sparingly).
  • Exit codes: 0 success, 2 completed with warnings/errors.

Process list: plain & JSON

matrix ps now has machine-readable modes to make scripting easier, alongside the human table that now includes a URL column.

# Plain TSV: alias  pid  port  uptime_seconds  url  target
matrix ps --plain

# JSON array of objects
matrix ps --json

Details

  • URL is inferred from host (defaults to 127.0.0.1 or $MATRIX_PS_HOST), port, and runner.json endpoint (fallback /messages/).
  • Human table remains the default, unchanged — just smarter.

MCP utilities (SSE/WS)

Interact with any local MCP server, even those not started by Matrix.

# Probe by alias (auto-discovers port; endpoint from runner.json or /messages/)
matrix mcp probe --alias hello-sse-server

# Or by explicit URL
matrix mcp probe --url http://127.0.0.1:52305/messages/

# Call a tool (optional JSON args)
matrix mcp call hello --alias hello-sse-server --args '{}'

# JSON mode (great for CI)
matrix mcp probe --alias hello-sse-server --json

Notes

  • Works out-of-the-box for SSE with mcp>=1.13.1 (install via pip install "matrix-cli[mcp]").
  • WebSocket URLs require websockets (imported only if ws:///wss:// is used).
  • Alias auto-discovery is resilient: case-insensitive match, and fallback by target path in the alias store, with helpful suggestions if not found.
  • Exit codes: 0 success, 2 failure, 130 interrupted.

Connection health

matrix connection checks Hub health and reports latency.

matrix connection            # human output
matrix connection --json     # structured, exit 0/2
matrix connection --timeout 3.0

Built on the same hardened TLS policy as the rest of the CLI (see below).

Changed

Install flow: safe by design

  • The CLI requests a plan from the Hub using a safe label (<alias>/<version>) — never your absolute local path.
  • Artifacts are materialized locally via the SDK installer.
  • Preflight write test ensures your local target is writable before network calls.
  • Short IDs resolve to fully-qualified IDs using a tiny on-disk cache (~/.matrix/cache/resolve.json, per-hub, short TTL).
  • If the public Hub is unreachable due to DNS/connection issues, we try once against a local dev Hub at http://localhost:443 and tell you.

Run UX

After a successful matrix run, we print:

  • Clickable base URL and explicit health URL.
  • A logs hint.
  • Practical follow-ups (e.g., matrix mcp probe --alias <name>, matrix mcp call <tool> …) so you can immediately exercise your server.

Fixed / Hardened

  • TLS verification is consistent across the CLI:

    • Respects REQUESTS_CA_BUNDLE / SSL_CERT_FILE.
    • Tries OS trust via truststore when available; falls back to certifi.
    • httpx clients (even in the SDK) default to the same verify policy.

  • Search/resolve robustness and caching to avoid extra round-trips.

  • Better error messages for offline scenarios and alias mismatches (suggestions + running aliases list).

Compatibility

  • Python 3.11+

  • Matrix Python SDK ≥ 0.1.2

  • Optional:

    • mcp>=1.13.1 (for matrix mcp …)
    • websockets>=12 (only if you use WS endpoints)

Upgrade

pip install -U matrix-cli

# Optional extras
pip install -U "matrix-cli[mcp]"     # MCP client
pip install -U websockets            # WS probing support

Corporate CA / proxies:

export SSL_CERT_FILE=/path/to/ca.pem
# or
export REQUESTS_CA_BUNDLE=/path/to/ca.pem

Command recap

# Health
matrix connection
matrix connection --json --timeout 3

# Search / Install / Run
matrix search "hello" --type mcp_server --limit 5
matrix install hello-sse-server --alias hello-sse-server
matrix run hello-sse-server

# Processes (human + machine)
matrix ps
matrix ps --plain
matrix ps --json

# MCP
matrix mcp probe --alias hello-sse-server
matrix mcp call hello --alias hello-sse-server --args '{}'

# Logs / Stop / Doctor
matrix logs hello-sse-server -f
matrix stop hello-sse-server
matrix doctor hello-sse-server

# Uninstall
matrix uninstall hello-sse-server
matrix uninstall --all --purge --force-stop -y

Known notes

  • The inferred URL in ps uses $MATRIX_PS_HOST when set, otherwise 127.0.0.1.
  • Endpoint inference prefers runner.json (transport/sse/env), falling back to /messages/.

Thank you to everyone who reported issues and tested pre-releases — your feedback directly shaped this one.

Assets 4
Loading