Metadata-Version: 2.4
Name: sum-cli
Version: 3.1.0
Summary: SUM Platform CLI: single control plane for site lifecycle management
Author: Mark Ashton
License-Expression: BSD-3-Clause
Project-URL: Homepage, https://github.com/markashton480/sum-platform
Project-URL: Repository, https://github.com/markashton480/sum-platform
Project-URL: Issues, https://github.com/markashton480/sum-platform/issues
Project-URL: Documentation, https://github.com/markashton480/sum-platform/tree/main/docs/dev/cli.md
Keywords: sum,cli,django,wagtail
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Build Tools
Classifier: Topic :: Software Development :: Code Generators
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: click>=8.1.7
Requires-Dist: pyyaml>=6.0
Provides-Extra: gitea
Requires-Dist: httpx>=0.27.0; extra == "gitea"
Dynamic: license-file

# SUM CLI (v3.1)

[![PyPI](https://img.shields.io/pypi/v/sum-cli.svg)](https://pypi.org/project/sum-cli/)

The SUM CLI is the single control plane for deploying and managing SUM Platform client sites on staging and production servers.

## Install

```bash
pip install sum-cli
sum-platform --version
```

### With Gitea Support

If using Gitea instead of GitHub for repository hosting:

```bash
pip install sum-cli[gitea]
```

## Initial Setup

Before using the CLI, configure your infrastructure settings:

```bash
sudo sum-platform setup
```

This interactive command creates `/etc/sum/config.yml` with your staging/production server settings.

## Commands

| Command | Description | Requires Sudo |
|---------|-------------|---------------|
| `setup` | Configure infrastructure settings | Yes |
| `init` | Create new site at `/srv/sum/<name>/` | Yes |
| `update` | Pull updates, migrate, restart | No (staging) |
| `backup` | Database and media backup | No |
| `promote` | Deploy staging site to production | No |
| `check` | Validate project setup | No |
| `themes` | List available themes | No |

## Creating Sites

### With GitHub

```bash
sudo sum-platform init acme --git-provider github --git-org acme-corp
```

### With Gitea

```bash
sudo sum-platform init acme --git-provider gitea --git-org clients \
  --gitea-url https://gitea.agency.com
```

### With Gitea (Custom SSH Port)

```bash
sudo sum-platform init acme --git-provider gitea --git-org clients \
  --gitea-url https://gitea.agency.com --gitea-ssh-port 2222
```

### Without Git

```bash
sudo sum-platform init acme --no-git
```

### Additional Init Options

```bash
sudo sum-platform init acme --git-provider github --git-org acme-corp \
  --theme theme_a \
  --profile sage-stone \
  --content-path /path/to/custom/content
```

## Managing Sites

```bash
# Update a deployed site (pull, migrate, restart)
sum-platform update acme

# Backup database and media
sum-platform backup acme --include-media

# Promote staging to production
sum-platform promote acme --domain acme.example.com

# Validate project setup
sum-platform check acme

# List available themes
sum-platform themes
```

## Configuration

### Global Config (`/etc/sum/config.yml`)

Infrastructure settings only. Created via `sum-platform setup`.

```yaml
agency:
  name: Your Agency Name

staging:
  server: staging.example.com
  domain_pattern: "{slug}.staging.example.com"
  base_dir: /srv/sum

production:
  server: prod.example.com
  ssh_host: 10.0.0.1
  base_dir: /srv/sum

templates:
  dir: /opt/your-ops/infra
  systemd: systemd/sum-site-gunicorn.service.template
  caddy: caddy/Caddyfile.template

defaults:
  theme: theme_a
  seed_profile: starter
  deploy_user: deploy
  postgres_port: 5432
```

### Site Config (`/srv/sum/<site>/.sum/config.yml`)

Per-site configuration. Auto-created when you run `init`.

**GitHub site:**
```yaml
site:
  slug: acme
  theme: theme_a
  created: 2026-02-03T14:30:00Z

git:
  provider: github
  org: acme-corp
```

**Gitea site:**
```yaml
site:
  slug: acme
  theme: theme_a
  created: 2026-02-03T14:30:00Z

git:
  provider: gitea
  org: clients
  url: https://gitea.agency.com
  ssh_port: 2222
  token_env: GITEA_TOKEN
```

**No-git site:**
```yaml
site:
  slug: acme
  theme: theme_a
  created: 2026-02-03T14:30:00Z

git: null
```

## Git Provider Setup

### GitHub

Requires the GitHub CLI (`gh`) to be installed and authenticated:

```bash
gh auth login
```

### Gitea

Set the API token environment variable:

```bash
export GITEA_TOKEN=your-token-here
```

Or use a custom environment variable name:

```bash
sudo sum-platform init acme --git-provider gitea --git-org clients \
  --gitea-url https://gitea.agency.com --gitea-token-env MY_GITEA_TOKEN
```

## Development Install (monorepo)

```bash
pip install -e ./cli
```
