feat: openmatrix CLI and one-command installer

Add full CLI with gateway management commands:
  openmatrix gateway start [-d]
  openmatrix gateway stop
  openmatrix gateway status
  openmatrix gateway restart
  openmatrix gateway logs [-f] [-n N]
  openmatrix setup / health / version / config

One-command install via curl:
  curl -sSL https://raw.githubusercontent.com/ItsDardanRexhepi/0pnMatrx/main/install.sh | bash

Registered 'openmatrix' as console_scripts entry point in pyproject.toml.
Updated start.sh to wrap the CLI with direct fallback.

Author: Neo

cli/__init__.py

@@ -0,0 +1,53 @@
+"""openmatrix CLI — command-line interface for 0pnMatrx."""
+
+import argparse
+import sys
+
+from cli.gateway import register_gateway_commands
+from cli.info import register_info_commands
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="openmatrix",
+        description="0pnMatrx — multi-agent crypto-native platform",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""\
+examples:
+  openmatrix gateway start          Start the gateway server
+  openmatrix gateway start -d       Start in background (daemon)
+  openmatrix gateway stop           Stop a running gateway
+  openmatrix gateway status         Check if gateway is running
+  openmatrix gateway restart        Restart the gateway
+  openmatrix gateway logs           Tail gateway logs
+  openmatrix setup                  Run interactive setup
+  openmatrix health                 Quick health check
+  openmatrix version                Show version
+""",
+    )
+
+    sub = parser.add_subparsers(dest="command", metavar="<command>")
+
+    register_gateway_commands(sub)
+    register_info_commands(sub)
+
+    return parser
+
+
+def main(argv: list[str] | None = None) -> None:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+
+    if not args.command:
+        parser.print_help()
+        sys.exit(0)
+
+    if hasattr(args, "func"):
+        try:
+            args.func(args)
+        except KeyboardInterrupt:
+            print("\nInterrupted.")
+            sys.exit(130)
+    else:
+        parser.print_help()
+        sys.exit(1)

cli/__main__.py

@@ -0,0 +1,5 @@
+"""Allow running the CLI with: python -m cli"""
+from cli import main
+
+if __name__ == "__main__":
+    main()

cli/gateway.py

@@ -0,0 +1,311 @@
+"""openmatrix gateway — start, stop, status, restart, logs."""
+
+import json
+import os
+import signal
+import subprocess
+import sys
+import time
+from pathlib import Path
+
+# ── Paths ────────────────────────────────────────────────────────────────────
+
+PROJECT_ROOT = Path(__file__).resolve().parent.parent
+PID_FILE = PROJECT_ROOT / "data" / "gateway.pid"
+LOG_FILE = PROJECT_ROOT / "data" / "gateway.log"
+CONFIG_FILE = PROJECT_ROOT / "openmatrix.config.json"
+
+# ── Colors ───────────────────────────────────────────────────────────────────
+
+BOLD = "\033[1m"
+CYAN = "\033[36m"
+GREEN = "\033[32m"
+RED = "\033[31m"
+YELLOW = "\033[33m"
+DIM = "\033[2m"
+NC = "\033[0m"
+
+
+def _info(msg: str) -> None:
+    print(f"{GREEN}[openmatrix]{NC} {msg}")
+
+
+def _warn(msg: str) -> None:
+    print(f"{YELLOW}[openmatrix]{NC} {msg}")
+
+
+def _error(msg: str) -> None:
+    print(f"{RED}[openmatrix]{NC} {msg}", file=sys.stderr)
+
+
+# ── PID management ───────────────────────────────────────────────────────────
+
+def _read_pid() -> int | None:
+    if not PID_FILE.exists():
+        return None
+    try:
+        pid = int(PID_FILE.read_text().strip())
+        # Check if process is actually alive
+        os.kill(pid, 0)
+        return pid
+    except (ValueError, ProcessLookupError, PermissionError):
+        PID_FILE.unlink(missing_ok=True)
+        return None
+
+
+def _write_pid(pid: int) -> None:
+    PID_FILE.parent.mkdir(parents=True, exist_ok=True)
+    PID_FILE.write_text(str(pid))
+
+
+def _remove_pid() -> None:
+    PID_FILE.unlink(missing_ok=True)
+
+
+# ── Config ───────────────────────────────────────────────────────────────────
+
+def _load_config() -> dict:
+    if not CONFIG_FILE.exists():
+        return {}
+    return json.loads(CONFIG_FILE.read_text())
+
+
+def _get_host_port() -> tuple[str, int]:
+    config = _load_config()
+    gw = config.get("gateway", {})
+    return gw.get("host", "0.0.0.0"), gw.get("port", 18790)
+
+
+# ── Commands ─────────────────────────────────────────────────────────────────
+
+def cmd_start(args) -> None:
+    """Start the gateway server."""
+    existing = _read_pid()
+    if existing:
+        _error(f"Gateway is already running (PID {existing}).")
+        _info(f"Use {CYAN}openmatrix gateway restart{NC} to restart it.")
+        sys.exit(1)
+
+    if not CONFIG_FILE.exists():
+        _warn("No configuration found.")
+        _info(f"Run {CYAN}openmatrix setup{NC} first, or create openmatrix.config.json")
+        sys.exit(1)
+
+    host, port = _get_host_port()
+
+    # Activate venv if present
+    venv_python = PROJECT_ROOT / ".venv" / "bin" / "python3"
+    python = str(venv_python) if venv_python.exists() else sys.executable
+
+    if args.daemon:
+        # Background mode
+        LOG_FILE.parent.mkdir(parents=True, exist_ok=True)
+        log_fd = open(LOG_FILE, "a")
+
+        proc = subprocess.Popen(
+            [python, "-m", "gateway.server"],
+            cwd=str(PROJECT_ROOT),
+            stdout=log_fd,
+            stderr=log_fd,
+            start_new_session=True,
+        )
+        _write_pid(proc.pid)
+
+        # Wait briefly to confirm it started
+        time.sleep(1.5)
+        if proc.poll() is not None:
+            _error("Gateway failed to start. Check logs:")
+            _info(f"  {CYAN}openmatrix gateway logs{NC}")
+            _remove_pid()
+            sys.exit(1)
+
+        print()
+        print(f"  {CYAN}{BOLD}0pnMatrx Gateway{NC}")
+        print(f"  {DIM}{'─' * 40}{NC}")
+        _info(f"Running in background (PID {proc.pid})")
+        _info(f"Listening on {BOLD}http://{host}:{port}{NC}")
+        _info(f"Logs: {LOG_FILE}")
+        print()
+        _info(f"Stop with:    {CYAN}openmatrix gateway stop{NC}")
+        _info(f"View logs:    {CYAN}openmatrix gateway logs{NC}")
+        _info(f"Check status: {CYAN}openmatrix gateway status{NC}")
+        print()
+    else:
+        # Foreground mode
+        print()
+        print(f"  {CYAN}{BOLD}┌──────────────────────────────────┐{NC}")
+        print(f"  {CYAN}{BOLD}│     0pnMatrx Gateway — Live      │{NC}")
+        print(f"  {CYAN}{BOLD}└──────────────────────────────────┘{NC}")
+        print()
+        _info(f"Listening on {BOLD}http://{host}:{port}{NC}")
+        _info("Press Ctrl+C to stop")
+        print()
+
+        try:
+            proc = subprocess.run(
+                [python, "-m", "gateway.server"],
+                cwd=str(PROJECT_ROOT),
+            )
+            sys.exit(proc.returncode)
+        except KeyboardInterrupt:
+            print()
+            _info("Gateway stopped.")
+
+
+def cmd_stop(args) -> None:
+    """Stop the gateway server."""
+    pid = _read_pid()
+    if not pid:
+        _warn("Gateway is not running.")
+        return
+
+    _info(f"Stopping gateway (PID {pid})...")
+
+    try:
+        os.kill(pid, signal.SIGTERM)
+
+        # Wait for graceful shutdown (up to 10 seconds)
+        for _ in range(20):
+            try:
+                os.kill(pid, 0)
+                time.sleep(0.5)
+            except ProcessLookupError:
+                break
+        else:
+            # Force kill if still running
+            _warn("Graceful shutdown timed out. Sending SIGKILL...")
+            try:
+                os.kill(pid, signal.SIGKILL)
+            except ProcessLookupError:
+                pass
+    except ProcessLookupError:
+        pass
+
+    _remove_pid()
+    _info("Gateway stopped.")
+
+
+def cmd_status(args) -> None:
+    """Check gateway status."""
+    pid = _read_pid()
+    host, port = _get_host_port()
+
+    if not pid:
+        print(f"  {RED}●{NC} Gateway is {RED}not running{NC}")
+        print()
+        _info(f"Start with: {CYAN}openmatrix gateway start{NC}")
+        return
+
+    print(f"  {GREEN}●{NC} Gateway is {GREEN}running{NC}")
+    print(f"  {DIM}PID:{NC}  {pid}")
+    print(f"  {DIM}URL:{NC}  http://{host}:{port}")
+
+    if LOG_FILE.exists():
+        size = LOG_FILE.stat().st_size
+        if size > 1024 * 1024:
+            print(f"  {DIM}Logs:{NC} {size / 1024 / 1024:.1f} MB")
+        else:
+            print(f"  {DIM}Logs:{NC} {size / 1024:.1f} KB")
+
+    # Try a health check
+    try:
+        import urllib.request
+        req = urllib.request.urlopen(f"http://localhost:{port}/health", timeout=3)
+        if req.status == 200:
+            data = json.loads(req.read())
+            uptime = data.get("uptime_seconds", 0)
+            hours = int(uptime // 3600)
+            mins = int((uptime % 3600) // 60)
+            print(f"  {DIM}Up:{NC}   {hours}h {mins}m")
+            print(f"  {GREEN}●{NC} Health: {GREEN}OK{NC}")
+        else:
+            print(f"  {YELLOW}●{NC} Health: responded with {req.status}")
+    except Exception:
+        print(f"  {YELLOW}●{NC} Health: could not reach /health endpoint")
+    print()
+
+
+def cmd_restart(args) -> None:
+    """Restart the gateway server."""
+    pid = _read_pid()
+    if pid:
+        _info("Stopping current instance...")
+        cmd_stop(args)
+        time.sleep(1)
+
+    args.daemon = True
+    cmd_start(args)
+
+
+def cmd_logs(args) -> None:
+    """Tail gateway logs."""
+    if not LOG_FILE.exists():
+        _warn("No log file found.")
+        _info("Gateway may not have been started in daemon mode.")
+        return
+
+    lines = args.lines or 50
+    follow = args.follow
+
+    if follow:
+        _info(f"Tailing {LOG_FILE} (Ctrl+C to stop)...")
+        try:
+            proc = subprocess.run(
+                ["tail", f"-n{lines}", "-f", str(LOG_FILE)],
+            )
+        except KeyboardInterrupt:
+            print()
+    else:
+        _info(f"Last {lines} lines from {LOG_FILE}:")
+        print()
+        subprocess.run(["tail", f"-n{lines}", str(LOG_FILE)])
+
+
+# ── Register ─────────────────────────────────────────────────────────────────
+
+def register_gateway_commands(subparsers) -> None:
+    gw = subparsers.add_parser(
+        "gateway",
+        help="Manage the gateway server",
+        description="Start, stop, and manage the 0pnMatrx gateway server.",
+    )
+    gw_sub = gw.add_subparsers(dest="gateway_command", metavar="<action>")
+
+    # start
+    start = gw_sub.add_parser("start", help="Start the gateway server")
+    start.add_argument(
+        "-d", "--daemon", action="store_true",
+        help="Run in background (daemon mode)",
+    )
+    start.add_argument(
+        "-p", "--port", type=int, default=None,
+        help="Override gateway port",
+    )
+    start.set_defaults(func=cmd_start)
+
+    # stop
+    stop = gw_sub.add_parser("stop", help="Stop the gateway server")
+    stop.set_defaults(func=cmd_stop)
+
+    # status
+    status = gw_sub.add_parser("status", help="Check gateway status")
+    status.set_defaults(func=cmd_status)
+
+    # restart
+    restart = gw_sub.add_parser("restart", help="Restart the gateway")
+    restart.set_defaults(func=cmd_restart)
+
+    # logs
+    logs = gw_sub.add_parser("logs", help="View gateway logs")
+    logs.add_argument(
+        "-n", "--lines", type=int, default=50,
+        help="Number of lines to show (default: 50)",
+    )
+    logs.add_argument(
+        "-f", "--follow", action="store_true",
+        help="Follow log output in real time",
+    )
+    logs.set_defaults(func=cmd_logs)
+
+    # If no subcommand given, show gateway help
+    gw.set_defaults(func=lambda a: gw.print_help())