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.
