cli-backup 0.1.0__tar.gz

cli_backup-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 cli-backup contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

cli_backup-0.1.0/PKG-INFO

@@ -0,0 +1,119 @@
+Metadata-Version: 2.4
+Name: cli-backup
+Version: 0.1.0
+Summary: Host backup CLI for database snapshots and directory archives
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/XakkiDev/cli-backup
+Project-URL: Issues, https://github.com/XakkiDev/cli-backup/issues
+Keywords: backup,mysql,mariadb,sqlite,s3
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: boto3==1.43.127
+Provides-Extra: dev
+Requires-Dist: ruff==0.6.9; extra == "dev"
+Dynamic: license-file
+
+# cli-backup
+
+A Python command-line tool for full database backups and directory archives, stored locally, in S3-compatible object storage, or both. Use it directly or include the shared Makefile in multiple projects on the same host.
+
+[![CI](https://github.com/XakkiDev/cli-backup/actions/workflows/ci.yml/badge.svg)](https://github.com/XakkiDev/cli-backup/actions/workflows/ci.yml) · [MIT license](LICENSE)
+
+## Capabilities
+
+| Interface | Sources | Features |
+| --- | --- | --- |
+| `scheduled` and `share.Makefile` | MariaDB, MySQL, SQLite | Date-based daily, weekly and monthly snapshots; Docker or Podman containers, TCP, or SQLite online backup |
+| Generic commands | MariaDB/MySQL, Redis, directories | Full dumps, Redis RDB snapshots, gzip tar archives and exclusion patterns |
+
+The CLI runs on the host, supports rootless Docker and Podman for scheduled database backups, and does not require a separate backup service in a project's Compose file. Scheduled Compose targets are discovered from container labels. PostgreSQL, MongoDB and incremental backups are not implemented.
+
+**Protect backup data and credentials.** Backups are not encrypted by this tool. Use private local paths, protected environment files and encrypted transport. Backups are not a substitute for an authorized recovery exercise. This CLI does not create buckets, change lifecycle policies, or schedule jobs.
+
+## Installation
+
+Python 3.11+ on a POSIX host is required. Client binaries are required for direct database or Redis connections. The selected Docker/Podman runtime is required for container sources.
+
+```sh
+git clone https://github.com/XakkiDev/cli-backup.git
+cd cli-backup
+make venv install
+.venv/bin/cli-backup --help
+.venv/bin/cli-backup scheduled --help
+```
+
+For a user-wide executable, `pipx install .` installs from the checkout. `share.Makefile` is supplied in the repository checkout rather than the Python wheel: keep or download a trusted checkout to use the shared Make targets. On systems without `ensurepip`, install the matching Python venv package first.
+
+The Composer package `xakki/cli-backup` distributes the source tree and agent skills for Composer-based projects. Composer does not install Python dependencies or provide a ready-to-run CLI: after `composer require xakki/cli-backup`, install the Python project from `vendor/xakki/cli-backup` with `pip` or `pipx` and include `vendor/xakki/cli-backup/share.Makefile` when needed. The `extra.skills.source` metadata identifies the agent skills for compatible Composer skill managers.
+
+
+## Scheduled database backups
+
+Include `share.Makefile` from your checkout. For a Compose service:
+
+```make
+CLI_BACKUP_COMPOSE_PROJECT_NAME := example
+CLI_BACKUP_DB_CONTAINER := mariadb
+include /path/to/cli-backup/share.Makefile
+export CLI_BACKUP_COMPOSE_PROJECT_NAME CLI_BACKUP_DB_CONTAINER
+```
+
+Set `CLI_BACKUP_PROJECT_NAME` if the storage namespace should differ from the Compose project. For a standalone container, set `CLI_BACKUP_PROJECT_NAME` and `CLI_BACKUP_DB_CONTAINER` to its name or ID. Set `CLI_BACKUP_CONTAINER_RUNTIME=podman` to use local rootless Podman; Docker is the default and uses the selected Docker context. For TCP use `CLI_BACKUP_PROJECT_NAME`, `CLI_BACKUP_DB_HOST`, optionally `CLI_BACKUP_DB_PORT`, `CLI_BACKUP_DB_NAME`, `CLI_BACKUP_DB_USER` and `CLI_BACKUP_DB_PASSWORD`.
+
+Container mode defaults to root, using `MARIADB_ROOT_PASSWORD` and `MARIADB_DATABASE` from the container; MySQL equivalents are also supported. Set a user and password together to override root. `CLI_BACKUP_DB_NAME` accepts comma-separated database names; each database produces a separate file. Credentials must be supplied in the environment or a protected project file, never as command-line arguments.
+
+For SQLite, set `CLI_BACKUP_PROJECT_NAME`, `CLI_BACKUP_DB_SERVICE_NAME=sqlite`, and an absolute `CLI_BACKUP_DB_PATH`. Do not set container, host or Compose variables. The SQLite online backup API includes committed WAL transactions without stopping the writer. Automatic SQLite restoration is not implemented.
+
+```sh
+make cli-backup@config-check
+make cli-backup@backup
+make cli-backup@list path=daily where=local
+make cli-backup@verify path=daily where=local file=2026-01-01.example.sql.gz
+```
+
+Additional targets `cli-backup@restore-test` and `cli-backup@restore` exist for MariaDB/MySQL. A live restore is destructive, requires an explicit file and interactive confirmation, and must target the correct stopped-writer environment. A restore rehearsal creates a disposable isolated container and should run only with appropriate authorization. For an unavailable source container, set `CLI_BACKUP_TEST_MYSQL_IMAGE` to an appropriate disposable test image before a rehearsal. Use `db=<name>` to filter when needed. Source-independent `list` and `verify` work with a stopped database container.
+
+### Storage and schedule
+
+Set `CLI_BACKUP_LOCAL_ROOT` for local storage and/or the S3 variables `CLI_BACKUP_S3_BUCKET`, `CLI_BACKUP_S3_ENDPOINT`, `CLI_BACKUP_S3_REGION`, `CLI_BACKUP_S3_KEY`, `CLI_BACKUP_S3_SECRET`, and optionally `CLI_BACKUP_S3_PREFIX`. Project environment values override global environment values; explicit scheduled CLI options override project values. `--project-env` accepts literal assignments and does not execute shell code. Period keys are relative to the optional S3 prefix:
+
+```text
+daily/<project>/<source>/YYYY-MM-DD.<database>.sql.gz
+weekly/<project>/<source>/YYYY-MM-DD.<database>.sql.gz
+monthly/<project>/<source>/YYYY-MM-DD.<database>.sql.gz
+.state/<project>/<source>/...  # schedule metadata
+```
+
+SQLite uses `.sqlite.gz`. `CLI_BACKUP_PERIOD_DAILY` and `CLI_BACKUP_PERIOD_MONTHLY` default to `true`; `CLI_BACKUP_PERIOD_WEEKLY` defaults to `false`. With daily enabled, beginning on Wednesday or the third day of the month, the latest eligible daily copy from the preceding week or month is copied to the relevant period if missing. When both select the same Sunday, weekly chooses an earlier snapshot. With daily disabled, a new weekly or monthly snapshot is created on or after the threshold if the current period is missing. Run the command from an external scheduler, normally daily, so missed attempts can be retried. A completed period may not create a new snapshot on a repeated invocation.
+
+`CLI_BACKUP_LOCAL_DAYS` sets local retention, with minimum retention for period selection and idempotency. The object storage service controls S3 retention. Required destinations are attempted independently, and errors cause a nonzero exit. S3 publishing reads and verifies the complete uploaded object before publishing its manifest. The default CPU scheduling priority is `nice 10` for the CLI and container dump client; configure `CLI_BACKUP_CPU_NICE` from 0 to 19. This does not limit the database server's CPU or I/O.
+
+## Generic CLI
+
+Run `cli-backup --help` for global options and commands. Generic CLI options precede the subcommand. Its configuration uses `CLI_BACKUP_PROJECT` and `CLI_BACKUP_DB_MODE` (`compose`, `container`, or `tcp`), which are distinct from the scheduled interface's project and connection variables.
+
+```sh
+cli-backup backup mysql
+cli-backup backup redis
+cli-backup backup files --directory /srv/example --exclude '*.tmp' --exclude 'cache/*'
+cli-backup list files --storage local
+cli-backup verify files --storage local --file NAME
+```
+
+Directory archives are full scans, not point-in-time filesystem snapshots. Exclusion patterns use Python `fnmatch` relative to the source; `*` can match `/`. Symlinks are archived without following them, hard links are archived separately, and unsafe escaping links or special files must be excluded. Extraction requires a new absolute destination and rejects unsafe paths; permissions are restored without setuid/setgid bits, and ownership is not restored. See `cli-backup restore --help` before recovery.
+
+MariaDB/MySQL dumps use `--single-transaction`; coordinate schema changes and nontransactional tables. Object-count comparisons do not prove row-level equivalence. The local and S3 files are sensitive; ensure sufficient free temporary space and protect the destination.
+
+## Development and AI agent skills
+
+```sh
+make venv install
+make test lint
+```
+
+CI runs unit tests on Python 3.11–3.13, lint, build and installed-wheel smoke tests. `make test-integration` requires explicitly selected disposable images and may perform database restoration; run it only when authorized. Project-portable skills for agents are in [`.agents/skills/`](.agents/skills/): `cli-backup-setup` covers integration and `cli-backup-develop` covers implementation and testing. They do not authorize storage administration, schedule changes, or restoration.
+
+## License
+
+[MIT](LICENSE)

cli_backup-0.1.0/README.md

@@ -0,0 +1,103 @@
+# cli-backup
+
+A Python command-line tool for full database backups and directory archives, stored locally, in S3-compatible object storage, or both. Use it directly or include the shared Makefile in multiple projects on the same host.
+
+[![CI](https://github.com/XakkiDev/cli-backup/actions/workflows/ci.yml/badge.svg)](https://github.com/XakkiDev/cli-backup/actions/workflows/ci.yml) · [MIT license](LICENSE)
+
+## Capabilities
+
+| Interface | Sources | Features |
+| --- | --- | --- |
+| `scheduled` and `share.Makefile` | MariaDB, MySQL, SQLite | Date-based daily, weekly and monthly snapshots; Docker or Podman containers, TCP, or SQLite online backup |
+| Generic commands | MariaDB/MySQL, Redis, directories | Full dumps, Redis RDB snapshots, gzip tar archives and exclusion patterns |
+
+The CLI runs on the host, supports rootless Docker and Podman for scheduled database backups, and does not require a separate backup service in a project's Compose file. Scheduled Compose targets are discovered from container labels. PostgreSQL, MongoDB and incremental backups are not implemented.
+
+**Protect backup data and credentials.** Backups are not encrypted by this tool. Use private local paths, protected environment files and encrypted transport. Backups are not a substitute for an authorized recovery exercise. This CLI does not create buckets, change lifecycle policies, or schedule jobs.
+
+## Installation
+
+Python 3.11+ on a POSIX host is required. Client binaries are required for direct database or Redis connections. The selected Docker/Podman runtime is required for container sources.
+
+```sh
+git clone https://github.com/XakkiDev/cli-backup.git
+cd cli-backup
+make venv install
+.venv/bin/cli-backup --help
+.venv/bin/cli-backup scheduled --help
+```
+
+For a user-wide executable, `pipx install .` installs from the checkout. `share.Makefile` is supplied in the repository checkout rather than the Python wheel: keep or download a trusted checkout to use the shared Make targets. On systems without `ensurepip`, install the matching Python venv package first.
+
+The Composer package `xakki/cli-backup` distributes the source tree and agent skills for Composer-based projects. Composer does not install Python dependencies or provide a ready-to-run CLI: after `composer require xakki/cli-backup`, install the Python project from `vendor/xakki/cli-backup` with `pip` or `pipx` and include `vendor/xakki/cli-backup/share.Makefile` when needed. The `extra.skills.source` metadata identifies the agent skills for compatible Composer skill managers.
+
+
+## Scheduled database backups
+
+Include `share.Makefile` from your checkout. For a Compose service:
+
+```make
+CLI_BACKUP_COMPOSE_PROJECT_NAME := example
+CLI_BACKUP_DB_CONTAINER := mariadb
+include /path/to/cli-backup/share.Makefile
+export CLI_BACKUP_COMPOSE_PROJECT_NAME CLI_BACKUP_DB_CONTAINER
+```
+
+Set `CLI_BACKUP_PROJECT_NAME` if the storage namespace should differ from the Compose project. For a standalone container, set `CLI_BACKUP_PROJECT_NAME` and `CLI_BACKUP_DB_CONTAINER` to its name or ID. Set `CLI_BACKUP_CONTAINER_RUNTIME=podman` to use local rootless Podman; Docker is the default and uses the selected Docker context. For TCP use `CLI_BACKUP_PROJECT_NAME`, `CLI_BACKUP_DB_HOST`, optionally `CLI_BACKUP_DB_PORT`, `CLI_BACKUP_DB_NAME`, `CLI_BACKUP_DB_USER` and `CLI_BACKUP_DB_PASSWORD`.
+
+Container mode defaults to root, using `MARIADB_ROOT_PASSWORD` and `MARIADB_DATABASE` from the container; MySQL equivalents are also supported. Set a user and password together to override root. `CLI_BACKUP_DB_NAME` accepts comma-separated database names; each database produces a separate file. Credentials must be supplied in the environment or a protected project file, never as command-line arguments.
+
+For SQLite, set `CLI_BACKUP_PROJECT_NAME`, `CLI_BACKUP_DB_SERVICE_NAME=sqlite`, and an absolute `CLI_BACKUP_DB_PATH`. Do not set container, host or Compose variables. The SQLite online backup API includes committed WAL transactions without stopping the writer. Automatic SQLite restoration is not implemented.
+
+```sh
+make cli-backup@config-check
+make cli-backup@backup
+make cli-backup@list path=daily where=local
+make cli-backup@verify path=daily where=local file=2026-01-01.example.sql.gz
+```
+
+Additional targets `cli-backup@restore-test` and `cli-backup@restore` exist for MariaDB/MySQL. A live restore is destructive, requires an explicit file and interactive confirmation, and must target the correct stopped-writer environment. A restore rehearsal creates a disposable isolated container and should run only with appropriate authorization. For an unavailable source container, set `CLI_BACKUP_TEST_MYSQL_IMAGE` to an appropriate disposable test image before a rehearsal. Use `db=<name>` to filter when needed. Source-independent `list` and `verify` work with a stopped database container.
+
+### Storage and schedule
+
+Set `CLI_BACKUP_LOCAL_ROOT` for local storage and/or the S3 variables `CLI_BACKUP_S3_BUCKET`, `CLI_BACKUP_S3_ENDPOINT`, `CLI_BACKUP_S3_REGION`, `CLI_BACKUP_S3_KEY`, `CLI_BACKUP_S3_SECRET`, and optionally `CLI_BACKUP_S3_PREFIX`. Project environment values override global environment values; explicit scheduled CLI options override project values. `--project-env` accepts literal assignments and does not execute shell code. Period keys are relative to the optional S3 prefix:
+
+```text
+daily/<project>/<source>/YYYY-MM-DD.<database>.sql.gz
+weekly/<project>/<source>/YYYY-MM-DD.<database>.sql.gz
+monthly/<project>/<source>/YYYY-MM-DD.<database>.sql.gz
+.state/<project>/<source>/...  # schedule metadata
+```
+
+SQLite uses `.sqlite.gz`. `CLI_BACKUP_PERIOD_DAILY` and `CLI_BACKUP_PERIOD_MONTHLY` default to `true`; `CLI_BACKUP_PERIOD_WEEKLY` defaults to `false`. With daily enabled, beginning on Wednesday or the third day of the month, the latest eligible daily copy from the preceding week or month is copied to the relevant period if missing. When both select the same Sunday, weekly chooses an earlier snapshot. With daily disabled, a new weekly or monthly snapshot is created on or after the threshold if the current period is missing. Run the command from an external scheduler, normally daily, so missed attempts can be retried. A completed period may not create a new snapshot on a repeated invocation.
+
+`CLI_BACKUP_LOCAL_DAYS` sets local retention, with minimum retention for period selection and idempotency. The object storage service controls S3 retention. Required destinations are attempted independently, and errors cause a nonzero exit. S3 publishing reads and verifies the complete uploaded object before publishing its manifest. The default CPU scheduling priority is `nice 10` for the CLI and container dump client; configure `CLI_BACKUP_CPU_NICE` from 0 to 19. This does not limit the database server's CPU or I/O.
+
+## Generic CLI
+
+Run `cli-backup --help` for global options and commands. Generic CLI options precede the subcommand. Its configuration uses `CLI_BACKUP_PROJECT` and `CLI_BACKUP_DB_MODE` (`compose`, `container`, or `tcp`), which are distinct from the scheduled interface's project and connection variables.
+
+```sh
+cli-backup backup mysql
+cli-backup backup redis
+cli-backup backup files --directory /srv/example --exclude '*.tmp' --exclude 'cache/*'
+cli-backup list files --storage local
+cli-backup verify files --storage local --file NAME
+```
+
+Directory archives are full scans, not point-in-time filesystem snapshots. Exclusion patterns use Python `fnmatch` relative to the source; `*` can match `/`. Symlinks are archived without following them, hard links are archived separately, and unsafe escaping links or special files must be excluded. Extraction requires a new absolute destination and rejects unsafe paths; permissions are restored without setuid/setgid bits, and ownership is not restored. See `cli-backup restore --help` before recovery.
+
+MariaDB/MySQL dumps use `--single-transaction`; coordinate schema changes and nontransactional tables. Object-count comparisons do not prove row-level equivalence. The local and S3 files are sensitive; ensure sufficient free temporary space and protect the destination.
+
+## Development and AI agent skills
+
+```sh
+make venv install
+make test lint
+```
+
+CI runs unit tests on Python 3.11–3.13, lint, build and installed-wheel smoke tests. `make test-integration` requires explicitly selected disposable images and may perform database restoration; run it only when authorized. Project-portable skills for agents are in [`.agents/skills/`](.agents/skills/): `cli-backup-setup` covers integration and `cli-backup-develop` covers implementation and testing. They do not authorize storage administration, schedule changes, or restoration.
+
+## License
+
+[MIT](LICENSE)

cli_backup-0.1.0/pyproject.toml

@@ -0,0 +1,23 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "cli-backup"
+version = "0.1.0"
+description = "Host backup CLI for database snapshots and directory archives"
+requires-python = ">=3.11"
+dependencies = ["boto3==1.43.127"]
+license = "MIT"
+readme = "README.md"
+keywords = ["backup", "mysql", "mariadb", "sqlite", "s3"]
+
+[project.urls]
+Homepage = "https://github.com/XakkiDev/cli-backup"
+Issues = "https://github.com/XakkiDev/cli-backup/issues"
+
+[project.optional-dependencies]
+dev = ["ruff==0.6.9"]
+
+[project.scripts]
+cli-backup = "cli_backup.cli:main"

cli_backup-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

cli_backup-0.1.0/src/cli_backup/__init__.py

@@ -0,0 +1 @@
+"""Backup CLI."""

cli_backup-0.1.0/src/cli_backup/cli.py

@@ -0,0 +1,209 @@
+"""Command-line entry point for backup and recovery."""
+from __future__ import annotations
+
+import argparse
+import os
+import subprocess
+import sys
+import tempfile
+import uuid
+from datetime import datetime, timezone
+from pathlib import Path
+
+from .config import load_config, read_project_env, resolve
+from .cpu_priority import lower_cpu_priority, validate_cpu_nice
+from .files import capture_directory, extract_archive
+from .mysql import MySQLConfig, capture_mysql, count_mysql_objects, restore_mysql
+from .redis_backup import capture_redis
+from .rehearsal import rehearse_mysql, rehearse_redis
+from .storage import LocalStorage, S3Storage, local_get, make_manifest, prune_local, s3_get, s3_list, write_private_copy
+
+
+def parser_build() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog='cli-backup')
+    parser.add_argument('--project-env', type=Path)
+    parser.add_argument('--project')
+    parser.add_argument('--local-root')
+    parser.add_argument('--temp-root')
+    parser.add_argument('--s3-bucket')
+    parser.add_argument('--s3-endpoint')
+    parser.add_argument('--s3-region')
+    parser.add_argument('--s3-prefix')
+    parser.add_argument('--compose-env-file', action='append', default=[])
+    for option in ('db-mode', 'db-name', 'db-user', 'db-host', 'db-port', 'db-service',
+                   'db-network', 'db-image', 'db-client', 'compose-dir', 'redis-host',
+                   'redis-port', 'redis-timeout', 'local-days', 'cpu-nice', 'test-mysql-image', 'test-redis-image', 'test-redis-server', 'restore-timeout'):
+        parser.add_argument('--' + option)
+    sub = parser.add_subparsers(dest='command', required=True)
+    sub.add_parser('scheduled', help='scheduled database backups; run cli-backup scheduled --help')
+    sub.add_parser('config-check')
+    publish = sub.add_parser('publish-local')
+    publish.add_argument('source', choices=['files', 'mysql', 'redis'])
+    publish.add_argument('--file', required=True)
+    backup = sub.add_parser('backup')
+    backup.add_argument('source', choices=['files', 'mysql', 'redis'])
+    backup.add_argument('--directory', type=Path)
+    backup.add_argument('--exclude', action='append', default=[])
+    for name in ('list', 'verify', 'restore', 'restore-test', 'download'):
+        item = sub.add_parser(name)
+        item.add_argument('source', choices=['files', 'mysql', 'redis'])
+        item.add_argument('--storage', choices=['local', 's3'], default='local')
+        if name != 'list':
+            item.add_argument('--file', required=(name != 'restore-test'))
+        if name == 'download':
+            item.add_argument('--destination', type=Path, required=True)
+        if name == 'restore':
+            item.add_argument('--destination', type=Path)
+            item.add_argument('--target', help='explicit database name')
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    argv = sys.argv[1:] if argv is None else argv
+    if argv and argv[0] == 'scheduled':
+        from .scheduled import main as scheduled_main
+        return scheduled_main(argv[1:])
+    args = parser_build().parse_args(argv)
+    try:
+        project_env = read_project_env(args.project_env) if args.project_env else {}
+        settings = vars(args)
+        config = load_config(os.environ, project_env, settings)
+        def setting(name: str, default: str = '') -> str:
+            return resolve(name, settings.get(name), project_env, os.environ) or default
+        cpu_nice = validate_cpu_nice(setting('cpu_nice', '10'))
+        if args.command == 'backup':
+            lower_cpu_priority(cpu_nice)
+        if args.command == 'config-check':
+            print(f'Configuration valid for project {config.project}')
+            return 0
+        stores = {}
+        if config.local_root:
+            stores['local'] = LocalStorage(Path(config.local_root).expanduser())
+        if config.s3_bucket and (args.command in ('backup', 'publish-local') or args.storage == 's3'):
+            def s3_factory():
+                import boto3
+                from botocore.config import Config
+                client = boto3.client('s3', endpoint_url=setting('s3_endpoint') or None,
+                    region_name=setting('s3_region') or None, config=Config(s3={'addressing_style': 'path'}),
+                    aws_access_key_id=setting('s3_key') or None,
+                    aws_secret_access_key=setting('s3_secret') or None)
+                return S3Storage(client, config.s3_bucket, setting('s3_prefix'))
+            stores['s3'] = s3_factory
+        def mysql_config(database: str | None = None) -> MySQLConfig:
+            return MySQLConfig(mode=setting('db_mode', 'compose'), database=database or setting('db_name'),
+                user=setting('db_user'), password=setting('db_password'), host=setting('db_host', '127.0.0.1'),
+                port=int(setting('db_port', '3306')), service=setting('db_service', 'mariadb'),
+                network=setting('db_network'), image=setting('db_image'), compose_dir=setting('compose_dir', '.'),
+                client=setting('db_client', 'mariadb'), compose_env_files=tuple(args.compose_env_file), cpu_nice=cpu_nice)
+        if args.command == 'publish-local':
+            if 'local' not in stores or 's3' not in stores:
+                raise ValueError('local and S3 storage are required')
+            local = stores['local']
+            manifest = next((item for item in local.list(config.project, args.source) if item.artifact == args.file), None)
+            if manifest is None or not local.verify(manifest):
+                raise ValueError('local backup missing or checksum mismatch')
+            remote = stores['s3']()
+            if not remote.verify(manifest):
+                raise ValueError('remote backup checksum mismatch')
+            remote.client.put_object(Bucket=remote.bucket, Key=remote.key(manifest) + '.json',
+                                     Body=manifest.encode(), IfNoneMatch='*')
+            print(f's3: {manifest.artifact}')
+            return 0
+        temp_root = setting('temp_root')
+        with tempfile.TemporaryDirectory(prefix='cli-backup-', dir=str(Path(temp_root).expanduser().absolute()) if temp_root else None) as tmp:
+            artifact = Path(tmp) / 'artifact'
+            if args.command == 'backup':
+                retention = setting('local_days')
+                if retention and int(retention) < 1:
+                    raise ValueError('local retention days must be positive')
+                object_counts = None
+                if args.source == 'files':
+                    if not args.directory:
+                        raise ValueError('--directory is required for file backup')
+                    capture_directory(args.directory, args.exclude, artifact)
+                elif args.source == 'mysql':
+                    database = mysql_config()
+                    object_counts = count_mysql_objects(database)
+                    with artifact.open('xb') as output:
+                        capture_mysql(database, output)
+                    if count_mysql_objects(database) != object_counts:
+                        raise ValueError('source schema object counts changed during dump')
+                else:
+                    capture_redis(artifact, setting('redis_host', '127.0.0.1'), int(setting('redis_port', '6379')), setting('redis_password') or None, timeout=int(setting('redis_timeout', '14400')))
+                if artifact.stat().st_size == 0:
+                    raise ValueError('source produced an empty backup')
+                now = datetime.now(timezone.utc)
+                name = f'{now:%Y%m%dT%H%M%SZ}-{uuid.uuid4().hex}.bin'
+                manifest = make_manifest(artifact, config.project, args.source, name, now.isoformat(), object_counts)
+                failures = []
+                for label, store in stores.items():
+                    try:
+                        destination = store() if label == 's3' else store
+                        destination.put(artifact, manifest)
+                        print(f'{label}: {name}')
+                    except Exception as exc:
+                        print(f'{label}: backup failed ({type(exc).__name__})', file=sys.stderr)
+                        failures.append(label)
+                if failures:
+                    return 1
+                if retention and 'local' in stores:
+                    removed = prune_local(stores['local'], config.project, args.source, int(retention), now)
+                    print(f'local: removed {removed} expired backups')
+                return 0
+            if args.storage not in stores:
+                raise ValueError(f'{args.storage} storage is not configured')
+            store = stores[args.storage]
+            if args.storage == 's3':
+                store = store()
+            manifests = store.list(config.project, args.source) if args.storage == 'local' else s3_list(store, config.project, args.source)
+            if args.command == 'list':
+                for item in manifests:
+                    print(f'{item.artifact}\t{item.timestamp}\t{item.size}\t{item.sha256}')
+                return 0
+            manifest = (next((item for item in manifests if item.artifact == args.file), None)
+                        if args.file else (manifests[-1] if manifests else None))
+            if manifest is None:
+                raise ValueError('backup not found')
+            with artifact.open('xb') as output:
+                (local_get if args.storage == 'local' else s3_get)(store, manifest, output)
+            if args.command == 'verify':
+                print('SHA-256 verified against downloaded bytes' if args.storage == 's3' else 'SHA-256 verified')
+            elif args.command == 'download':
+                with artifact.open('rb') as source:
+                    write_private_copy(source, args.destination)
+            elif args.command == 'restore-test':
+                if args.source == 'mysql':
+                    restored = rehearse_mysql(artifact, setting('test_mysql_image'), setting('db_client', 'mariadb'), int(setting('restore_timeout', '14400')))
+                    expected = manifest.object_counts or count_mysql_objects(mysql_config())
+                    if expected != restored:
+                        raise ValueError(f'object counts differ: expected={expected}, restored={restored}')
+                    print(f'object counts match: {restored}')
+                elif args.source == 'redis':
+                    rehearse_redis(artifact, setting('test_redis_image'), setting('test_redis_server', 'redis-server'))
+                else:
+                    raise ValueError('restore-test supports mysql and redis')
+            elif args.source == 'files':
+                if not args.destination:
+                    raise ValueError('--destination is required')
+                extract_archive(artifact, args.destination)
+                print('Extracted; original ownership is not restored', file=sys.stderr)
+            elif args.source == 'mysql':
+                if not args.target:
+                    raise ValueError('--target is required')
+                if not sys.stdin.isatty() or input(f'Restore into database {args.target}? Type yes: ') != 'yes':
+                    raise ValueError('restore not confirmed')
+                with artifact.open('rb') as source:
+                    restore_mysql(mysql_config(args.target), source)
+            else:
+                raise ValueError('live Redis restore is manual; use a verified RDB snapshot')
+            return 0
+    except (OSError, ValueError, subprocess.SubprocessError) as exc:
+        print(f'cli-backup: {exc}', file=sys.stderr)
+        return 2
+    except Exception as exc:
+        print(f'cli-backup: operation failed ({type(exc).__name__})', file=sys.stderr)
+        return 2
+
+
+if __name__ == '__main__':
+    raise SystemExit(main())

cli_backup-0.1.0/src/cli_backup/config.py

@@ -0,0 +1,68 @@
+"""Configuration resolution without executing project files."""
+from __future__ import annotations
+
+import os
+import re
+import shlex
+from collections.abc import Mapping
+from dataclasses import dataclass
+from pathlib import Path
+
+PREFIX = "CLI_BACKUP_"
+
+
+def resolve(name: str, argument: str | None, project: Mapping[str, str], global_env: Mapping[str, str] | None = None) -> str | None:
+    key = f"{PREFIX}{name.upper()}"
+    env = os.environ if global_env is None else global_env
+    return argument if argument is not None else project.get(key, env.get(key))
+
+
+def validate_project(project: str) -> str:
+    if not re.fullmatch(r"[A-Za-z0-9][A-Za-z0-9_-]{0,63}", project):
+        raise ValueError("invalid project identifier")
+    return project
+
+
+def read_project_env(path: Path) -> dict[str, str]:
+    """Read literal CLI_BACKUP assignments; no expansion or shell execution."""
+    result: dict[str, str] = {}
+    for number, line in enumerate(path.read_text(encoding="utf-8").splitlines(), 1):
+        line = line.strip()
+        if not line or line.startswith("#"):
+            continue
+        if line.startswith("export "):
+            line = line[7:].lstrip()
+        key, sep, value = line.partition("=")
+        key = key.strip()
+        if not key.startswith(PREFIX):
+            continue
+        if not sep or not re.fullmatch(r"CLI_BACKUP_[A-Z0-9_]+", key):
+            raise ValueError(f"invalid project setting at line {number}")
+        try:
+            tokens = shlex.split(value, comments=True, posix=True)
+        except ValueError as exc:
+            raise ValueError(f"invalid project setting at line {number}") from exc
+        if len(tokens) > 1:
+            raise ValueError(f"invalid project setting at line {number}")
+        if key in result:
+            raise ValueError(f"duplicate project setting at line {number}")
+        result[key] = tokens[0] if tokens else ""
+    return result
+
+
+@dataclass(frozen=True)
+class Config:
+    project: str
+    local_root: str | None
+    s3_bucket: str | None
+
+
+def load_config(global_env: Mapping[str, str], project_env: Mapping[str, str], args: Mapping[str, str | None]) -> Config:
+    project = resolve("project", args.get("project"), project_env, global_env)
+    if not project:
+        raise ValueError("CLI_BACKUP_PROJECT is required")
+    root = resolve("local_root", args.get("local_root"), project_env, global_env) or None
+    bucket = resolve("s3_bucket", args.get("s3_bucket"), project_env, global_env) or None
+    if not root and not bucket:
+        raise ValueError("configure CLI_BACKUP_LOCAL_ROOT or CLI_BACKUP_S3_BUCKET")
+    return Config(validate_project(project), root, bucket)

cli_backup-0.1.0/src/cli_backup/cpu_priority.py

@@ -0,0 +1,21 @@
+"""Lower backup CPU scheduling priority without raising an inherited value."""
+from __future__ import annotations
+
+import os
+
+
+def validate_cpu_nice(value: str | int) -> int:
+    try:
+        parsed = int(value)
+    except (TypeError, ValueError) as exc:
+        raise ValueError('CLI_BACKUP_CPU_NICE must be an integer from 0 to 19') from exc
+    if not 0 <= parsed <= 19:
+        raise ValueError('CLI_BACKUP_CPU_NICE must be an integer from 0 to 19')
+    return parsed
+
+
+def lower_cpu_priority(value: int) -> None:
+    priority = validate_cpu_nice(value)
+    current = os.getpriority(os.PRIO_PROCESS, 0)
+    if current < priority:
+        os.setpriority(os.PRIO_PROCESS, 0, priority)