getbased-agent-stack 0.3.1__tar.gz → 0.4.1__tar.gz

{getbased_agent_stack-0.3.1/src/getbased_agent_stack.egg-info → getbased_agent_stack-0.4.1}/PKG-INFO

@@ -1,16 +1,16 @@
 Metadata-Version: 2.4
 Name: getbased-agent-stack
-Version: 0.3.1
+Version: 0.4.1
 Summary: One-command install of the full getbased agent stack — getbased-mcp + getbased-rag + getbased-dashboard
 License-Expression: GPL-3.0-only
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: getbased-mcp>=0.2.2
-Requires-Dist: getbased-rag>=0.7.0
-Requires-Dist: getbased-dashboard>=0.6.0
+Requires-Dist: getbased-mcp>=0.2.3
+Requires-Dist: getbased-rag>=0.7.1
+Requires-Dist: getbased-dashboard>=0.6.1
 Provides-Extra: full
-Requires-Dist: getbased-rag[full]>=0.7.0; extra == "full"
+Requires-Dist: getbased-rag[full]>=0.7.1; extra == "full"
 Provides-Extra: test
 Requires-Dist: pytest>=8.0; extra == "test"
 Requires-Dist: httpx>=0.27; extra == "test"
@@ -19,7 +19,7 @@ Dynamic: license-file
 
 # getbased-agent-stack
 
-Meta-package bundling the full [getbased](https://getbased.health) agent stack into one install: the MCP adapter, the RAG engine, the browser dashboard, a thin discovery CLI, a hardened systemd unit, and example configs for Claude Code + Hermes.
+Meta-package bundling the full [getbased](https://getbased.health) agent stack into one install: the MCP adapter, the RAG engine, the browser dashboard, an orchestration CLI (`init` / `install` / `mcp-config`), hardened systemd units for rag + dashboard, and paste-ready configs for Claude Desktop/Code, Cursor, Cline, and Hermes.
 
 Part of the [getbased-agents monorepo](https://github.com/elkimek/getbased-agents).
 
@@ -39,36 +39,65 @@ Pulls:
 
 Total install: ~500 MB (the ML deps dominate). Smaller installs available — `pipx install getbased-mcp` (10 MB, agent only), `pipx install "getbased-rag[full]"` (RAG only), `pipx install getbased-dashboard` (UI + MCP; pulls rag if you want the Knowledge tab working).
 
-## Quickstart
+## Quickstart — one command
 
 ```bash
-# 1. Start the RAG server — local Qdrant DB + MiniLM embedder
-lens serve                               # blocks; serves on 127.0.0.1:8322
-lens key                                 # prints the bearer token
+getbased-stack init
+```
+
+The wizard (~30 seconds):
+
+1. Prompts for your `GETBASED_TOKEN` (skip if you don't use sync)
+2. Generates a rag API key if one doesn't exist
+3. Writes `~/.config/getbased/env` (mode 0600) — the shared config file
+4. Installs systemd user units for rag + dashboard, enables them, starts them
+
+Then paste one line into your MCP client:
+
+```bash
+getbased-stack mcp-config claude-desktop   # or: claude-code, cursor, cline, hermes
+```
+
+The snippet carries only `GETBASED_STACK_MANAGED=1` in its env block. No secrets in client configs — every MCP spawn reads the shared env file and loads the token + rag URL + API key path from there.
+
+Open the dashboard:
+
+```
+http://127.0.0.1:8323
+```
+
+Login URL with bearer key:
+
+```bash
+getbased-dashboard login-url   # prints http://127.0.0.1:8323/?key=...
+```
+
+Upload docs, create libraries, manage sources, and test the MCP probe from the web UI. Rotate the sync token from the CLI (see below) or by editing `~/.config/getbased/env` directly.
 
-# 2. Start the dashboard in another terminal
-getbased-dashboard serve                 # serves on 127.0.0.1:8323
+### Surviving reboot on headless hosts
 
-# 3. Open http://127.0.0.1:8323 in your browser, paste the lens key
-#    Create libraries, drag-drop files to ingest (live chunks/sec pill),
-#    run the MCP Test button to verify your agent path
+User systemd services stop on logout. On a headless server (no GUI session), they won't come back at boot unless you enable linger once:
 
-# 4. Wire the MCP into your AI client
-#    The dashboard's MCP tab generates paste-ready config blocks for
-#    Claude Desktop, Claude Code, Cursor, Cline, and Hermes.
+```bash
+sudo loginctl enable-linger $USER
 ```
 
-Both the RAG server and the getbased PWA talk to the same `lens` instance — point the PWA at `http://127.0.0.1:8322` under **Settings → AI → Knowledge Base → External server** and the same corpus feeds the browser chat, the dashboard, and any MCP-connected agent.
+`getbased-stack init` prints this reminder when it detects a headless environment. On a laptop with a GUI login, linger is nice-to-have — services start when you log in.
 
-## Running as a systemd service
+### Other commands
 
 ```bash
-cp systemd/getbased-rag.service ~/.config/systemd/user/
-systemctl --user daemon-reload
-systemctl --user enable --now getbased-rag
+getbased-stack status          # env file, unit state, linger
+getbased-stack set GETBASED_TOKEN=new   # rotate the token
+getbased-stack install         # re-apply unit files after package upgrade
+getbased-stack uninstall       # stop + disable + remove units
 ```
 
-The unit is hardened (`ProtectSystem=strict`, `NoNewPrivileges`, `RestrictAddressFamilies`, etc.); run `systemd-analyze security getbased-rag` to see the score.
+### Migrating from an older install
+
+If you have a hand-rolled setup (standalone `lens-rag.service`, hermes-style `~/.hermes/config.yaml` with MCP env), **leave it alone** — `getbased-stack init` only writes new paths and installs new unit names (`getbased-rag.service`, `getbased-dashboard.service`), so it can coexist. The opt-in loader in every binary is gated on `GETBASED_STACK_MANAGED=1`; without that flag set, every binary behaves exactly as before.
+
+If you're running the existing Hermes VM deployment on this host, don't run `init` there. Your `~/.hermes/config.yaml` continues to supply env explicitly; nothing from this package touches it.
 
 ## Architecture
 
@@ -97,6 +126,7 @@ The dashboard is likewise stateless — it proxies rag for Knowledge operations,
 |---|---|---|---|---|
 | 0.1.x | ≥0.2.0 | ≥0.1.0 | — | v1 (multi-library) |
 | 0.2.x | ≥0.2.2 | ≥0.6.0 | ≥0.5.0 | v1 (+ streaming ingest, per-library models) |
+| 0.4.x | ≥0.2.3 | ≥0.7.1 | ≥0.6.1 | v1 (+ shared env file, `getbased-stack init`, systemd units) |
 
 Bump the meta's major when sibling protocols break; bump siblings freely for normal features.
 

{getbased_agent_stack-0.3.1 → getbased_agent_stack-0.4.1}/README.md

@@ -1,6 +1,6 @@
 # getbased-agent-stack
 
-Meta-package bundling the full [getbased](https://getbased.health) agent stack into one install: the MCP adapter, the RAG engine, the browser dashboard, a thin discovery CLI, a hardened systemd unit, and example configs for Claude Code + Hermes.
+Meta-package bundling the full [getbased](https://getbased.health) agent stack into one install: the MCP adapter, the RAG engine, the browser dashboard, an orchestration CLI (`init` / `install` / `mcp-config`), hardened systemd units for rag + dashboard, and paste-ready configs for Claude Desktop/Code, Cursor, Cline, and Hermes.
 
 Part of the [getbased-agents monorepo](https://github.com/elkimek/getbased-agents).
 
@@ -20,36 +20,65 @@ Pulls:
 
 Total install: ~500 MB (the ML deps dominate). Smaller installs available — `pipx install getbased-mcp` (10 MB, agent only), `pipx install "getbased-rag[full]"` (RAG only), `pipx install getbased-dashboard` (UI + MCP; pulls rag if you want the Knowledge tab working).
 
-## Quickstart
+## Quickstart — one command
 
 ```bash
-# 1. Start the RAG server — local Qdrant DB + MiniLM embedder
-lens serve                               # blocks; serves on 127.0.0.1:8322
-lens key                                 # prints the bearer token
+getbased-stack init
+```
+
+The wizard (~30 seconds):
+
+1. Prompts for your `GETBASED_TOKEN` (skip if you don't use sync)
+2. Generates a rag API key if one doesn't exist
+3. Writes `~/.config/getbased/env` (mode 0600) — the shared config file
+4. Installs systemd user units for rag + dashboard, enables them, starts them
+
+Then paste one line into your MCP client:
+
+```bash
+getbased-stack mcp-config claude-desktop   # or: claude-code, cursor, cline, hermes
+```
+
+The snippet carries only `GETBASED_STACK_MANAGED=1` in its env block. No secrets in client configs — every MCP spawn reads the shared env file and loads the token + rag URL + API key path from there.
+
+Open the dashboard:
+
+```
+http://127.0.0.1:8323
+```
+
+Login URL with bearer key:
+
+```bash
+getbased-dashboard login-url   # prints http://127.0.0.1:8323/?key=...
+```
+
+Upload docs, create libraries, manage sources, and test the MCP probe from the web UI. Rotate the sync token from the CLI (see below) or by editing `~/.config/getbased/env` directly.
 
-# 2. Start the dashboard in another terminal
-getbased-dashboard serve                 # serves on 127.0.0.1:8323
+### Surviving reboot on headless hosts
 
-# 3. Open http://127.0.0.1:8323 in your browser, paste the lens key
-#    Create libraries, drag-drop files to ingest (live chunks/sec pill),
-#    run the MCP Test button to verify your agent path
+User systemd services stop on logout. On a headless server (no GUI session), they won't come back at boot unless you enable linger once:
 
-# 4. Wire the MCP into your AI client
-#    The dashboard's MCP tab generates paste-ready config blocks for
-#    Claude Desktop, Claude Code, Cursor, Cline, and Hermes.
+```bash
+sudo loginctl enable-linger $USER
 ```
 
-Both the RAG server and the getbased PWA talk to the same `lens` instance — point the PWA at `http://127.0.0.1:8322` under **Settings → AI → Knowledge Base → External server** and the same corpus feeds the browser chat, the dashboard, and any MCP-connected agent.
+`getbased-stack init` prints this reminder when it detects a headless environment. On a laptop with a GUI login, linger is nice-to-have — services start when you log in.
 
-## Running as a systemd service
+### Other commands
 
 ```bash
-cp systemd/getbased-rag.service ~/.config/systemd/user/
-systemctl --user daemon-reload
-systemctl --user enable --now getbased-rag
+getbased-stack status          # env file, unit state, linger
+getbased-stack set GETBASED_TOKEN=new   # rotate the token
+getbased-stack install         # re-apply unit files after package upgrade
+getbased-stack uninstall       # stop + disable + remove units
 ```
 
-The unit is hardened (`ProtectSystem=strict`, `NoNewPrivileges`, `RestrictAddressFamilies`, etc.); run `systemd-analyze security getbased-rag` to see the score.
+### Migrating from an older install
+
+If you have a hand-rolled setup (standalone `lens-rag.service`, hermes-style `~/.hermes/config.yaml` with MCP env), **leave it alone** — `getbased-stack init` only writes new paths and installs new unit names (`getbased-rag.service`, `getbased-dashboard.service`), so it can coexist. The opt-in loader in every binary is gated on `GETBASED_STACK_MANAGED=1`; without that flag set, every binary behaves exactly as before.
+
+If you're running the existing Hermes VM deployment on this host, don't run `init` there. Your `~/.hermes/config.yaml` continues to supply env explicitly; nothing from this package touches it.
 
 ## Architecture
 
@@ -78,6 +107,7 @@ The dashboard is likewise stateless — it proxies rag for Knowledge operations,
 |---|---|---|---|---|
 | 0.1.x | ≥0.2.0 | ≥0.1.0 | — | v1 (multi-library) |
 | 0.2.x | ≥0.2.2 | ≥0.6.0 | ≥0.5.0 | v1 (+ streaming ingest, per-library models) |
+| 0.4.x | ≥0.2.3 | ≥0.7.1 | ≥0.6.1 | v1 (+ shared env file, `getbased-stack init`, systemd units) |
 
 Bump the meta's major when sibling protocols break; bump siblings freely for normal features.
 

{getbased_agent_stack-0.3.1 → getbased_agent_stack-0.4.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "getbased-agent-stack"
-version = "0.3.1"
+version = "0.4.1"
 description = "One-command install of the full getbased agent stack — getbased-mcp + getbased-rag + getbased-dashboard"
 readme = "README.md"
 license = "GPL-3.0-only"
@@ -12,15 +12,15 @@ requires-python = ">=3.10"
 # Pulls every sibling package. Bump this meta when a sibling protocol
 # bump requires coordinated release.
 dependencies = [
-    "getbased-mcp>=0.2.2",
-    "getbased-rag>=0.7.0",
-    "getbased-dashboard>=0.6.0",
+    "getbased-mcp>=0.2.3",
+    "getbased-rag>=0.7.1",
+    "getbased-dashboard>=0.6.1",
 ]
 
 [project.optional-dependencies]
 # `full` includes PDF/DOCX parsers and ONNX acceleration (pre-exported
 # weights — no PyTorch/transformers/optimum dance).
-full = ["getbased-rag[full]>=0.7.0"]
+full = ["getbased-rag[full]>=0.7.1"]
 # For contributors running the integration test harness.
 test = ["pytest>=8.0", "httpx>=0.27", "pytest-timeout>=2.3"]
 
@@ -36,6 +36,11 @@ getbased-stack = "getbased_agent_stack.cli:main"
 [tool.setuptools.packages.find]
 where = ["src"]
 
+[tool.setuptools.package-data]
+# Ship the user systemd unit files inside the wheel so
+# `getbased-stack install` can locate them via importlib.resources.
+getbased_agent_stack = ["systemd/*.service"]
+
 [tool.pytest.ini_options]
 testpaths = ["tests"]
 addopts = "-ra -q"

{getbased_agent_stack-0.3.1 → getbased_agent_stack-0.4.1}/src/getbased_agent_stack/__init__.py

@@ -5,4 +5,4 @@ plus a small CLI that proxies to the real binaries. Everything
 interesting lives in the sibling repos.
 """
 
-__version__ = "0.1.0"
+__version__ = "0.4.1"

getbased_agent_stack-0.4.1/src/getbased_agent_stack/cli.py

@@ -0,0 +1,366 @@
+"""getbased-stack — orchestration CLI.
+
+Subcommands:
+  init           — interactive one-time setup: token, API key, systemd units
+  install        — install/refresh the bundled systemd user units
+  uninstall      — stop, disable, and remove the systemd units
+  status         — show env file, units, and linger state
+  set KEY=VALUE  — upsert a single var in the shared env file
+  mcp-config CLIENT — print the MCP client config snippet
+  version        — print installed package versions
+  info / serve / everything else → delegate to the `lens` CLI
+
+Deliberate zero-dep: argparse + stdlib only. No typer, no click, no
+python-dotenv. The env file format is simple enough that we own it.
+"""
+from __future__ import annotations
+
+import argparse
+import os
+import secrets
+import shutil
+import sys
+from pathlib import Path
+
+from . import env_file, mcp_configs, units
+
+
+# ── helpers ───────────────────────────────────────────────────────────
+
+
+def _default_api_key_file() -> Path:
+    xdg = os.environ.get("XDG_DATA_HOME") or os.path.expanduser("~/.local/share")
+    return Path(xdg) / "getbased" / "lens" / "api_key"
+
+
+def _ensure_api_key(path: Path) -> str:
+    """Generate a key if missing; return the key text either way. Mode 0600."""
+    if path.exists():
+        return path.read_text(encoding="utf-8").strip()
+    path.parent.mkdir(parents=True, exist_ok=True)
+    key = secrets.token_urlsafe(32)
+    path.write_text(key + "\n", encoding="utf-8")
+    os.chmod(path, 0o600)
+    return key
+
+
+def _prompt(msg: str, default: str = "", secret: bool = False) -> str:
+    """Non-intrusive readline prompt. Treats EOF/Ctrl-D as 'use default'."""
+    suffix = f" [{default}]" if default else ""
+    try:
+        if secret:
+            import getpass
+
+            answer = getpass.getpass(f"{msg}{suffix}: ")
+        else:
+            answer = input(f"{msg}{suffix}: ")
+    except EOFError:
+        return default
+    return answer.strip() or default
+
+
+def _display_value(key: str, value: str) -> str:
+    """Mask only actual secrets (a variable NAMED token/key/secret/password).
+    Keys like LENS_API_KEY_FILE that hold a path, not a secret, show verbatim."""
+    upper = key.upper()
+    # Values that end with _FILE or _PATH are filesystem paths — show them.
+    if upper.endswith(("_FILE", "_PATH", "_DIR", "_HOME", "_URL")):
+        return value
+    if any(upper.endswith("_" + s) or upper == s for s in ("TOKEN", "KEY", "SECRET", "PASSWORD")):
+        return "****" + value[-4:] if len(value) > 4 else "****"
+    return value
+
+
+def _yesno(msg: str, default: bool = True) -> bool:
+    suffix = "[Y/n]" if default else "[y/N]"
+    try:
+        ans = input(f"{msg} {suffix}: ").strip().lower()
+    except EOFError:
+        return default
+    if not ans:
+        return default
+    return ans in ("y", "yes")
+
+
+# ── subcommand implementations ────────────────────────────────────────
+
+
+def cmd_init(args: argparse.Namespace) -> int:
+    print("getbased-stack init — one-time setup")
+    print(
+        "Writes ~/.config/getbased/env, (optionally) installs + starts systemd\n"
+        "user units for rag and dashboard. Idempotent: safe to re-run."
+    )
+    print()
+
+    # 1. token (optional)
+    existing = env_file.read_env_file()
+    current_token = existing.get("GETBASED_TOKEN", "")
+    masked = "****" + current_token[-4:] if current_token else "(unset)"
+    print(f"[1/4] getbased sync token (current: {masked})")
+    token = _prompt(
+        "Paste GETBASED_TOKEN (press Enter to keep current / skip)",
+        default=current_token,
+        secret=True,
+    )
+
+    # 2. API key
+    key_path = Path(existing.get("LENS_API_KEY_FILE", str(_default_api_key_file())))
+    print(f"\n[2/4] rag API key file ({key_path})")
+    if key_path.exists():
+        print("  existing key found — reusing (init is idempotent).")
+    else:
+        print("  no key found — one will be generated on first service start.")
+    key_value = _ensure_api_key(key_path)
+    print(f"  key ready (length {len(key_value)} chars, mode 0600)")
+
+    # 3. write env file
+    print("\n[3/4] writing ~/.config/getbased/env")
+    merged = {**existing}
+    merged["GETBASED_STACK_MANAGED"] = "1"
+    if token:
+        merged["GETBASED_TOKEN"] = token
+    merged["LENS_API_KEY_FILE"] = str(key_path)
+    merged.setdefault("LENS_URL", "http://127.0.0.1:8322")
+    path = env_file.write_env_file(merged)
+    print(f"  wrote {path} (mode 0600)")
+
+    # 4. install units
+    print("\n[4/4] install systemd user units?")
+    if _yesno("install + start getbased-rag + getbased-dashboard?", default=True):
+        mgr = units.UnitManager()
+        for line in mgr.install(enable=True, start=True):
+            print(f"  {line}")
+    else:
+        print("  skipped — run `getbased-stack install` later to enable.")
+
+    # 5. linger check
+    print("\n── Post-install ──")
+    _print_linger_hint(strict=False)
+
+    # 6. MCP config pointers
+    print("\nConfigure your MCP client(s):")
+    for client in mcp_configs.SUPPORTED_CLIENTS:
+        print(f"  getbased-stack mcp-config {client}")
+
+    return 0
+
+
+def _print_linger_hint(strict: bool) -> None:
+    user = os.environ.get("USER", "")
+    if not user:
+        return
+    try:
+        linger_on = units.has_linger(user)
+    except FileNotFoundError:
+        # loginctl not on PATH (uncommon but possible in minimal containers)
+        print("  loginctl not found — cannot check linger status.")
+        return
+    gui = units.is_gui_session()
+    if linger_on:
+        print("  linger: enabled ✓ (services will survive logout + reboot)")
+        return
+    # Not on.
+    if gui:
+        # Laptop with GUI login — user will be logged in when they use this,
+        # so linger is nice-to-have, not blocking.
+        print("  linger: off (fine for laptops; services only run while you're logged in)")
+        print(f"         enable with: sudo loginctl enable-linger {user}")
+        return
+    # Headless + no linger = services die on logout. This is the "silent
+    # breakage after reboot" failure mode.
+    print("  ⚠ linger: off AND no GUI session detected (headless).")
+    print(f"    Without linger, rag + dashboard will stop as soon as this SSH session ends.")
+    print(f"    Run this once, then re-enable with `systemctl --user start getbased-rag.service`:")
+    print(f"      sudo loginctl enable-linger {user}")
+
+
+def cmd_install(args: argparse.Namespace) -> int:
+    mgr = units.UnitManager()
+    for line in mgr.install(enable=not args.no_enable, start=not args.no_start):
+        print(line)
+    _print_linger_hint(strict=False)
+    return 0
+
+
+def cmd_uninstall(args: argparse.Namespace) -> int:
+    mgr = units.UnitManager()
+    for line in mgr.uninstall():
+        print(line)
+    if args.delete_env:
+        p = env_file.env_file_path()
+        if p.exists():
+            p.unlink()
+            print(f"removed {p}")
+    return 0
+
+
+def cmd_status(args: argparse.Namespace) -> int:
+    # env file
+    path = env_file.env_file_path()
+    if path.exists():
+        data = env_file.read_env_file(path)
+        keys = sorted(data.keys())
+        print(f"env file: {path}  ({len(keys)} keys)")
+        for k in keys:
+            print(f"  {k}={_display_value(k, data[k])}")
+    else:
+        print(f"env file: {path} (not present — run `getbased-stack init`)")
+
+    # systemd units
+    print("\nunits:")
+    mgr = units.UnitManager()
+    try:
+        for svc in mgr.status():
+            flags = []
+            flags.append("installed" if svc["installed"] else "not installed")
+            flags.append("enabled" if svc["enabled"] else "not enabled")
+            flags.append("active" if svc["active"] else "inactive")
+            print(f"  {svc['name']}: {', '.join(flags)}")
+    except FileNotFoundError:
+        print("  systemctl not found — cannot check unit status.")
+
+    # linger
+    print()
+    _print_linger_hint(strict=False)
+    return 0
+
+
+def cmd_set(args: argparse.Namespace) -> int:
+    if "=" not in args.assignment:
+        print("usage: getbased-stack set KEY=VALUE", file=sys.stderr)
+        return 2
+    key, _, value = args.assignment.partition("=")
+    key = key.strip()
+    value = value.strip()
+    path = env_file.set_env_var(key, value)
+    print(f"{key} updated in {path}")
+    # If rag/dashboard are running, they'll pick up the change on next
+    # restart — remind the user.
+    print("restart services to apply: systemctl --user restart getbased-rag getbased-dashboard")
+    return 0
+
+
+def cmd_mcp_config(args: argparse.Namespace) -> int:
+    try:
+        snippet = mcp_configs.emit(args.client)
+    except ValueError as e:
+        print(str(e), file=sys.stderr)
+        return 2
+    print(snippet, end="")
+    return 0
+
+
+def cmd_version(args: argparse.Namespace) -> int:
+    try:
+        import importlib.metadata as md
+
+        import getbased_agent_stack
+
+        print(f"getbased-agent-stack {getbased_agent_stack.__version__}")
+        for pkg in ("getbased-mcp", "getbased-rag", "getbased-dashboard"):
+            try:
+                print(f"  {pkg} {md.version(pkg)}")
+            except md.PackageNotFoundError:
+                print(f"  {pkg} (not installed)")
+        return 0
+    except ImportError as e:
+        print(f"Missing dependency: {e}", file=sys.stderr)
+        return 1
+
+
+def _delegate_to_lens(argv: "list[str]") -> int:
+    """Historical behavior: unknown subcommands fall through to `lens`
+    so the user can do `getbased-stack serve` / `info` / `ingest` without
+    needing to remember a separate binary."""
+    try:
+        from lens.cli import app as lens_app
+
+        sys.argv = ["lens"] + argv
+        try:
+            lens_app()
+            return 0
+        except SystemExit as e:
+            return int(e.code or 0)
+    except ImportError:
+        print(
+            "getbased-rag not installed — install with "
+            "`pipx install getbased-agent-stack[full]`",
+            file=sys.stderr,
+        )
+        return 1
+
+
+# ── argparse wiring ───────────────────────────────────────────────────
+
+
+def build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(
+        prog="getbased-stack",
+        description=(
+            "One-command orchestrator for the getbased agent stack. "
+            "Use `init` for first-time setup."
+        ),
+    )
+    sub = p.add_subparsers(dest="command")
+
+    sub.add_parser("init", help="Interactive one-time setup (token, API key, units).")
+
+    pi = sub.add_parser("install", help="Install + start the systemd user units.")
+    pi.add_argument("--no-enable", action="store_true", help="Copy files only; don't enable.")
+    pi.add_argument("--no-start", action="store_true", help="Enable but don't start now.")
+
+    pu = sub.add_parser("uninstall", help="Stop, disable, and remove the systemd units.")
+    pu.add_argument(
+        "--delete-env",
+        action="store_true",
+        help="Also delete ~/.config/getbased/env (keeps API key + data).",
+    )
+
+    sub.add_parser("status", help="Show env file, unit state, linger.")
+
+    ps = sub.add_parser("set", help="Upsert a single key in the shared env file.")
+    ps.add_argument("assignment", help="KEY=VALUE")
+
+    pm = sub.add_parser("mcp-config", help="Print an MCP client config snippet.")
+    pm.add_argument(
+        "client",
+        choices=mcp_configs.SUPPORTED_CLIENTS,
+        help="Which client to emit for.",
+    )
+
+    sub.add_parser("version", help="Print installed package versions.")
+
+    return p
+
+
+COMMANDS = {
+    "init": cmd_init,
+    "install": cmd_install,
+    "uninstall": cmd_uninstall,
+    "status": cmd_status,
+    "set": cmd_set,
+    "mcp-config": cmd_mcp_config,
+    "version": cmd_version,
+}
+
+
+def main(argv: "list[str] | None" = None) -> int:
+    argv = argv if argv is not None else sys.argv[1:]
+
+    # Fast path: no args → show our help, not lens's.
+    if not argv or argv[0] in ("-h", "--help", "help"):
+        build_parser().print_help()
+        return 0
+
+    # New commands take priority; everything else falls through to lens
+    # (preserves the old thin-wrapper behavior for `serve`, `info`, etc).
+    if argv[0] in COMMANDS:
+        args = build_parser().parse_args(argv)
+        return COMMANDS[args.command](args)
+
+    return _delegate_to_lens(argv)
+
+
+if __name__ == "__main__":
+    sys.exit(main())