# Matrix CLI
**Official command-line interface for Matrix Hub**
Search, inspect, install agents/tools, and manage catalog remotes — plus an interactive **Matrix Shell** REPL.
---
## ✨ Features
- **Interactive Matrix Shell (REPL)** with history, completions, and built-in commands.
- **Options at the group level**: `--version`, `--rain/--no-rain`, `--no-repl`.
- **Session-wide rain toggle**: turn the Matrix rain on/off at startup or dynamically inside the REPL.
- **Polished UX**:
- `help` does **not** clear the screen.
- `matrix exit`, `exit`, `quit`, `close` all exit cleanly.
- Typing a redundant `matrix` token in the REPL is accepted.
- Robust autocompletion even when options are typed first (e.g., `--no-rain`).
---
## 🔧 Installation
```bash
# Via pipx (recommended)
pipx install matrix-cli
# Or via pip
pip install matrix-cli
```
> **Requires** Python 3.11+.
---
## ⚙️ Configuration
By default, Matrix CLI reads `~/.matrix/config.toml`.
Create a minimal config:
```toml
# ~/.matrix/config.toml
[registry]
base_url = "http://localhost:7300"
token = "YOUR_MATRIX_TOKEN" # optional
[gateway]
base_url = "http://localhost:7200"
token = "YOUR_GATEWAY_TOKEN" # optional
[cache]
dir = "~/.cache/matrix"
ttl_seconds = 14400 # 4 hours
```
You can override per command:
```bash
matrix --base-url http://hub.example.com search "summarize pdfs"
```
Or via environment variables:
```bash
export MATRIX_BASE_URL=http://hub.example.com
export MATRIX_TOKEN=...
export MATRIX_EXTRA_CATALOGS="https://example.com/cat1.json,https://example.com/cat2.json"
export MCP_GATEWAY_URL=http://gateway.example.com
export MCP_GATEWAY_TOKEN=...
export MATRIX_CACHE_DIR=~/.cache/matrix
export MATRIX_CACHE_TTL=14400
```
---
## 🚀 Quick Start
### One-shot (non-interactive) usage
```bash
# Version
matrix --version
# Show help for top level
matrix --help
# Disable REPL after running a command
matrix --no-repl --help
```
### Interactive Matrix Shell (REPL)
Just run:
```bash
matrix
```
Inside the shell:
* `help` or `matrix help` → show commands and usage (no screen clear).
* `help <command>` → detailed help for a specific command.
* `clear` or `matrix clear` → clear the screen.
* `--no-rain` / `--rain` → toggle Matrix rain **for the current session**.
* `exit`, `quit`, `close`, or `matrix exit` → exit the shell.
You can also pass options on entry:
```bash
# Start without the rain animation
matrix --no-rain
# Print help then exit (do not enter REPL)
matrix --no-repl --help
```
> The REPL accepts a redundant leading `matrix` token, so `matrix help`, `matrix exit`, etc. work as expected.
---
## 🧭 Common Commands
### Health / Info
```bash
matrix --version
matrix --help
```
### Search
```bash
matrix search "summarize pdfs" \
--type agent \
--capabilities pdf,summarize \
--frameworks langgraph \
--mode hybrid \
--limit 10
```
### Show Details
```bash
# id can be type:name@version or type:name with --version
matrix show agent:pdf-summarizer@1.4.2 [--json]
```
Renders name, version, type, summary, capabilities, endpoints, artifacts, adapters.
### Install
```bash
matrix install agent:pdf-summarizer@1.4.2 \
--target ./apps/pdf-bot
```
Writes adapters, registers with MCP-Gateway, and produces `matrix.lock.json`.
### List Entities
```bash
# From Matrix Hub index
matrix list --type tool --source hub
# From MCP-Gateway
matrix list --type tool --source gateway
```
### Manage Catalog Remotes
```bash
# List
matrix remotes list
# Add
matrix remotes add https://raw.githubusercontent.com/agent-matrix/catalog/main/index.json \
--name official
# Trigger ingest
matrix remotes ingest official
```
---
## 🧩 Options (Top-Level Group)
These options apply both at startup and **inside** the REPL:
* `--version`
Print the installed `matrix-cli` version and exit.
* `--rain / --no-rain`
Enable/disable the Matrix rain animation. Inside the REPL this toggles the session state.
* `--no-repl`
Run the requested action (e.g., `--help`) and exit **without** entering the REPL.
* `--help`
Show top-level help.
---
## 💡 Tips & Troubleshooting
* If you type `matrix --no-rain` **inside** the REPL, the animation toggles for the rest of the session; the shell does **not** restart or clear your screen.
* `help` in the REPL never clears the screen (use `clear` if you want a fresh view).
* Autocompletion is resilient even when you start with options (e.g., `--no-rain` first).
* If you installed with `pipx`, ensure your shell is picking up the `pipx` bin path.
---
## 📚 Documentation
Full user and developer docs live in the `docs/` folder.
Preview locally:
```bash
pip install mkdocs mkdocs-material
mkdocs serve
```
Open `http://127.0.0.1:8000/`.
---
## 🛠️ Development
```bash
# clone & setup venv
git clone https://github.com/agent-matrix/matrix-cli.git
cd matrix-cli
python -m venv .venv && source .venv/bin/activate
# install dev deps
pip install -e ".[dev]"
# lint & format
ruff check .
black .
# run tests
pytest
```
---
## 📄 License
Apache-2.0 © agent-matrix
Raw data
{
"_id": null,
"home_page": null,
"name": "matrix-cli",
"maintainer": null,
"docs_url": null,
"requires_python": "<3.13,>=3.11",
"maintainer_email": null,
"keywords": "matrix, ai, agents, tools, cli, mcp, hub",
"author": null,
"author_email": "agent-matrix <contact@ruslanmv.com>",
"download_url": "https://files.pythonhosted.org/packages/53/2f/3d7bf3772a09a80bcf7ed32afa3ea716eb14c61273d187fe418f2c0d3962/matrix_cli-0.1.0.tar.gz",
"platform": null,
"description": "\n\n# Matrix CLI\n\n**Official command-line interface for Matrix Hub** \nSearch, inspect, install agents/tools, and manage catalog remotes \u2014 plus an interactive **Matrix Shell** REPL.\n\n---\n\n## \u2728 Features\n\n- **Interactive Matrix Shell (REPL)** with history, completions, and built-in commands.\n- **Options at the group level**: `--version`, `--rain/--no-rain`, `--no-repl`.\n- **Session-wide rain toggle**: turn the Matrix rain on/off at startup or dynamically inside the REPL.\n- **Polished UX**:\n - `help` does **not** clear the screen.\n - `matrix exit`, `exit`, `quit`, `close` all exit cleanly.\n - Typing a redundant `matrix` token in the REPL is accepted.\n - Robust autocompletion even when options are typed first (e.g., `--no-rain`).\n\n---\n\n## \ud83d\udd27 Installation\n\n```bash\n# Via pipx (recommended)\npipx install matrix-cli\n\n# Or via pip\npip install matrix-cli\n```\n\n> **Requires** Python 3.11+.\n\n---\n\n## \u2699\ufe0f Configuration\n\nBy default, Matrix CLI reads `~/.matrix/config.toml`.\n\nCreate a minimal config:\n\n```toml\n# ~/.matrix/config.toml\n\n[registry]\nbase_url = \"http://localhost:7300\"\ntoken = \"YOUR_MATRIX_TOKEN\" # optional\n\n[gateway]\nbase_url = \"http://localhost:7200\"\ntoken = \"YOUR_GATEWAY_TOKEN\" # optional\n\n[cache]\ndir = \"~/.cache/matrix\"\nttl_seconds = 14400 # 4 hours\n```\n\nYou can override per command:\n\n```bash\nmatrix --base-url http://hub.example.com search \"summarize pdfs\"\n```\n\nOr via environment variables:\n\n```bash\nexport MATRIX_BASE_URL=http://hub.example.com\nexport MATRIX_TOKEN=...\nexport MATRIX_EXTRA_CATALOGS=\"https://example.com/cat1.json,https://example.com/cat2.json\"\n\nexport MCP_GATEWAY_URL=http://gateway.example.com\nexport MCP_GATEWAY_TOKEN=...\n\nexport MATRIX_CACHE_DIR=~/.cache/matrix\nexport MATRIX_CACHE_TTL=14400\n```\n\n---\n\n## \ud83d\ude80 Quick Start\n\n### One-shot (non-interactive) usage\n\n```bash\n# Version\nmatrix --version\n\n# Show help for top level\nmatrix --help\n\n# Disable REPL after running a command\nmatrix --no-repl --help\n```\n\n### Interactive Matrix Shell (REPL)\n\nJust run:\n\n```bash\nmatrix\n```\n\nInside the shell:\n\n* `help` or `matrix help` \u2192 show commands and usage (no screen clear).\n* `help <command>` \u2192 detailed help for a specific command.\n* `clear` or `matrix clear` \u2192 clear the screen.\n* `--no-rain` / `--rain` \u2192 toggle Matrix rain **for the current session**.\n* `exit`, `quit`, `close`, or `matrix exit` \u2192 exit the shell.\n\nYou can also pass options on entry:\n\n```bash\n# Start without the rain animation\nmatrix --no-rain\n\n# Print help then exit (do not enter REPL)\nmatrix --no-repl --help\n```\n\n> The REPL accepts a redundant leading `matrix` token, so `matrix help`, `matrix exit`, etc. work as expected.\n\n---\n\n## \ud83e\udded Common Commands\n\n### Health / Info\n\n```bash\nmatrix --version\nmatrix --help\n```\n\n### Search\n\n```bash\nmatrix search \"summarize pdfs\" \\\n --type agent \\\n --capabilities pdf,summarize \\\n --frameworks langgraph \\\n --mode hybrid \\\n --limit 10\n```\n\n### Show Details\n\n```bash\n# id can be type:name@version or type:name with --version\nmatrix show agent:pdf-summarizer@1.4.2 [--json]\n```\n\nRenders name, version, type, summary, capabilities, endpoints, artifacts, adapters.\n\n### Install\n\n```bash\nmatrix install agent:pdf-summarizer@1.4.2 \\\n --target ./apps/pdf-bot\n```\n\nWrites adapters, registers with MCP-Gateway, and produces `matrix.lock.json`.\n\n### List Entities\n\n```bash\n# From Matrix Hub index\nmatrix list --type tool --source hub\n\n# From MCP-Gateway\nmatrix list --type tool --source gateway\n```\n\n### Manage Catalog Remotes\n\n```bash\n# List\nmatrix remotes list\n\n# Add\nmatrix remotes add https://raw.githubusercontent.com/agent-matrix/catalog/main/index.json \\\n --name official\n\n# Trigger ingest\nmatrix remotes ingest official\n```\n\n---\n\n## \ud83e\udde9 Options (Top-Level Group)\n\nThese options apply both at startup and **inside** the REPL:\n\n* `--version`\n Print the installed `matrix-cli` version and exit.\n* `--rain / --no-rain`\n Enable/disable the Matrix rain animation. Inside the REPL this toggles the session state.\n* `--no-repl`\n Run the requested action (e.g., `--help`) and exit **without** entering the REPL.\n* `--help`\n Show top-level help.\n\n---\n\n## \ud83d\udca1 Tips & Troubleshooting\n\n* If you type `matrix --no-rain` **inside** the REPL, the animation toggles for the rest of the session; the shell does **not** restart or clear your screen.\n* `help` in the REPL never clears the screen (use `clear` if you want a fresh view).\n* Autocompletion is resilient even when you start with options (e.g., `--no-rain` first).\n* If you installed with `pipx`, ensure your shell is picking up the `pipx` bin path.\n\n---\n\n## \ud83d\udcda Documentation\n\nFull user and developer docs live in the `docs/` folder.\n\nPreview locally:\n\n```bash\npip install mkdocs mkdocs-material\nmkdocs serve\n```\n\nOpen `http://127.0.0.1:8000/`.\n\n---\n\n## \ud83d\udee0\ufe0f Development\n\n```bash\n# clone & setup venv\ngit clone https://github.com/agent-matrix/matrix-cli.git\ncd matrix-cli\npython -m venv .venv && source .venv/bin/activate\n\n# install dev deps\npip install -e \".[dev]\"\n\n# lint & format\nruff check .\nblack .\n\n# run tests\npytest\n```\n\n---\n\n## \ud83d\udcc4 License\n\nApache-2.0 \u00a9 agent-matrix\n\n",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "Official CLI for Matrix Hub",
"version": "0.1.0",
"project_urls": {
"Documentation": "https://agent-matrix.github.io/matrix-cli/",
"Homepage": "https://github.com/agent-matrix/matrix-cli",
"Issues": "https://github.com/agent-matrix/matrix-cli/issues",
"Repository": "https://github.com/agent-matrix/matrix-cli"
},
"split_keywords": [
"matrix",
" ai",
" agents",
" tools",
" cli",
" mcp",
" hub"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "bd3c6d7fbcdee73d14c56ec86d25f3a70873d90cfb30665a672937516cb1ca64",
"md5": "5d05698113e108c45639db11dc5b1be7",
"sha256": "50dd63bc3c07ec4f152e4eb82b9519fac305aa19ee4857b9d73712e6141d79b3"
},
"downloads": -1,
"filename": "matrix_cli-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "5d05698113e108c45639db11dc5b1be7",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<3.13,>=3.11",
"size": 21608,
"upload_time": "2025-08-01T17:34:15",
"upload_time_iso_8601": "2025-08-01T17:34:15.053812Z",
"url": "https://files.pythonhosted.org/packages/bd/3c/6d7fbcdee73d14c56ec86d25f3a70873d90cfb30665a672937516cb1ca64/matrix_cli-0.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "532f3d7bf3772a09a80bcf7ed32afa3ea716eb14c61273d187fe418f2c0d3962",
"md5": "d06fa04e3ac4e25e9be2b5114c0a0fde",
"sha256": "c3ccf3b59570369dcccf8efff4bda3e9f61db9f57cde4caf96d2244ac77b9026"
},
"downloads": -1,
"filename": "matrix_cli-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "d06fa04e3ac4e25e9be2b5114c0a0fde",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<3.13,>=3.11",
"size": 20328,
"upload_time": "2025-08-01T17:34:16",
"upload_time_iso_8601": "2025-08-01T17:34:16.851667Z",
"url": "https://files.pythonhosted.org/packages/53/2f/3d7bf3772a09a80bcf7ed32afa3ea716eb14c61273d187fe418f2c0d3962/matrix_cli-0.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-01 17:34:16",
"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
