# ⚡️ Matrix CLI
*The command-line interface for **Matrix Hub** — search, inspect, install, run, probe MCP servers, manage remotes, check connectivity, and safely uninstall.*
[](https://pypi.org/project/matrix-cli/)
[](https://pypi.org/project/matrix-cli/)
[](https://github.com/agent-matrix/matrix-cli)
[](https://agent-matrix.github.io/matrix-cli/)
[](./LICENSE) <a href="https://github.com/agent-matrix/matrix-hub"><img src="https://img.shields.io/badge/Powered%20by-matrix--hub-brightgreen" alt="Powered by matrix-hub"></a>
> Requires **Python 3.11+** and **matrix-python-sdk ≥ 0.1.9**.
---
## 🌍 Why Matrix CLI
Matrix CLI gets you from **discovery → install → run → interact** with agents, tools, and MCP servers — fast. Built to be secure by default, delightful for developers, and friendly for automation worldwide.
---
## 🚀 What’s new in v0.1.6
Aligned with **matrix-python-sdk 0.1.9** (backwards-compatible refactor) and introduces a faster way to talk to your agents.
* **✨ New:** `matrix do <alias> <prompt>` — the quickest way to interact with a running agent.
* **Smarter runner discovery:** Auto-materializes `runner.json` from embedded b64/URL/object, embedded manifests (v1/v2), on-disk search, or inference (`server.py`, `package.json`). Synthesizes connector runners if an MCP URL is present.
* **Safer materialization:** Writes only under your target; supports base64 files, git/http artifacts; robust logging.
* **Faster environment prep:** Python: fresh venv + upgraded `pip/setuptools/wheel`, then `requirements.txt` or editable `pyproject.toml` / `setup.py`. Node: auto-detects **pnpm > yarn > npm**.
* **Connector-aware run (attach mode):** If `runner.json` is a connector with an MCP SSE URL, `matrix run` attaches (no local process). `matrix stop` becomes a no-op (clears the lock).
* **Better MCP probing & calls:** Tolerates `/sse` vs `/messages/`, clearer errors, `--json` for scripts.
* **Idempotent installs:** Re-install same alias with `--force --no-prompt` without surprises.
> Tip: `export MATRIX_SDK_DEBUG=1` for verbose installer logs.
---
## 🎬 A 5-Minute End-to-End Demo
Experience the full lifecycle with a Watsonx agent — from search to results.
### 0) Setup
Create a local `.env` with your credentials:
```bash
# .env
WATSONX_API_KEY="your_api_key_here"
WATSONX_URL="your_url_here"
WATSONX_PROJECT_ID="your_project_id_here"
```
### 1) 🔍 Discover
```bash
matrix search "watsonx" --type mcp_server --limit 5
```
### 2) 📦 Install
```bash
matrix install mcp_server:watsonx-agent@0.1.0 --alias watsonx-chat
```
### 3) 🚀 Run
```bash
matrix run watsonx-chat --port 6288
# ✓ URL: http://127.0.0.1:6288/sse
# Health: http://127.0.0.1:6288/health
```
### 4) ✨ Ask with **matrix do**
```bash
matrix do watsonx-chat "Tell me about Genoa"
```
### 5) ⚙️ Advanced call
```bash
matrix mcp call chat --alias watsonx-chat --args '{"query":"List three landmarks in Genoa"}'
```
### 6) 📋 Manage & clean up
```bash
matrix ps
matrix stop watsonx-chat
matrix uninstall watsonx-chat -y
```
---
## 📦 Install
```bash
# Recommended
pipx install matrix-cli
# Or with pip (active virtualenv)
pip install matrix-cli
```
### Optional extras
```bash
# Add MCP client (SSE works; WebSocket needs `websockets`)
pip install "matrix-cli[mcp]" # installs mcp>=1.13.1
# If you also want WebSocket probing:
pip install websockets
# Dev extras (linting, tests, docs)
pip install "matrix-cli[dev]"
# Using pipx? Inject extras later:
pipx inject matrix-cli mcp websockets
```
---
## ⚙️ Configuration
The CLI reads, in order: **environment variables**, `~/.config/matrix/cli.toml` (optional), then built-ins.
### Environment
```bash
export MATRIX_HUB_BASE="https://api.matrixhub.io" # or your dev hub
export MATRIX_HUB_TOKEN="..." # optional
export MATRIX_HOME="$HOME/.matrix" # optional; default ~/.matrix
# TLS (corporate CA/proxy)
export SSL_CERT_FILE=/path/to/ca.pem
# or
export REQUESTS_CA_BUNDLE=/path/to/ca.pem
# ps URL host override (display only)
export MATRIX_PS_HOST="localhost"
# Installer / builder verbosity (SDK ≥ 0.1.9)
export MATRIX_SDK_DEBUG=1
```
### Optional TOML (`~/.config/matrix/cli.toml`)
```toml
hub_base = "https://api.matrixhub.io"
token = ""
home = "~/.matrix"
```
---
## 🏁 Quick start
```bash
# Basics
matrix --version
matrix version
# Search (includes pending by default)
matrix search "hello"
# Filtered search
matrix search "hello" --type mcp_server --limit 5
# Install (short name resolves to mcp_server:<name>@<latest>)
matrix install hello-sse-server --alias hello-sse-server
# Run and interact
matrix run hello-sse-server
matrix do hello-sse-server "What is Matrix CLI?"
# Inspect
matrix ps # shows URL column
matrix logs hello-sse-server -f
matrix stop hello-sse-server
# Show raw details
matrix show mcp_server:hello-sse-server@0.1.0
# Hub health (human / JSON for CI)
matrix connection
matrix connection --json --timeout 3.0
```
**Demo GIFs**
---
## 🔍 Search tips
Useful filters:
* `--type {agent|tool|mcp_server}`
* `--mode {keyword|semantic|hybrid}`
* `--capabilities rag,sql`
* `--frameworks langchain,autogen`
* `--providers openai,anthropic`
* `--with-snippets`
* `--certified` (registered/certified only)
* `--json` for programmatic output
* `--exact` to fetch a specific ID
Examples:
```bash
# MCP servers about "hello"
matrix search "hello" --type mcp_server --limit 5
# Hybrid mode with snippets
matrix search "watsonx" --mode hybrid --with-snippets
# Structured results
matrix search "sql agent" --capabilities rag,sql --json
```
If the public Hub is unreachable, some operations try a **local dev Hub** once and tell you.
---
## 🧩 Install behavior (safer by design)
* Accepts `name`, `name@ver`, `ns:name`, `ns:name@ver`.
* If `ns` missing, prefers **`mcp_server`**.
* If `@version` missing, picks **latest** (stable > pre-release).
* Uses a small cache under `~/.matrix/cache/resolve.json` (per-hub, short TTL).
* **No absolute paths sent to the Hub** — the CLI sends a safe `<alias>/<version>` label, then **materializes locally**.
* Preflight checks ensure your local target is **writable** before network calls.
Examples:
```bash
# Short name; alias is optional (auto-suggested if omitted)
matrix install hello-sse-server --alias hello-sse-server
# Specific version
matrix install mcp_server:hello-sse-server@0.1.0
# Custom target
matrix install hello-sse-server --target ~/.matrix/runners/hello-sse-server/0.1.0
```
---
## ▶️ Run, interact, and probe
`matrix run <alias>` prints a click-ready **URL** and **Health** link, plus a logs hint.
```bash
# Instant interaction
matrix do <alias> "Your question here"
# Probe tools exposed by your local MCP server (auto-discovers port)
matrix mcp probe --alias <alias>
# Call a tool (optional args as JSON)
matrix mcp call <tool_name> --alias <alias> --args '{"key":"value"}'
```
---
## 🔗 Connector mode (attach to a remote/local MCP)
If you already have an MCP server listening (e.g. on `http://127.0.0.1:6289/sse`), **attach** to it without starting a local process by using a **connector runner**:
`~/.matrix/runners/<alias>/<version>/runner.json`:
```json
{
"type": "connector",
"name": "watsonx-chat",
"description": "Connector to Watsonx MCP over SSE",
"integration_type": "MCP",
"request_type": "SSE",
"url": "http://127.0.0.1:6289/sse",
"endpoint": "/sse",
"headers": {}
}
```
Then:
```bash
matrix run watsonx-chat
matrix ps # shows URL (PID=0 attach mode)
matrix mcp probe --alias watsonx-chat
matrix mcp call chat --alias watsonx-chat --args '{"query":"Hello"}'
```
> In connector mode, `matrix stop` simply clears the lock (no local process to kill).
---
## 🧪 MCP utilities (SSE/WS)
Probe and call tools on MCP servers.
```bash
# Probe by alias (auto-discovers port; infers endpoint)
matrix mcp probe --alias hello-sse-server
# Or probe by full SSE URL
matrix mcp probe --url http://127.0.0.1:52305/messages/
# Call a tool (optional args as JSON)
matrix mcp call hello --alias hello-sse-server --args '{}'
# JSON mode for scripts
matrix mcp probe --alias hello-sse-server --json
```
Notes:
* SSE works with `mcp>=1.13.1` (installed via the `mcp` extra).
* WebSocket URLs (`ws://`/`wss://`) require the `websockets` package.
* If a call fails, the CLI helps by listing tools and tolerates `/sse` vs `/messages/` endpoints.
---
## 🧭 Process management
`matrix ps` shows a **URL** column built from the runner’s port and endpoint (default `/messages/`).
```
┏━━━━━━━━━━━━━━━━━━┳━━━━━━┳━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ ALIAS ┃ PID ┃ PORT ┃ UPTIME ┃ URL ┃ TARGET ┃
┡━━━━━━━━━━━━━━━━━━╇━━━━━━╇━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ hello-sse-server │ 1234 ┃ 52305 ┃ 02:18:44 │ http://127.0.0.1:52305/messages/ │ ~/.matrix/runners/hello…/0.1.0 │
└──────────────────┴──────┴───────┴──────────┴──────────────────────────────────┴──────────────────────────────────┘
```
Copy the URL directly into:
```bash
matrix mcp probe --url http://127.0.0.1:52305/messages/
```
Script-friendly output:
```bash
# Plain (space-delimited): alias pid port uptime_seconds url target
matrix ps --plain
# JSON: array of objects with {alias,pid,port,uptime_seconds,url,target}
matrix ps --json
```
Other commands:
```bash
matrix logs <alias> [-f]
matrix stop <alias>
matrix doctor <alias>
```
---
## 🌐 Hub health & TLS
```bash
# Quick Hub health
matrix connection
matrix connection --json
```
TLS policy:
* Respects `REQUESTS_CA_BUNDLE` / `SSL_CERT_FILE`.
* Tries OS trust (when available).
* Falls back to `certifi`.
* Never throws on network errors in health checks — returns a structured status with exit codes.
---
## 🧹 Safe uninstall
Remove one or many aliases, and optionally purge local files.
```bash
# Uninstall one alias (keeps files by default)
matrix uninstall hello-sse-server
# Uninstall several and also delete files (safe paths only)
matrix uninstall hello-a hello-b --purge
# Remove everything from the local alias store (stop first, purge files)
matrix uninstall --all --force-stop --purge -y
# Dry-run (show what would be removed)
matrix uninstall --all --dry-run
```
Safety features:
* Only purges targets under `~/.matrix/runners` by default.
* Skips deleting files still referenced by other aliases.
* `--force-files` allows deleting outside the safe path (⚠️ **dangerous**; off by default).
* `--stopped-only` to avoid touching running aliases.
Exit codes: **0** success, **2** partial/failed.
---
## 🧰 Scripting & CI examples
```bash
# Search, parse with jq, then install the first result
results=$(matrix search "ocr table" --type tool --json)
first_id=$(echo "$results" | jq -r '.items[0].id')
matrix install "$first_id" --alias ocr-table --force --no-prompt
# Health check in CI (exit code 0/2)
matrix connection --json
# Get the port quickly for an alias
port=$(matrix ps --plain | awk '$1=="hello-sse-server"{print $3; exit}')
matrix mcp probe --url "http://127.0.0.1:${port}/messages/" --json
```
---
## 🐞 Troubleshooting
* **“Missing 'mcp' package”** — Install the optional extra: `pip install "matrix-cli[mcp]"` (and `pip install websockets` for WS).
* **TLS / certificate errors** — Set `SSL_CERT_FILE` or `REQUESTS_CA_BUNDLE` to your CA bundle.
* **Alias not found when probing** — Use the alias shown by `matrix ps` (case-insensitive), or pass `--url` directly.
* **Connector mode shows PID=0** — Expected in attach mode; ensure the remote server is running.
---
## 🛠️ Development
```bash
# Create venv and install (editable) with useful extras
python3.11 -m venv .venv
source .venv/bin/activate
pip install -U pip
pip install -e ".[dev,mcp]"
# Common tasks
make lint # ruff/flake8
make fmt # black
make typecheck # mypy
make test # pytest
make build # sdist + wheel
```
---
## 🌍 About MatrixHub
MatrixHub aims to be the **pip of agents & MCP servers** — a secure, open, and developer-friendly registry and runtime that scales from personal laptops to global enterprises. If you’re building agents, tools, or MCP services, Matrix CLI gets you from idea to running in seconds.
---
## 📄 License
Apache License 2.0
---
## ✉️ Feedback
Issues and PRs welcome! If you hit rough edges with install/probing/health, the new **connector** flow, or `ps --plain/--json` and `uninstall`, please open an issue with your command, output, and environment.
* GitHub: [https://github.com/agent-matrix/matrix-cli](https://github.com/agent-matrix/matrix-cli)
* PyPI: [https://pypi.org/project/matrix-cli/](https://pypi.org/project/matrix-cli/)
Raw data
{
"_id": null,
"home_page": null,
"name": "matrix-cli",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.11",
"maintainer_email": null,
"keywords": "matrix, mcp, model context protocol, cli, agents, tools, runtime, search, installer",
"author": null,
"author_email": "Ruslan Magana Vsevolodovna <contact@ruslanmv.com>",
"download_url": "https://files.pythonhosted.org/packages/cd/a0/355f5f0a10c89050dff0ddde186fbf902cb6628b9b053aed0be430354abe/matrix_cli-0.1.7.tar.gz",
"platform": null,
"description": "# \u26a1\ufe0f Matrix CLI\n\n*The command-line interface for **Matrix Hub** \u2014 search, inspect, install, run, probe MCP servers, manage remotes, check connectivity, and safely uninstall.*\n\n[](https://pypi.org/project/matrix-cli/)\n[](https://pypi.org/project/matrix-cli/)\n[](https://github.com/agent-matrix/matrix-cli)\n[](https://agent-matrix.github.io/matrix-cli/)\n[](./LICENSE) <a href=\"https://github.com/agent-matrix/matrix-hub\"><img src=\"https://img.shields.io/badge/Powered%20by-matrix--hub-brightgreen\" alt=\"Powered by matrix-hub\"></a>\n\n> Requires **Python 3.11+** and **matrix-python-sdk \u2265 0.1.9**.\n\n---\n\n## \ud83c\udf0d Why Matrix CLI\n\nMatrix CLI gets you from **discovery \u2192 install \u2192 run \u2192 interact** with agents, tools, and MCP servers \u2014 fast. Built to be secure by default, delightful for developers, and friendly for automation worldwide.\n\n---\n## \ud83d\ude80 What\u2019s new in v0.1.6\n\nAligned with **matrix-python-sdk 0.1.9** (backwards-compatible refactor) and introduces a faster way to talk to your agents.\n\n* **\u2728 New:** `matrix do <alias> <prompt>` \u2014 the quickest way to interact with a running agent.\n* **Smarter runner discovery:** Auto-materializes `runner.json` from embedded b64/URL/object, embedded manifests (v1/v2), on-disk search, or inference (`server.py`, `package.json`). Synthesizes connector runners if an MCP URL is present.\n* **Safer materialization:** Writes only under your target; supports base64 files, git/http artifacts; robust logging.\n* **Faster environment prep:** Python: fresh venv + upgraded `pip/setuptools/wheel`, then `requirements.txt` or editable `pyproject.toml` / `setup.py`. Node: auto-detects **pnpm > yarn > npm**.\n* **Connector-aware run (attach mode):** If `runner.json` is a connector with an MCP SSE URL, `matrix run` attaches (no local process). `matrix stop` becomes a no-op (clears the lock).\n* **Better MCP probing & calls:** Tolerates `/sse` vs `/messages/`, clearer errors, `--json` for scripts.\n* **Idempotent installs:** Re-install same alias with `--force --no-prompt` without surprises.\n\n> Tip: `export MATRIX_SDK_DEBUG=1` for verbose installer logs.\n\n\n\n\n---\n\n## \ud83c\udfac A 5-Minute End-to-End Demo\n\nExperience the full lifecycle with a Watsonx agent \u2014 from search to results.\n\n### 0) Setup\n\nCreate a local `.env` with your credentials:\n\n```bash\n# .env\nWATSONX_API_KEY=\"your_api_key_here\"\nWATSONX_URL=\"your_url_here\"\nWATSONX_PROJECT_ID=\"your_project_id_here\"\n```\n\n### 1) \ud83d\udd0d Discover\n\n```bash\nmatrix search \"watsonx\" --type mcp_server --limit 5\n```\n\n### 2) \ud83d\udce6 Install\n\n```bash\nmatrix install mcp_server:watsonx-agent@0.1.0 --alias watsonx-chat\n```\n\n### 3) \ud83d\ude80 Run\n\n```bash\nmatrix run watsonx-chat --port 6288\n# \u2713 URL: http://127.0.0.1:6288/sse\n# Health: http://127.0.0.1:6288/health\n```\n\n### 4) \u2728 Ask with **matrix do**\n\n```bash\nmatrix do watsonx-chat \"Tell me about Genoa\"\n```\n\n### 5) \u2699\ufe0f Advanced call\n\n```bash\nmatrix mcp call chat --alias watsonx-chat --args '{\"query\":\"List three landmarks in Genoa\"}'\n```\n\n### 6) \ud83d\udccb Manage & clean up\n\n```bash\nmatrix ps\nmatrix stop watsonx-chat\nmatrix uninstall watsonx-chat -y\n```\n\n---\n\n## \ud83d\udce6 Install\n\n```bash\n# Recommended\npipx install matrix-cli\n\n# Or with pip (active virtualenv)\npip install matrix-cli\n```\n\n### Optional extras\n\n```bash\n# Add MCP client (SSE works; WebSocket needs `websockets`)\npip install \"matrix-cli[mcp]\" # installs mcp>=1.13.1\n\n# If you also want WebSocket probing:\npip install websockets\n\n# Dev extras (linting, tests, docs)\npip install \"matrix-cli[dev]\"\n\n# Using pipx? Inject extras later:\npipx inject matrix-cli mcp websockets\n```\n\n---\n\n## \u2699\ufe0f Configuration\n\nThe CLI reads, in order: **environment variables**, `~/.config/matrix/cli.toml` (optional), then built-ins.\n\n### Environment\n\n```bash\nexport MATRIX_HUB_BASE=\"https://api.matrixhub.io\" # or your dev hub\nexport MATRIX_HUB_TOKEN=\"...\" # optional\nexport MATRIX_HOME=\"$HOME/.matrix\" # optional; default ~/.matrix\n\n# TLS (corporate CA/proxy)\nexport SSL_CERT_FILE=/path/to/ca.pem\n# or\nexport REQUESTS_CA_BUNDLE=/path/to/ca.pem\n\n# ps URL host override (display only)\nexport MATRIX_PS_HOST=\"localhost\"\n\n# Installer / builder verbosity (SDK \u2265 0.1.9)\nexport MATRIX_SDK_DEBUG=1\n```\n\n### Optional TOML (`~/.config/matrix/cli.toml`)\n\n```toml\nhub_base = \"https://api.matrixhub.io\"\ntoken = \"\"\nhome = \"~/.matrix\"\n```\n\n---\n\n## \ud83c\udfc1 Quick start\n\n```bash\n# Basics\nmatrix --version\nmatrix version\n\n# Search (includes pending by default)\nmatrix search \"hello\"\n\n# Filtered search\nmatrix search \"hello\" --type mcp_server --limit 5\n\n# Install (short name resolves to mcp_server:<name>@<latest>)\nmatrix install hello-sse-server --alias hello-sse-server\n\n# Run and interact\nmatrix run hello-sse-server\nmatrix do hello-sse-server \"What is Matrix CLI?\"\n\n# Inspect\nmatrix ps # shows URL column\nmatrix logs hello-sse-server -f\nmatrix stop hello-sse-server\n\n# Show raw details\nmatrix show mcp_server:hello-sse-server@0.1.0\n\n# Hub health (human / JSON for CI)\nmatrix connection\nmatrix connection --json --timeout 3.0\n```\n\n**Demo GIFs**\n\n\n\n\n---\n\n## \ud83d\udd0d Search tips\n\nUseful filters:\n\n* `--type {agent|tool|mcp_server}`\n* `--mode {keyword|semantic|hybrid}`\n* `--capabilities rag,sql`\n* `--frameworks langchain,autogen`\n* `--providers openai,anthropic`\n* `--with-snippets`\n* `--certified` (registered/certified only)\n* `--json` for programmatic output\n* `--exact` to fetch a specific ID\n\nExamples:\n\n```bash\n# MCP servers about \"hello\"\nmatrix search \"hello\" --type mcp_server --limit 5\n\n# Hybrid mode with snippets\nmatrix search \"watsonx\" --mode hybrid --with-snippets\n\n# Structured results\nmatrix search \"sql agent\" --capabilities rag,sql --json\n```\n\nIf the public Hub is unreachable, some operations try a **local dev Hub** once and tell you.\n\n---\n\n## \ud83e\udde9 Install behavior (safer by design)\n\n* Accepts `name`, `name@ver`, `ns:name`, `ns:name@ver`.\n* If `ns` missing, prefers **`mcp_server`**.\n* If `@version` missing, picks **latest** (stable > pre-release).\n* Uses a small cache under `~/.matrix/cache/resolve.json` (per-hub, short TTL).\n* **No absolute paths sent to the Hub** \u2014 the CLI sends a safe `<alias>/<version>` label, then **materializes locally**.\n* Preflight checks ensure your local target is **writable** before network calls.\n\nExamples:\n\n```bash\n# Short name; alias is optional (auto-suggested if omitted)\nmatrix install hello-sse-server --alias hello-sse-server\n\n# Specific version\nmatrix install mcp_server:hello-sse-server@0.1.0\n\n# Custom target\nmatrix install hello-sse-server --target ~/.matrix/runners/hello-sse-server/0.1.0\n```\n\n---\n\n## \u25b6\ufe0f Run, interact, and probe\n\n`matrix run <alias>` prints a click-ready **URL** and **Health** link, plus a logs hint.\n\n```bash\n# Instant interaction\nmatrix do <alias> \"Your question here\"\n\n# Probe tools exposed by your local MCP server (auto-discovers port)\nmatrix mcp probe --alias <alias>\n\n# Call a tool (optional args as JSON)\nmatrix mcp call <tool_name> --alias <alias> --args '{\"key\":\"value\"}'\n```\n\n---\n\n## \ud83d\udd17 Connector mode (attach to a remote/local MCP)\n\nIf you already have an MCP server listening (e.g. on `http://127.0.0.1:6289/sse`), **attach** to it without starting a local process by using a **connector runner**:\n\n`~/.matrix/runners/<alias>/<version>/runner.json`:\n\n```json\n{\n \"type\": \"connector\",\n \"name\": \"watsonx-chat\",\n \"description\": \"Connector to Watsonx MCP over SSE\",\n \"integration_type\": \"MCP\",\n \"request_type\": \"SSE\",\n \"url\": \"http://127.0.0.1:6289/sse\",\n \"endpoint\": \"/sse\",\n \"headers\": {}\n}\n```\n\nThen:\n\n```bash\nmatrix run watsonx-chat\nmatrix ps # shows URL (PID=0 attach mode)\nmatrix mcp probe --alias watsonx-chat\nmatrix mcp call chat --alias watsonx-chat --args '{\"query\":\"Hello\"}'\n```\n\n> In connector mode, `matrix stop` simply clears the lock (no local process to kill).\n\n---\n\n## \ud83e\uddea MCP utilities (SSE/WS)\n\nProbe and call tools on MCP servers.\n\n```bash\n# Probe by alias (auto-discovers port; infers endpoint)\nmatrix mcp probe --alias hello-sse-server\n\n# Or probe by full SSE URL\nmatrix mcp probe --url http://127.0.0.1:52305/messages/\n\n# Call a tool (optional args as JSON)\nmatrix mcp call hello --alias hello-sse-server --args '{}'\n\n# JSON mode for scripts\nmatrix mcp probe --alias hello-sse-server --json\n```\n\nNotes:\n\n* SSE works with `mcp>=1.13.1` (installed via the `mcp` extra).\n* WebSocket URLs (`ws://`/`wss://`) require the `websockets` package.\n* If a call fails, the CLI helps by listing tools and tolerates `/sse` vs `/messages/` endpoints.\n\n---\n\n## \ud83e\udded Process management\n\n`matrix ps` shows a **URL** column built from the runner\u2019s port and endpoint (default `/messages/`).\n\n```\n\u250f\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2533\u2501\u2501\u2501\u2501\u2501\u2501\u2533\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2533\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2533\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2533\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2513\n\u2503 ALIAS \u2503 PID \u2503 PORT \u2503 UPTIME \u2503 URL \u2503 TARGET \u2503\n\u2521\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2547\u2501\u2501\u2501\u2501\u2501\u2501\u2547\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2547\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2547\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2547\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2529\n\u2502 hello-sse-server \u2502 1234 \u2503 52305 \u2503 02:18:44 \u2502 http://127.0.0.1:52305/messages/ \u2502 ~/.matrix/runners/hello\u2026/0.1.0 \u2502\n\u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\n```\n\nCopy the URL directly into:\n\n```bash\nmatrix mcp probe --url http://127.0.0.1:52305/messages/\n```\n\nScript-friendly output:\n\n```bash\n# Plain (space-delimited): alias pid port uptime_seconds url target\nmatrix ps --plain\n\n# JSON: array of objects with {alias,pid,port,uptime_seconds,url,target}\nmatrix ps --json\n```\n\nOther commands:\n\n```bash\nmatrix logs <alias> [-f]\nmatrix stop <alias>\nmatrix doctor <alias>\n```\n\n---\n\n## \ud83c\udf10 Hub health & TLS\n\n```bash\n# Quick Hub health\nmatrix connection\nmatrix connection --json\n```\n\nTLS policy:\n\n* Respects `REQUESTS_CA_BUNDLE` / `SSL_CERT_FILE`.\n* Tries OS trust (when available).\n* Falls back to `certifi`.\n* Never throws on network errors in health checks \u2014 returns a structured status with exit codes.\n\n---\n\n## \ud83e\uddf9 Safe uninstall\n\nRemove one or many aliases, and optionally purge local files.\n\n```bash\n# Uninstall one alias (keeps files by default)\nmatrix uninstall hello-sse-server\n\n# Uninstall several and also delete files (safe paths only)\nmatrix uninstall hello-a hello-b --purge\n\n# Remove everything from the local alias store (stop first, purge files)\nmatrix uninstall --all --force-stop --purge -y\n\n# Dry-run (show what would be removed)\nmatrix uninstall --all --dry-run\n```\n\nSafety features:\n\n* Only purges targets under `~/.matrix/runners` by default.\n* Skips deleting files still referenced by other aliases.\n* `--force-files` allows deleting outside the safe path (\u26a0\ufe0f **dangerous**; off by default).\n* `--stopped-only` to avoid touching running aliases.\n\nExit codes: **0** success, **2** partial/failed.\n\n---\n\n## \ud83e\uddf0 Scripting & CI examples\n\n```bash\n# Search, parse with jq, then install the first result\nresults=$(matrix search \"ocr table\" --type tool --json)\nfirst_id=$(echo \"$results\" | jq -r '.items[0].id')\nmatrix install \"$first_id\" --alias ocr-table --force --no-prompt\n\n# Health check in CI (exit code 0/2)\nmatrix connection --json\n\n# Get the port quickly for an alias\nport=$(matrix ps --plain | awk '$1==\"hello-sse-server\"{print $3; exit}')\nmatrix mcp probe --url \"http://127.0.0.1:${port}/messages/\" --json\n```\n\n---\n\n## \ud83d\udc1e Troubleshooting\n\n* **\u201cMissing 'mcp' package\u201d** \u2014 Install the optional extra: `pip install \"matrix-cli[mcp]\"` (and `pip install websockets` for WS).\n* **TLS / certificate errors** \u2014 Set `SSL_CERT_FILE` or `REQUESTS_CA_BUNDLE` to your CA bundle.\n* **Alias not found when probing** \u2014 Use the alias shown by `matrix ps` (case-insensitive), or pass `--url` directly.\n* **Connector mode shows PID=0** \u2014 Expected in attach mode; ensure the remote server is running.\n\n---\n\n## \ud83d\udee0\ufe0f Development\n\n```bash\n# Create venv and install (editable) with useful extras\npython3.11 -m venv .venv\nsource .venv/bin/activate\npip install -U pip\npip install -e \".[dev,mcp]\"\n\n# Common tasks\nmake lint # ruff/flake8\nmake fmt # black\nmake typecheck # mypy\nmake test # pytest\nmake build # sdist + wheel\n```\n\n---\n\n## \ud83c\udf0d About MatrixHub\n\nMatrixHub aims to be the **pip of agents & MCP servers** \u2014 a secure, open, and developer-friendly registry and runtime that scales from personal laptops to global enterprises. If you\u2019re building agents, tools, or MCP services, Matrix CLI gets you from idea to running in seconds.\n\n---\n\n## \ud83d\udcc4 License\n\nApache License 2.0\n\n---\n\n## \u2709\ufe0f Feedback\n\nIssues and PRs welcome! If you hit rough edges with install/probing/health, the new **connector** flow, or `ps --plain/--json` and `uninstall`, please open an issue with your command, output, and environment.\n\n* GitHub: [https://github.com/agent-matrix/matrix-cli](https://github.com/agent-matrix/matrix-cli)\n* PyPI: [https://pypi.org/project/matrix-cli/](https://pypi.org/project/matrix-cli/)\n",
"bugtrack_url": null,
"license": null,
"summary": "Matrix CLI \u2014 thin UX layer over matrix-python-sdk (deep links, local builder, runtime)",
"version": "0.1.7",
"project_urls": {
"Documentation": "https://agent-matrix.github.io/matrix-cli/",
"Homepage": "https://matrixhub.io",
"Repository": "https://github.com/agent-matrix/matrix-cli"
},
"split_keywords": [
"matrix",
" mcp",
" model context protocol",
" cli",
" agents",
" tools",
" runtime",
" search",
" installer"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "fc03f4c1502d7de578db1fa3d9cea544bc31ae3c8d024cc21955deb850676b4e",
"md5": "fb61d6f1843f5831d384999e744e036e",
"sha256": "7a752d8139eb31ec5333f4ca27b878f8d9722a852b7228247ca37f3cd946fa24"
},
"downloads": -1,
"filename": "matrix_cli-0.1.7-py3-none-any.whl",
"has_sig": false,
"md5_digest": "fb61d6f1843f5831d384999e744e036e",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.11",
"size": 85000,
"upload_time": "2025-09-12T10:34:22",
"upload_time_iso_8601": "2025-09-12T10:34:22.345210Z",
"url": "https://files.pythonhosted.org/packages/fc/03/f4c1502d7de578db1fa3d9cea544bc31ae3c8d024cc21955deb850676b4e/matrix_cli-0.1.7-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "cda0355f5f0a10c89050dff0ddde186fbf902cb6628b9b053aed0be430354abe",
"md5": "bb9c0463c0e93c34c66a5c59aabf5d2a",
"sha256": "88ede6b8b236c756d2012246bcf2d9017b2ffb7301e045f2d9145c6e6d3e6160"
},
"downloads": -1,
"filename": "matrix_cli-0.1.7.tar.gz",
"has_sig": false,
"md5_digest": "bb9c0463c0e93c34c66a5c59aabf5d2a",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.11",
"size": 83319,
"upload_time": "2025-09-12T10:34:24",
"upload_time_iso_8601": "2025-09-12T10:34:24.117247Z",
"url": "https://files.pythonhosted.org/packages/cd/a0/355f5f0a10c89050dff0ddde186fbf902cb6628b9b053aed0be430354abe/matrix_cli-0.1.7.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-12 10:34:24",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "agent-matrix",
"github_project": "matrix-cli",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "matrix-cli"
}
JSON
