payd-labs-sentinel-cli 0.3.0__tar.gz

payd_labs_sentinel_cli-0.3.0/.gitignore

@@ -0,0 +1,34 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.venv/
+venv/
+*.egg
+
+# Node
+node_modules/
+dist/
+
+# Environment
+.env
+.env.local
+.env.*.local
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Data
+*.db
+/data/
+
+# Docker
+docker-compose.override.yml

payd_labs_sentinel_cli-0.3.0/PKG-INFO

@@ -0,0 +1,210 @@
+Metadata-Version: 2.4
+Name: payd-labs-sentinel-cli
+Version: 0.3.0
+Summary: CLI and MCP server for the Sentinel DevOps portal - manage deployments, services, and projects
+Project-URL: Homepage, https://sentinel.paydlabs.com
+Project-URL: Repository, https://github.com/getpayd-tech/payd-labs-sentinel-v1
+Author-email: Payd Labs <dev@payd.money>
+License-Expression: MIT
+Keywords: cli,deployment,devops,docker,mcp
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Build Tools
+Classifier: Topic :: System :: Systems Administration
+Requires-Python: >=3.12
+Requires-Dist: httpx>=0.28.0
+Requires-Dist: mcp>=1.0.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: typer>=0.15.0
+Description-Content-Type: text/markdown
+
+# sentinel-cli
+
+CLI and MCP server for the [Sentinel](https://sentinel.paydlabs.com) DevOps portal. Manage deployments end-to-end from the terminal or via AI agents.
+
+## Install
+
+```bash
+python3.12 -m pip install payd-labs-sentinel-cli
+```
+
+Requires Python 3.12+.
+
+## Quick start
+
+```bash
+payd-sentinel login    # one-time OTP via Payd Auth, caches token at ~/.sentinel/
+
+# End-to-end bootstrap of a new service (one command):
+payd-sentinel bootstrap \
+  --name my-app --type fastapi --domain my-app.paydlabs.com \
+  --repo https://github.com/getpayd-tech/my-app \
+  --create-db \
+  --env SECRET_KEY="$(openssl rand -hex 32)" \
+  --env APP_ENV=production \
+  --deploy
+```
+
+Runs 7 steps: project create, env set, database create, Caddy route, server provision, write workflow to local git repo + set GitHub secret via `gh`, first deploy.
+
+## Command reference
+
+### Everyday ops
+
+```bash
+payd-sentinel status              # All projects + their latest deploy
+payd-sentinel projects            # List projects
+payd-sentinel services            # List containers
+payd-sentinel deploy <project>    # Trigger deploy
+payd-sentinel deploy <project> --tag v1.2.3
+payd-sentinel rollback <project> <deploy-id>
+payd-sentinel deployments [--project X]
+payd-sentinel logs <container> [--tail 100] [--since 1h]
+payd-sentinel restart|stop|start <container>
+payd-sentinel audit [--action X] [--limit 30]
+```
+
+`payd-sentinel deploy <project> --tag <sha>` is authoritative for Sentinel-generated
+single-container and blended projects, where the project `ghcr_image` maps to
+one image or the generated `-api` and `-ui` images. For parameterized custom
+multi-image compose stacks, put a shared `*IMAGE_TAG` variable in the compose
+`image:` lines, for example `CONNECT_IMAGE_TAG`; Sentinel updates that variable
+in the compose file directory's `.env` before `docker compose pull`. For custom
+edge/router stacks, set `--deploy-config` with image prefixes and the edge
+service so Sentinel can assert the live service/image map before reporting
+success.
+
+Example:
+
+```bash
+payd-sentinel project update payd-connect-v2-sandbox \
+  --deploy-config '{"compose_source":"webhook_bundle","image_tag_variables":["CONNECT_IMAGE_TAG"],"project_image_prefixes":["ghcr.io/getpayd-tech/payd-connect-v2-sandbox-"],"edge_service":"payd-connect-v2-sandbox"}'
+```
+
+### Projects
+
+```bash
+payd-sentinel project create <name> --type fastapi --domain X --repo URL
+payd-sentinel project show <name>
+payd-sentinel project update <name> --domain new --custom-domains
+payd-sentinel project delete <name>
+payd-sentinel project scan                     # Auto-discover /apps/
+payd-sentinel project provision <name>         # Write compose + .env + Caddy
+payd-sentinel project service-key <name>       # Generate API key for custom-domains API
+```
+
+### Environment variables
+
+```bash
+payd-sentinel env list <project> [--reveal]
+payd-sentinel env set <project> KEY=VAL KEY2=VAL2 ...
+payd-sentinel env unset <project> KEY1 KEY2
+```
+
+### Database (managed PostgreSQL)
+
+```bash
+payd-sentinel db list
+payd-sentinel db create <name> [--password PW]
+payd-sentinel db tables <db>
+payd-sentinel db query <db> "SELECT * FROM ..."
+```
+
+### Domains + TLS
+
+```bash
+payd-sentinel domain list
+payd-sentinel domain add <domain> --upstream container:port [--tls auto|cloudflare_dns|on_demand|off]
+payd-sentinel domain remove <domain>
+payd-sentinel domain reload
+payd-sentinel domain tls status|enable|disable
+payd-sentinel custom-domain list [--project X]
+payd-sentinel custom-domain remove <domain>
+```
+
+### Security (fail2ban + SSH auth log)
+
+```bash
+payd-sentinel security banned [--jail sshd]
+payd-sentinel security ban <ip> [--jail sshd]
+payd-sentinel security unban <ip> [--jail sshd]
+payd-sentinel security activity [--tail 50]
+payd-sentinel security auth [--tail 50] [--type success|failure|info]
+payd-sentinel security ip <ip>           # Full history (fail2ban + SSH)
+```
+
+### Repo setup (close the loop on new services)
+
+```bash
+# End-to-end (recommended for new services):
+payd-sentinel bootstrap --name X --type T --domain D --repo URL [...]
+
+# For existing Sentinel projects that need the workflow added to their repo:
+cd my-existing-repo
+payd-sentinel repo setup <project>
+#  -> fetches generated workflow YAML from Sentinel
+#  -> writes .github/workflows/deploy.yml
+#  -> runs `gh secret set SENTINEL_WEBHOOK_SECRET ...`
+#  -> commits + pushes
+# Flags: --no-secret, --no-commit, --message "msg"
+```
+
+### Interactive wizard
+
+```bash
+payd-sentinel init    # prompts for each field, runs the 9-step wizard
+```
+
+## Auth
+
+Run `payd-sentinel login` once. Tokens are cached at `~/.sentinel/credentials.json` with auto-refresh.
+
+Or set `SENTINEL_TOKEN` env var with a valid admin JWT to skip the login flow.
+
+Override the API URL: `SENTINEL_URL=http://localhost:8000 payd-sentinel projects`
+
+## MCP Server (for Claude Code / AI agents)
+
+The package includes an MCP server that exposes 30 tools for AI agents.
+
+Add to your Claude Code settings:
+
+```json
+{
+  "mcpServers": {
+    "sentinel": {
+      "command": "sentinel-mcp"
+    }
+  }
+}
+```
+
+### Available tools
+
+**Projects**: `sentinel_list_projects`, `sentinel_create_project`, `sentinel_update_project`, `sentinel_delete_project`, `sentinel_scan_projects`, `sentinel_provision_project`, `sentinel_project_status`, `sentinel_generate_service_key`, `sentinel_get_workflow`
+
+**Deployments**: `sentinel_list_deployments`, `sentinel_deploy`, `sentinel_rollback`
+
+**Services**: `sentinel_list_services`, `sentinel_restart_service`, `sentinel_stop_service`, `sentinel_start_service`, `sentinel_get_logs`
+
+**Env**: `sentinel_list_env`, `sentinel_set_env`, `sentinel_unset_env`
+
+**Database**: `sentinel_list_databases`, `sentinel_create_database`, `sentinel_list_tables`, `sentinel_db_query`
+
+**Domains**: `sentinel_list_domains`, `sentinel_add_domain`, `sentinel_remove_domain`, `sentinel_reload_caddy`, `sentinel_list_custom_domains`
+
+**Audit**: `sentinel_audit_log`
+
+The MCP server reads auth from `~/.sentinel/credentials.json` (run `payd-sentinel login` first) or `SENTINEL_TOKEN` env var.
+
+## What is Sentinel?
+
+Sentinel is a self-hosted DevOps portal for managing Docker container deployments behind Caddy reverse proxy. It provides webhook-based deploys, automatic health checks with rollback, custom domain management with on-demand TLS, fail2ban monitoring, and a web UI.
+
+[sentinel.paydlabs.com](https://sentinel.paydlabs.com) | [GitHub](https://github.com/getpayd-tech/payd-labs-sentinel-v1) | [Self-hosting guide](https://github.com/getpayd-tech/payd-labs-sentinel-v1/blob/main/SELFHOST.md)
+
+
+Legacy alias: `sentinel` remains available for backwards compatibility.

payd_labs_sentinel_cli-0.3.0/README.md

@@ -0,0 +1,187 @@
+# sentinel-cli
+
+CLI and MCP server for the [Sentinel](https://sentinel.paydlabs.com) DevOps portal. Manage deployments end-to-end from the terminal or via AI agents.
+
+## Install
+
+```bash
+python3.12 -m pip install payd-labs-sentinel-cli
+```
+
+Requires Python 3.12+.
+
+## Quick start
+
+```bash
+payd-sentinel login    # one-time OTP via Payd Auth, caches token at ~/.sentinel/
+
+# End-to-end bootstrap of a new service (one command):
+payd-sentinel bootstrap \
+  --name my-app --type fastapi --domain my-app.paydlabs.com \
+  --repo https://github.com/getpayd-tech/my-app \
+  --create-db \
+  --env SECRET_KEY="$(openssl rand -hex 32)" \
+  --env APP_ENV=production \
+  --deploy
+```
+
+Runs 7 steps: project create, env set, database create, Caddy route, server provision, write workflow to local git repo + set GitHub secret via `gh`, first deploy.
+
+## Command reference
+
+### Everyday ops
+
+```bash
+payd-sentinel status              # All projects + their latest deploy
+payd-sentinel projects            # List projects
+payd-sentinel services            # List containers
+payd-sentinel deploy <project>    # Trigger deploy
+payd-sentinel deploy <project> --tag v1.2.3
+payd-sentinel rollback <project> <deploy-id>
+payd-sentinel deployments [--project X]
+payd-sentinel logs <container> [--tail 100] [--since 1h]
+payd-sentinel restart|stop|start <container>
+payd-sentinel audit [--action X] [--limit 30]
+```
+
+`payd-sentinel deploy <project> --tag <sha>` is authoritative for Sentinel-generated
+single-container and blended projects, where the project `ghcr_image` maps to
+one image or the generated `-api` and `-ui` images. For parameterized custom
+multi-image compose stacks, put a shared `*IMAGE_TAG` variable in the compose
+`image:` lines, for example `CONNECT_IMAGE_TAG`; Sentinel updates that variable
+in the compose file directory's `.env` before `docker compose pull`. For custom
+edge/router stacks, set `--deploy-config` with image prefixes and the edge
+service so Sentinel can assert the live service/image map before reporting
+success.
+
+Example:
+
+```bash
+payd-sentinel project update payd-connect-v2-sandbox \
+  --deploy-config '{"compose_source":"webhook_bundle","image_tag_variables":["CONNECT_IMAGE_TAG"],"project_image_prefixes":["ghcr.io/getpayd-tech/payd-connect-v2-sandbox-"],"edge_service":"payd-connect-v2-sandbox"}'
+```
+
+### Projects
+
+```bash
+payd-sentinel project create <name> --type fastapi --domain X --repo URL
+payd-sentinel project show <name>
+payd-sentinel project update <name> --domain new --custom-domains
+payd-sentinel project delete <name>
+payd-sentinel project scan                     # Auto-discover /apps/
+payd-sentinel project provision <name>         # Write compose + .env + Caddy
+payd-sentinel project service-key <name>       # Generate API key for custom-domains API
+```
+
+### Environment variables
+
+```bash
+payd-sentinel env list <project> [--reveal]
+payd-sentinel env set <project> KEY=VAL KEY2=VAL2 ...
+payd-sentinel env unset <project> KEY1 KEY2
+```
+
+### Database (managed PostgreSQL)
+
+```bash
+payd-sentinel db list
+payd-sentinel db create <name> [--password PW]
+payd-sentinel db tables <db>
+payd-sentinel db query <db> "SELECT * FROM ..."
+```
+
+### Domains + TLS
+
+```bash
+payd-sentinel domain list
+payd-sentinel domain add <domain> --upstream container:port [--tls auto|cloudflare_dns|on_demand|off]
+payd-sentinel domain remove <domain>
+payd-sentinel domain reload
+payd-sentinel domain tls status|enable|disable
+payd-sentinel custom-domain list [--project X]
+payd-sentinel custom-domain remove <domain>
+```
+
+### Security (fail2ban + SSH auth log)
+
+```bash
+payd-sentinel security banned [--jail sshd]
+payd-sentinel security ban <ip> [--jail sshd]
+payd-sentinel security unban <ip> [--jail sshd]
+payd-sentinel security activity [--tail 50]
+payd-sentinel security auth [--tail 50] [--type success|failure|info]
+payd-sentinel security ip <ip>           # Full history (fail2ban + SSH)
+```
+
+### Repo setup (close the loop on new services)
+
+```bash
+# End-to-end (recommended for new services):
+payd-sentinel bootstrap --name X --type T --domain D --repo URL [...]
+
+# For existing Sentinel projects that need the workflow added to their repo:
+cd my-existing-repo
+payd-sentinel repo setup <project>
+#  -> fetches generated workflow YAML from Sentinel
+#  -> writes .github/workflows/deploy.yml
+#  -> runs `gh secret set SENTINEL_WEBHOOK_SECRET ...`
+#  -> commits + pushes
+# Flags: --no-secret, --no-commit, --message "msg"
+```
+
+### Interactive wizard
+
+```bash
+payd-sentinel init    # prompts for each field, runs the 9-step wizard
+```
+
+## Auth
+
+Run `payd-sentinel login` once. Tokens are cached at `~/.sentinel/credentials.json` with auto-refresh.
+
+Or set `SENTINEL_TOKEN` env var with a valid admin JWT to skip the login flow.
+
+Override the API URL: `SENTINEL_URL=http://localhost:8000 payd-sentinel projects`
+
+## MCP Server (for Claude Code / AI agents)
+
+The package includes an MCP server that exposes 30 tools for AI agents.
+
+Add to your Claude Code settings:
+
+```json
+{
+  "mcpServers": {
+    "sentinel": {
+      "command": "sentinel-mcp"
+    }
+  }
+}
+```
+
+### Available tools
+
+**Projects**: `sentinel_list_projects`, `sentinel_create_project`, `sentinel_update_project`, `sentinel_delete_project`, `sentinel_scan_projects`, `sentinel_provision_project`, `sentinel_project_status`, `sentinel_generate_service_key`, `sentinel_get_workflow`
+
+**Deployments**: `sentinel_list_deployments`, `sentinel_deploy`, `sentinel_rollback`
+
+**Services**: `sentinel_list_services`, `sentinel_restart_service`, `sentinel_stop_service`, `sentinel_start_service`, `sentinel_get_logs`
+
+**Env**: `sentinel_list_env`, `sentinel_set_env`, `sentinel_unset_env`
+
+**Database**: `sentinel_list_databases`, `sentinel_create_database`, `sentinel_list_tables`, `sentinel_db_query`
+
+**Domains**: `sentinel_list_domains`, `sentinel_add_domain`, `sentinel_remove_domain`, `sentinel_reload_caddy`, `sentinel_list_custom_domains`
+
+**Audit**: `sentinel_audit_log`
+
+The MCP server reads auth from `~/.sentinel/credentials.json` (run `payd-sentinel login` first) or `SENTINEL_TOKEN` env var.
+
+## What is Sentinel?
+
+Sentinel is a self-hosted DevOps portal for managing Docker container deployments behind Caddy reverse proxy. It provides webhook-based deploys, automatic health checks with rollback, custom domain management with on-demand TLS, fail2ban monitoring, and a web UI.
+
+[sentinel.paydlabs.com](https://sentinel.paydlabs.com) | [GitHub](https://github.com/getpayd-tech/payd-labs-sentinel-v1) | [Self-hosting guide](https://github.com/getpayd-tech/payd-labs-sentinel-v1/blob/main/SELFHOST.md)
+
+
+Legacy alias: `sentinel` remains available for backwards compatibility.

payd_labs_sentinel_cli-0.3.0/pyproject.toml

@@ -0,0 +1,42 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "payd-labs-sentinel-cli"
+version = "0.3.0"
+description = "CLI and MCP server for the Sentinel DevOps portal - manage deployments, services, and projects"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.12"
+authors = [
+    { name = "Payd Labs", email = "dev@payd.money" },
+]
+keywords = ["devops", "deployment", "docker", "mcp", "cli"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Topic :: Software Development :: Build Tools",
+    "Topic :: System :: Systems Administration",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+]
+dependencies = [
+    "typer>=0.15.0",
+    "httpx>=0.28.0",
+    "rich>=13.0.0",
+    "mcp>=1.0.0",
+]
+
+[project.urls]
+Homepage = "https://sentinel.paydlabs.com"
+Repository = "https://github.com/getpayd-tech/payd-labs-sentinel-v1"
+
+[project.scripts]
+sentinel = "sentinel_cli.cli:app"
+payd-sentinel = "sentinel_cli.cli:app"
+sentinel-mcp = "sentinel_cli.mcp_server:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["sentinel_cli"]

payd_labs_sentinel_cli-0.3.0/sentinel_cli/__init__.py

@@ -0,0 +1 @@
+"""Sentinel CLI and MCP server."""

payd_labs_sentinel_cli-0.3.0/sentinel_cli/auth.py

@@ -0,0 +1,168 @@
+"""Authentication - OTP login, token caching, and auto-refresh."""
+from __future__ import annotations
+
+import base64
+import json
+import logging
+import os
+import time
+
+import httpx
+from rich.console import Console
+from rich.prompt import Prompt
+
+from sentinel_cli.config import CREDENTIALS_DIR, CREDENTIALS_FILE
+
+logger = logging.getLogger(__name__)
+console = Console()
+
+
+def _decode_jwt_payload(token: str) -> dict:
+    """Decode the payload segment of a JWT without signature verification."""
+    parts = token.split(".")
+    if len(parts) != 3:
+        raise ValueError("Invalid JWT format")
+    payload = parts[1]
+    payload += "=" * (4 - len(payload) % 4)
+    return json.loads(base64.urlsafe_b64decode(payload))
+
+
+def save_credentials(auth_token: str, refresh_token: str) -> None:
+    """Persist tokens to ~/.sentinel/credentials.json with restricted permissions."""
+    claims = _decode_jwt_payload(auth_token)
+    expires_at = claims.get("exp", int(time.time()) + 3600)
+
+    CREDENTIALS_DIR.mkdir(parents=True, exist_ok=True)
+    CREDENTIALS_DIR.chmod(0o700)
+
+    data = {
+        "auth_token": auth_token,
+        "refresh_token": refresh_token,
+        "expires_at": expires_at,
+        "username": claims.get("username", ""),
+    }
+    CREDENTIALS_FILE.write_text(json.dumps(data, indent=2))
+    CREDENTIALS_FILE.chmod(0o600)
+
+
+def load_credentials() -> dict | None:
+    """Load cached credentials from disk. Returns None if missing or corrupt."""
+    if not CREDENTIALS_FILE.exists():
+        return None
+    try:
+        return json.loads(CREDENTIALS_FILE.read_text())
+    except (json.JSONDecodeError, OSError):
+        return None
+
+
+def get_valid_token(base_url: str) -> str | None:
+    """Return a valid auth token, refreshing if needed.
+
+    Checks (in order):
+    1. SENTINEL_TOKEN env var
+    2. Cached credentials with auto-refresh
+    Returns None if no valid token is available.
+    """
+    env_token = os.environ.get("SENTINEL_TOKEN")
+    if env_token:
+        return env_token
+
+    creds = load_credentials()
+    if not creds:
+        return None
+
+    now = time.time()
+    if creds["expires_at"] > now + 60:
+        return creds["auth_token"]
+
+    # Token expired or near expiry - try refresh
+    try:
+        new_auth, new_refresh = _refresh_token(base_url, creds["refresh_token"])
+        save_credentials(new_auth, new_refresh)
+        return new_auth
+    except Exception as exc:
+        logger.debug("Token refresh failed: %s", exc)
+        return None
+
+
+def _refresh_token(base_url: str, refresh_tok: str) -> tuple[str, str]:
+    """Exchange a refresh token for new auth + refresh tokens."""
+    with httpx.Client(timeout=30.0) as client:
+        resp = client.post(
+            f"{base_url}/api/v1/auth/refresh",
+            json={"refresh_token": refresh_tok},
+        )
+        resp.raise_for_status()
+        data = resp.json()
+        auth_token = data.get("authToken") or data.get("access_token")
+        refresh_token = data.get("refreshToken") or data.get("refresh_token")
+        if not auth_token or not refresh_token:
+            raise ValueError("Missing tokens in refresh response")
+        return auth_token, refresh_token
+
+
+def interactive_login(base_url: str) -> None:
+    """Run the full OTP login flow interactively."""
+    username = Prompt.ask("[bold]Username[/bold]")
+    password = Prompt.ask("[bold]Password[/bold]", password=True)
+
+    with httpx.Client(timeout=30.0) as client:
+        # Step 1: Login
+        resp = client.post(
+            f"{base_url}/api/v1/auth/login",
+            json={"username": username, "password": password},
+        )
+        if resp.status_code >= 400:
+            detail = resp.json().get("detail", "Login failed")
+            console.print(f"[red]Login failed:[/red] {detail}")
+            raise SystemExit(1)
+
+        data = resp.json()
+        session_token = data.get("sessionToken", "")
+
+        # Step 2: Request OTP
+        resp = client.post(
+            f"{base_url}/api/v1/auth/request-otp",
+            headers={"x-session-token": session_token},
+            content=b"",
+        )
+        if resp.status_code >= 400:
+            detail = resp.json().get("detail", "OTP request failed")
+            console.print(f"[red]OTP request failed:[/red] {detail}")
+            raise SystemExit(1)
+
+        otp_data = resp.json()
+        new_session = otp_data.get("sessionToken")
+        if new_session:
+            session_token = new_session
+
+        console.print("[dim]OTP sent. Check your phone/email.[/dim]")
+
+        # Step 3: Verify OTP
+        otp_code = Prompt.ask("[bold]OTP Code[/bold]")
+        resp = client.post(
+            f"{base_url}/api/v1/auth/verify-otp",
+            json={"otp": otp_code},
+            headers={"x-session-token": session_token},
+        )
+        if resp.status_code >= 400:
+            detail = resp.json().get("detail", "OTP verification failed")
+            console.print(f"[red]OTP verification failed:[/red] {detail}")
+            raise SystemExit(1)
+
+        data = resp.json()
+        auth_token = data.get("authToken") or data.get("access_token")
+        refresh_token = data.get("refreshToken") or data.get("refresh_token")
+
+        if not auth_token:
+            console.print("[red]No auth token in response[/red]")
+            raise SystemExit(1)
+
+        # Verify admin status
+        claims = _decode_jwt_payload(auth_token)
+        if not claims.get("is_admin"):
+            console.print("[red]Account is not an admin[/red]")
+            raise SystemExit(1)
+
+        save_credentials(auth_token, refresh_token or "")
+        console.print(f"[green]Logged in as {claims.get('username', username)}[/green]")