veltro-cli 0.15.7__tar.gz

veltro_cli-0.15.7/PKG-INFO

@@ -0,0 +1,40 @@
+Metadata-Version: 2.4
+Name: veltro-cli
+Version: 0.15.7
+Summary: Operator CLI for the Veltro security operations suite (Compose + Helm).
+Author: Veltro Security
+License: AGPL-3.0-only
+Project-URL: Homepage, https://github.com/veltrosecurity/veltro
+Project-URL: Documentation, https://github.com/veltrosecurity/veltro#readme
+Project-URL: Repository, https://github.com/veltrosecurity/veltro
+Project-URL: Issues, https://github.com/veltrosecurity/veltro/issues
+Keywords: veltro,security,soc,compose,helm
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: System Administrators
+Classifier: License :: OSI Approved :: GNU Affero General Public License v3
+Classifier: Operating System :: POSIX
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Security
+Classifier: Topic :: System :: Systems Administration
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# veltro-cli
+
+Stdlib-only operator CLI for the Veltro suite. Every Veltro release publishes
+it at the release's version. Install a release with:
+
+```sh
+curl -fsSL https://raw.githubusercontent.com/veltrosecurity/veltro/vX.Y.Z/install.sh \
+  | VELTRO_RELEASE=X.Y.Z sh
+```
+
+or `pip install veltro-cli==X.Y.Z` and `veltro install --suite-version X.Y.Z`.
+Leave the version out to take the newest release.
+
+Requires Python ≥ 3.10 and Docker Compose ≥ 2.20 on the host.

veltro_cli-0.15.7/README.md

@@ -0,0 +1,14 @@
+# veltro-cli
+
+Stdlib-only operator CLI for the Veltro suite. Every Veltro release publishes
+it at the release's version. Install a release with:
+
+```sh
+curl -fsSL https://raw.githubusercontent.com/veltrosecurity/veltro/vX.Y.Z/install.sh \
+  | VELTRO_RELEASE=X.Y.Z sh
+```
+
+or `pip install veltro-cli==X.Y.Z` and `veltro install --suite-version X.Y.Z`.
+Leave the version out to take the newest release.
+
+Requires Python ≥ 3.10 and Docker Compose ≥ 2.20 on the host.

veltro_cli-0.15.7/pyproject.toml

@@ -0,0 +1,45 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "veltro-cli"
+version = "0.15.7"
+description = "Operator CLI for the Veltro security operations suite (Compose + Helm)."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "AGPL-3.0-only" }
+authors = [{ name = "Veltro Security" }]
+keywords = ["veltro", "security", "soc", "compose", "helm"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Environment :: Console",
+  "Intended Audience :: System Administrators",
+  "License :: OSI Approved :: GNU Affero General Public License v3",
+  "Operating System :: POSIX",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Topic :: Security",
+  "Topic :: System :: Systems Administration",
+]
+# Stdlib only — no third-party runtime dependencies.
+dependencies = []
+
+[project.urls]
+Homepage = "https://github.com/veltrosecurity/veltro"
+Documentation = "https://github.com/veltrosecurity/veltro#readme"
+Repository = "https://github.com/veltrosecurity/veltro"
+Issues = "https://github.com/veltrosecurity/veltro/issues"
+
+[project.scripts]
+veltro = "veltro_cli.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["veltro_cli*"]
+
+[tool.setuptools.package-data]
+veltro_cli = ["py.typed"]

veltro_cli-0.15.7/setup.cfg

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

veltro_cli-0.15.7/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-0.15.7/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-0.15.7/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-0.15.7/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-0.15.7/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