veltro-cli 0.15.7__py3-none-any.whl

veltro_cli/__init__.py

@@ -0,0 +1,6 @@
+"""veltro-cli — stdlib-only operator entry point for the Veltro suite."""
+
+from __future__ import annotations
+
+__version__ = "0.15.7"
+__all__ = ["__version__"]

veltro_cli/__main__.py

@@ -0,0 +1,7 @@
+"""python -m veltro_cli"""
+
+from __future__ import annotations
+
+from veltro_cli.cli import main
+
+raise SystemExit(main())

veltro_cli/cli.py

@@ -0,0 +1,478 @@
+"""veltro — single operator entry point (stdlib only)."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+from typing import Sequence
+
+from veltro_cli import __version__
+from veltro_cli.lib.agent import enroll_agent
+from veltro_cli.lib.backup import cmd_backup, cmd_restore
+from veltro_cli.lib.compose import ComposeClient
+from veltro_cli.lib.demo import ACTIONS as DEMO_ACTIONS, run_demo
+from veltro_cli.lib.doctor import run_doctor
+from veltro_cli.lib.env_init import init_env
+from veltro_cli.lib.errors import VeltroCliError, print_error
+from veltro_cli.lib.install import install as run_install
+from veltro_cli.lib.k8s import render as k8s_render
+from veltro_cli.lib.paths import resolve_dir
+from veltro_cli.lib.products import resolve_selection
+from veltro_cli.lib.status import collect_status, format_status
+from veltro_cli.lib.support import capture_support_bundle
+from veltro_cli.lib.toml_config import (
+    TLS_MODES,
+    VELTRO_TOML,
+    VeltroConfig,
+    read_config,
+)
+from veltro_cli.lib.upgrade import execute_upgrade, plan_upgrade
+
+
+def _load_ctx(args: argparse.Namespace) -> tuple[Path, str, bool, tuple[str, ...]]:
+    root = resolve_dir(getattr(args, "dir", None))
+    cfg = read_config(root / VELTRO_TOML)
+    products = resolve_selection(root, getattr(args, "products", None))
+    tls_mode = getattr(args, "tls", None) or (cfg.tls_mode if cfg else "off")
+    monitoring = bool(getattr(args, "monitoring", False) or (cfg.monitoring if cfg else False))
+    return root, tls_mode, monitoring, products
+
+
+def _client(args: argparse.Namespace) -> ComposeClient:
+    root, tls_mode, monitoring, products = _load_ctx(args)
+    return ComposeClient(root, products=products, tls_mode=tls_mode, monitoring=monitoring)
+
+
+def cmd_version(_args: argparse.Namespace) -> int:
+    print(f"veltro-cli {__version__}")
+    return 0
+
+
+def cmd_init_env(args: argparse.Namespace) -> int:
+    root = resolve_dir(args.dir)
+    generated = init_env(root, force=bool(args.force))
+    print(f"wrote {root / '.env'}")
+    print(f"  generated {len(generated)} secret(s): {' '.join(generated)}")
+    return 0
+
+
+def cmd_install(args: argparse.Namespace) -> int:
+    source = Path(args.source).resolve() if args.source else None
+    dest = run_install(
+        products=args.products,
+        directory=args.dir,
+        public_url=args.public_url,
+        tls_mode=args.tls,
+        yes=bool(args.yes),
+        source=source,
+        release_url=args.release_url,
+        release_sha256=args.release_sha256,
+        suite_version=args.suite_version,
+        monitoring=bool(args.monitoring),
+        skip_up=bool(args.skip_up),
+    )
+    print(f"installed into {dest}")
+    shown_public_url = args.public_url or (read_config(dest / VELTRO_TOML) or VeltroConfig()).public_url
+    saved = read_config(dest / VELTRO_TOML) or VeltroConfig()
+    print(f"  products={saved.products} tls={args.tls} public_url={shown_public_url}")
+    if args.tls == "internal":
+        print(
+            "  trust CA after startup: "
+            f"{dest / 'tls/caddy-data/caddy/pki/authorities/local/root.crt'}"
+        )
+    print("  next: veltro status")
+    return 0
+
+
+def cmd_up(args: argparse.Namespace) -> int:
+    client = _client(args)
+    compose_args = tuple(getattr(args, "compose_args", ()))
+    if args.dry_run:
+        client.up(*compose_args, dry_run=True)
+        for call in client.calls:
+            print(call.as_shell())
+        return 0
+    from veltro_cli.lib.install import start_stack
+
+    result = start_stack(client, *compose_args)
+    if result.stdout:
+        print(result.stdout, end="" if result.stdout.endswith("\n") else "\n")
+    if result.returncode != 0:
+        raise VeltroCliError(
+            result.stderr.strip() or "compose up failed",
+            remedy="run `veltro doctor` and `veltro logs`",
+        )
+    return 0
+
+
+def cmd_down(args: argparse.Namespace) -> int:
+    client = _client(args)
+    result = client.down(*getattr(args, "compose_args", ()), dry_run=bool(args.dry_run))
+    if args.dry_run:
+        print(client.calls[-1].as_shell())
+        return 0
+    if result.returncode != 0:
+        raise VeltroCliError(result.stderr.strip() or "compose down failed")
+    return 0
+
+
+def cmd_restart(args: argparse.Namespace) -> int:
+    client = _client(args)
+    result = client.restart(*getattr(args, "compose_args", ()), dry_run=bool(args.dry_run))
+    if args.dry_run:
+        print(client.calls[-1].as_shell())
+        return 0
+    if result.returncode != 0:
+        raise VeltroCliError(result.stderr.strip() or "compose restart failed")
+    return 0
+
+
+def cmd_ps(args: argparse.Namespace) -> int:
+    client = _client(args)
+    result = client.ps(*getattr(args, "compose_args", ()), dry_run=bool(args.dry_run))
+    if args.dry_run:
+        print(client.calls[-1].as_shell())
+        return 0
+    sys.stdout.write(result.stdout)
+    if result.returncode != 0:
+        sys.stderr.write(result.stderr)
+    return result.returncode
+
+
+def cmd_logs(args: argparse.Namespace) -> int:
+    client = _client(args)
+    result = client.logs(*args.service, dry_run=bool(args.dry_run))
+    if args.dry_run:
+        print(client.calls[-1].as_shell())
+        return 0
+    sys.stdout.write(result.stdout)
+    if result.returncode != 0:
+        sys.stderr.write(result.stderr)
+    return result.returncode
+
+
+def cmd_config(args: argparse.Namespace) -> int:
+    client = _client(args)
+    compose_args = ("--format", args.format) if args.format else ()
+    result = client.config(*compose_args, dry_run=bool(args.dry_run))
+    if args.dry_run:
+        print(client.calls[-1].as_shell())
+        return 0
+    sys.stdout.write(result.stdout)
+    if result.returncode != 0:
+        sys.stderr.write(result.stderr)
+    return result.returncode
+
+def cmd_pull(args: argparse.Namespace) -> int:
+    client = _client(args)
+    result = client.pull(*getattr(args, "compose_args", ()), dry_run=bool(args.dry_run))
+    if args.dry_run:
+        print(client.calls[-1].as_shell())
+        return 0
+    sys.stdout.write(result.stdout)
+    if result.returncode != 0:
+        sys.stderr.write(result.stderr)
+    return result.returncode
+
+
+def cmd_status(args: argparse.Namespace) -> int:
+    root, tls_mode, monitoring, products = _load_ctx(args)
+    cfg = read_config(root / VELTRO_TOML)
+    public_url = args.public_url or (cfg.public_url if cfg else "http://localhost")
+    client = ComposeClient(root, products=products, tls_mode=tls_mode, monitoring=monitoring)
+
+    def fetcher(url: str, timeout: float = 3.0):
+        if args.dry_run:
+            return 200, '{"status":"ok"}'
+        from veltro_cli.lib.status import default_fetcher
+
+        return default_fetcher(url, timeout)
+
+    doc = collect_status(
+        root,
+        products=products,
+        public_url=public_url,
+        client=client,
+        fetcher=fetcher,
+        tls_mode=tls_mode,
+        check_latest=not args.dry_run,
+    )
+    sys.stdout.write(format_status(doc))
+    bad = any(p["state"] not in {"ready", "not_installed"} for p in doc.get("probes") or [])
+    return 1 if bad and not args.dry_run else 0
+
+
+def cmd_doctor(args: argparse.Namespace) -> int:
+    return run_doctor(
+        directory=args.dir,
+        products=args.products,
+        public_url=args.public_url,
+        http_port=int(args.http_port),
+    )
+
+
+def cmd_demo(args: argparse.Namespace) -> int:
+    return run_demo(
+        args.action,
+        directory=args.dir,
+        datasets=args.dataset,
+        extra_args=args.seed_arg,
+    )
+
+
+def cmd_agent(args: argparse.Namespace) -> int:
+    client = _client(args)
+    return enroll_agent(
+        directory=args.dir,
+        environment=args.environment,
+        client=client,
+        dry_run=bool(args.dry_run),
+    )
+
+
+def cmd_upgrade(args: argparse.Namespace) -> int:
+    root = resolve_dir(args.dir)
+    cfg = read_config(root / VELTRO_TOML)
+    current = (cfg.installed_suite_version if cfg else "") or "0.0.0"
+    if not args.to:
+        print(f"installed: {current}")
+        print("pass --to X.Y.Z to plan/execute an upgrade")
+        return 0
+    plan = plan_upgrade(directory=root, target=args.to, current=current)
+    print(f"upgrade plan: {plan['from']} → {plan['to']}")
+    for delta in plan["module_deltas"]:
+        print(f"  {delta['module']}: {delta['from']} → {delta['to']}")
+    for warning in plan["warnings"]:
+        print(f"  WARNING: {warning}")
+    for step in plan["steps"]:
+        print(f"  - {step}")
+    if args.dry_run:
+        return 0
+    execute_upgrade(directory=root, target=args.to, current=current)
+    print(f"upgraded to {args.to}")
+    return 0
+
+
+def cmd_k8s(args: argparse.Namespace) -> int:
+    if args.k8s_command != "render":
+        raise VeltroCliError(f"unknown k8s subcommand {args.k8s_command!r}")
+    products = resolve_selection(resolve_dir(getattr(args, "dir", None)), args.products)
+    out = k8s_render(
+        products=products,
+        values=args.values or (),
+        dry_run=bool(args.dry_run),
+    )
+    print(out)
+    return 0
+
+
+def cmd_support_bundle(args: argparse.Namespace) -> int:
+    path = capture_support_bundle(
+        directory=args.dir,
+        output=args.output,
+        base_url=args.base_url,
+    )
+    print(path)
+    return 0
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="veltro",
+        description="Operator CLI for the Veltro security operations suite.",
+    )
+    parser.add_argument("--version", action="store_true", help="print CLI version")
+    parser.add_argument("--dir", default=None, help="install / checkout directory (default: discover or ./veltro)")
+    parser.add_argument("--dry-run", action="store_true", help="print actions without running docker")
+
+    sub = parser.add_subparsers(dest="command")
+
+    p_install = sub.add_parser("install", help="download/materialise and start Veltro")
+    p_install.add_argument("--products", default=None, help="comma-separated subset of vectorflow,chad,warden; empty for core")
+    p_install.add_argument("--dir", default="./veltro")
+    p_install.add_argument("--public-url", default=None)
+    p_install.add_argument("--tls", choices=TLS_MODES, default="off")
+    p_install.add_argument("--yes", action="store_true")
+    p_install.add_argument("--source", default=None, help="path to a Veltro git checkout to copy from")
+    p_install.add_argument("--release-url", default=None, help="URL of a release tarball")
+    p_install.add_argument("--release-sha256", default=None, help="required SHA-256 for --release-url")
+    p_install.add_argument(
+        "--suite-version",
+        default=None,
+        help="Veltro release to install, X.Y.Z (default: the newest release)",
+    )
+    p_install.add_argument("--monitoring", action="store_true")
+    p_install.add_argument("--skip-up", action="store_true", help="materialise files only (tests)")
+    p_install.set_defaults(func=cmd_install)
+
+    def _lifecycle(name: str, func, help_text: str, *, passthrough: bool = False):
+        p = sub.add_parser(name, help=help_text)
+        p.add_argument("--products", default=None)
+        p.add_argument("--tls", choices=TLS_MODES, default=None)
+        p.add_argument("--monitoring", action="store_true")
+        p.add_argument("--dir", default=None)
+        p.add_argument("--dry-run", action="store_true")
+        if passthrough:
+            p.add_argument("compose_args", nargs=argparse.REMAINDER)
+        p.set_defaults(func=func)
+        return p
+
+    _lifecycle("up", cmd_up, "start the stack (compose up -d --wait)", passthrough=True)
+    _lifecycle("down", cmd_down, "stop containers (keeps volumes)", passthrough=True)
+    _lifecycle("restart", cmd_restart, "restart services", passthrough=True)
+    _lifecycle("ps", cmd_ps, "show service status", passthrough=True)
+    _lifecycle("pull", cmd_pull, "pull pinned images", passthrough=True)
+    p_logs = _lifecycle("logs", cmd_logs, "follow logs")
+    p_logs.add_argument("service", nargs="*")
+    p_config = _lifecycle("config", cmd_config, "render resolved compose config")
+    p_config.add_argument("--format", choices=("yaml", "json"), default=None)
+
+    p_status = sub.add_parser("status", help="compose ps + HTTP health probes")
+    p_status.add_argument("--products", default=None)
+    p_status.add_argument("--tls", choices=TLS_MODES, default=None)
+    p_status.add_argument("--dir", default=None)
+    p_status.add_argument("--public-url", default=None)
+    p_status.add_argument("--dry-run", action="store_true")
+    p_status.set_defaults(func=cmd_status)
+
+    p_doctor = sub.add_parser("doctor", help="host and install preflight checks")
+    p_doctor.add_argument("--products", default=None)
+    p_doctor.add_argument("--dir", default=None)
+    p_doctor.add_argument("--public-url", default=None)
+    p_doctor.add_argument("--http-port", default="80")
+    p_doctor.set_defaults(func=cmd_doctor)
+
+    p_demo = sub.add_parser("demo", help="list, seed or reset the demo sandbox datasets")
+    p_demo.add_argument("action", choices=DEMO_ACTIONS)
+    p_demo.add_argument(
+        "--dataset",
+        action="append",
+        default=[],
+        metavar="ID",
+        help="dataset id from content/datasets (repeatable, comma-separated, or `all`); defaults to brute-force on seed",
+    )
+    p_demo.add_argument("--dir", default=None)
+    # A trailing REMAINDER positional would swallow `--dataset` itself, so the
+    # golden-path seeder's extra arguments are passed one at a time.
+    p_demo.add_argument("--seed-arg", action="append", default=[], metavar="ARG",
+                        help="extra argument forwarded to scripts/seed-demo.sh (repeatable)")
+    p_demo.set_defaults(func=cmd_demo)
+
+    p_agent = sub.add_parser("agent", help="agent enrollment helpers")
+    agent_sub = p_agent.add_subparsers(dest="agent_command")
+    p_enroll = agent_sub.add_parser("enroll", help="start vf-agent profile and prepare token dir")
+    p_enroll.add_argument("--environment", default=None)
+    p_enroll.add_argument("--dir", default=None)
+    p_enroll.add_argument("--products", default=None)
+    p_enroll.add_argument("--dry-run", action="store_true")
+    p_enroll.set_defaults(func=cmd_agent)
+
+    p_upgrade = sub.add_parser("upgrade", help="upgrade to a newer suite release")
+    p_upgrade.add_argument("--to", default=None, help="Veltro release to upgrade to, X.Y.Z")
+    p_upgrade.add_argument("--dry-run", action="store_true")
+    p_upgrade.add_argument("--dir", default=None)
+    p_upgrade.set_defaults(func=cmd_upgrade)
+
+    p_backup = sub.add_parser("backup", help="create a suite backup (§1.5)")
+    p_backup.add_argument("--to", default=None)
+    p_backup.add_argument("--auto", action="store_true")
+    p_backup.add_argument("--products", default=None)
+    p_backup.add_argument("--include-env", action="store_true")
+    p_backup.add_argument("--passphrase", default=None)
+    p_backup.add_argument("--skip-optional", action="store_true")
+    p_backup.add_argument("--schedule", default=None)
+    p_backup.add_argument("--backup-dir", default=None)
+    p_backup.add_argument("--keep", type=int, default=7)
+    p_backup.add_argument("--dir", default=None)
+    p_backup.set_defaults(func=cmd_backup)
+
+    p_restore = sub.add_parser("restore", help="restore a suite backup (§1.5)")
+    p_restore.add_argument("path", nargs="?")
+    p_restore.add_argument("--yes", action="store_true")
+    p_restore.add_argument("--products", default=None)
+    p_restore.add_argument("--passphrase", default=None)
+    p_restore.add_argument("--dry-run", action="store_true")
+    p_restore.add_argument("--skip-start", action="store_true")
+    p_restore.add_argument("--dir", default=None)
+    p_restore.set_defaults(func=cmd_restore)
+
+    p_k8s = sub.add_parser("k8s", help="kubernetes helpers")
+    k8s_sub = p_k8s.add_subparsers(dest="k8s_command")
+    p_render = k8s_sub.add_parser("render", help="helm template the umbrella chart")
+    p_render.add_argument(
+        "--products",
+        default=None,
+        help="comma-separated subset of vectorflow,chad,warden on the core; empty for core only",
+    )
+    p_render.add_argument("--values", action="append", default=[])
+    p_render.add_argument("--dry-run", action="store_true")
+    p_render.set_defaults(func=cmd_k8s)
+
+    p_sb = sub.add_parser("support-bundle", help="capture a secret-free support bundle")
+    p_sb.add_argument("--dir", default=None)
+    p_sb.add_argument("--output", default=None)
+    p_sb.add_argument("--base-url", default=None)
+    p_sb.set_defaults(func=cmd_support_bundle)
+
+    p_init = sub.add_parser("init-env", help="bootstrap .env from .env.example")
+    p_init.add_argument("--dir", default=None)
+    p_init.add_argument("--force", action="store_true")
+    p_init.set_defaults(func=cmd_init_env)
+
+    return parser
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    argv_list = list(sys.argv[1:] if argv is None else argv)
+    parser = build_parser()
+    if any(arg == "--profile" or arg.startswith("--profile=") for arg in argv_list):
+        print("error: --profile was removed; select products with --products or VELTRO_PRODUCTS", file=sys.stderr)
+        return 2
+    try:
+        args, unknown = parser.parse_known_args(argv_list)
+        if unknown:
+            if getattr(args, "command", None) in {"up", "down", "restart", "ps", "pull"}:
+                args.compose_args = [*getattr(args, "compose_args", ()), *unknown]
+            elif getattr(args, "command", None) == "logs":
+                args.service = [*getattr(args, "service", ()), *unknown]
+            else:
+                parser.error("unrecognized arguments: " + " ".join(unknown))
+    except SystemExit as exc:
+        return int(exc.code or 0)
+
+    # Top-level --dir / --dry-run should win when a subcommand left defaults.
+    # argparse subparsers do not inherit parent option values.
+    if hasattr(args, "dir") and args.dir is None:
+        parent = argparse.ArgumentParser(add_help=False)
+        parent.add_argument("--dir", default=None)
+        parent.add_argument("--version", action="store_true")
+        parent.add_argument("--dry-run", action="store_true")
+        parent_args, _ = parent.parse_known_args(argv_list)
+        if parent_args.dir is not None:
+            args.dir = parent_args.dir
+        if parent_args.dry_run and not getattr(args, "dry_run", False):
+            args.dry_run = True
+
+    if getattr(args, "version", False) and not getattr(args, "command", None):
+        return cmd_version(args)
+
+    func = getattr(args, "func", None)
+    if func is None:
+        if getattr(args, "version", False):
+            return cmd_version(args)
+        parser.print_help()
+        return 2
+    try:
+        return int(func(args))
+    except VeltroCliError as exc:
+        return print_error(exc)
+    except KeyboardInterrupt:
+        print("interrupted", file=sys.stderr)
+        return 130
+    except Exception as exc:  # noqa: BLE001
+        return print_error(exc)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

veltro_cli/lib/__init__.py

@@ -0,0 +1,3 @@
+"""Library pieces shared by the CLI and thin script shims."""
+
+from __future__ import annotations

veltro_cli/lib/agent.py

@@ -0,0 +1,37 @@
+"""veltro agent enroll — agent-up + token drop ceremony."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from veltro_cli.lib.compose import ComposeClient
+from veltro_cli.lib.errors import VeltroCliError
+from veltro_cli.lib.paths import enrollment_token_dir, resolve_dir
+
+
+def enroll_agent(
+    *,
+    directory: str | Path | None = None,
+    environment: str | None = None,
+    client: ComposeClient | None = None,
+    dry_run: bool = False,
+) -> int:
+    root = resolve_dir(directory)
+    client = client or ComposeClient(root)
+    token_dir = enrollment_token_dir(root)
+    if not dry_run:
+        token_dir.mkdir(parents=True, exist_ok=True)
+    result = client.agent_up(dry_run=dry_run)
+    if result.returncode != 0:
+        raise VeltroCliError(
+            f"agent-up failed: {result.stderr.strip() or result.stdout.strip()}",
+            remedy="ensure the suite is up and an enrollment token will be dropped into "
+            f"{token_dir} (see README 'VectorFlow agent enrollment')",
+        )
+    # Token minting is owned by the seeder / VF API; we only start the agent profile.
+    if environment:
+        # Record intent for operators; actual enroll uses the token file.
+        marker = token_dir / "environment-name"
+        if not dry_run:
+            marker.write_text(environment + "\n", encoding="utf-8")
+    return 0

veltro_cli/lib/backup.py

@@ -0,0 +1,139 @@
+"""Suite backup / restore command handlers (plan §1.5).
+
+The implementation lives in ``scripts/veltro_backup.py`` so thin shims and the
+operator CLI share one stdlib module. This adapter translates ``veltro backup``
+/ ``veltro restore`` argparse namespaces into that library and maps failures to
+``VeltroCliError``.
+"""
+
+from __future__ import annotations
+
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+from veltro_cli.lib.errors import VeltroCliError
+from veltro_cli.lib.paths import resolve_dir
+
+# scripts/veltro_backup.py remains the single DR implementation. The installed
+# CLI resolves it from the selected suite directory; the source checkout paths
+# keep editable installs working.
+_HERE = Path(__file__).resolve()
+
+
+def _load_veltro_backup(root: Path):
+    import importlib.util
+
+    candidates = (
+        root / "scripts",
+        _HERE.parents[3] / "scripts",
+        _HERE.parents[2] / "scripts",
+        Path.cwd() / "scripts",
+    )
+    for scripts_dir in candidates:
+        path = scripts_dir / "veltro_backup.py"
+        if path.is_file():
+            spec = importlib.util.spec_from_file_location("veltro_backup", path)
+            if spec is None or spec.loader is None:
+                continue
+            mod = importlib.util.module_from_spec(spec)
+            sys.modules["veltro_backup"] = mod
+            spec.loader.exec_module(mod)
+            return mod
+    try:
+        import veltro_backup as mod  # type: ignore
+
+        return mod
+    except ImportError as exc:  # pragma: no cover
+        raise VeltroCliError(
+            "veltro_backup library not found",
+            remedy="run from a Veltro checkout that contains scripts/veltro_backup.py",
+        ) from exc
+
+
+def cmd_backup(args: Any) -> int:
+    """``veltro backup [--to PATH] [--auto] [--dir DIR]``."""
+    root = resolve_dir(getattr(args, "dir", None))
+    vb = _load_veltro_backup(root)
+    products = getattr(args, "products", None)
+    include_env = bool(getattr(args, "include_env", False))
+    passphrase = getattr(args, "passphrase", None)
+    schedule = getattr(args, "schedule", None)
+    if schedule:
+        sys.stdout.write(
+            vb.schedule_snippet(
+                schedule,
+                backup_dir=getattr(args, "backup_dir", None) or "/var/lib/veltro/backups",
+                keep=int(getattr(args, "keep", 7) or 7),
+            )
+        )
+        sys.stdout.write(
+            "Enable compose profile `backup` (compose/backup.yml) after writing crontab.\n"
+        )
+        return 0
+
+    output = getattr(args, "to", None)
+    if output is None and getattr(args, "auto", False):
+        stamp = datetime.now(timezone.utc).strftime("%Y%m%dT%H%M%S%fZ")
+        output = str(root / "backups" / f"veltro-backup-auto-{stamp}.tar")
+        Path(output).parent.mkdir(parents=True, exist_ok=True)
+
+    options = vb.BackupOptions(
+        root=root,
+        products=products,
+        output=Path(output) if output else None,
+        include_env=include_env,
+        passphrase=passphrase,
+        skip_optional=bool(getattr(args, "skip_optional", False)),
+    )
+    try:
+        path = vb.create_backup(options)
+    except vb.BackupError as exc:
+        raise VeltroCliError(
+            str(exc),
+            remedy="see docs/runbooks/backup-restore.md; ensure selected products are up and VELTRO_BACKUP_PASSPHRASE is set when keyrings exist",
+        ) from exc
+    print(f"wrote {path}")
+    return 0
+
+
+def cmd_restore(args: Any) -> int:
+    """``veltro restore PATH [--yes] [--dir DIR]``."""
+
+    archive = getattr(args, "path", None) or getattr(args, "archive", None)
+    if not archive:
+        raise VeltroCliError(
+            "restore requires an archive path",
+            remedy="veltro restore ./veltro-backup-….tar --yes",
+        )
+    root = resolve_dir(getattr(args, "dir", None))
+    vb = _load_veltro_backup(root)
+    options = vb.RestoreOptions(
+        root=root,
+        archive=Path(archive),
+        products=getattr(args, "products", None),
+        passphrase=getattr(args, "passphrase", None),
+        dry_run=bool(getattr(args, "dry_run", False)),
+        yes=bool(getattr(args, "yes", False)),
+        skip_start=bool(getattr(args, "skip_start", False)),
+    )
+    try:
+        result = vb.run_restore(options)
+    except vb.BackupError as exc:
+        raise VeltroCliError(
+            str(exc),
+            remedy="run with --dry-run to inspect the plan; refuse rules are documented in docs/runbooks/backup-restore.md",
+        ) from exc
+    import json
+
+    print(json.dumps(result, indent=2, sort_keys=True))
+    if result.get("status") == "restored":
+        return 0
+    if result.get("executable") is False:
+        return 2
+    return 0
+
+
+
+__all__ = ["cmd_backup", "cmd_restore"]