floe-python 0.8.0__py3-none-any.whl

floe/__init__.py

@@ -0,0 +1,327 @@
+"""The public `floe` API, matching `crates/floe-python/python/floe/_floe.pyi` (Rust: `floe-python/src/`)."""
+
+import json
+from collections.abc import Callable
+from dataclasses import asdict, dataclass, field, replace
+from html import escape
+from importlib.metadata import version
+from pathlib import Path
+from typing import Any, cast
+
+__version__ = version(
+    "floe-python"
+)  # before the imports below: `floe.report.summary` reads it
+
+from floe import manifest as _manifest
+from floe import run as _run
+from floe.config.parse import parse_config
+from floe.config.profile import ProfileConfig, apply_profile, parse_profile
+from floe.config.project import RootConfig as _Root
+from floe.config.validate import validate_config
+from floe.config.vars import extract_config_env_vars as _env_vars
+from floe.config.vars import resolve_vars
+from floe.errors import (
+    FloeConfigError,
+    FloeError,
+    FloeIoError,
+    FloeRunError,
+    FloeStorageError,
+)
+from floe.lineage.observer import run_with_lineage
+from floe.maintain import FLOOR_DAYS, FLOOR_SNAPSHOTS, ORPHAN_DELAY_DAYS
+from floe.maintain import maintain as _maintain
+from floe.manifest_run import load_manifest, shown
+from floe.report.summary import id_path
+from floe.run.entity import state_uri
+from floe.run.events import (
+    EntityFinishedEvent,
+    EntityStartedEvent,
+    FileFinishedEvent,
+    FileStartedEvent,
+    LogEvent,
+    RunEvent,
+    RunFinishedEvent,
+    RunStartedEvent,
+    SchemaEvolutionAppliedEvent,
+)
+from floe.state import dump_state, read_state, reset
+from floe.storage.paths import normalize_local_path
+from floe.storage.types import StorageClient
+
+_observer: Callable[[RunEvent], None] | None = None
+
+
+def _debug(value: str) -> str:
+    return json.dumps(value, ensure_ascii=False)  # Rust `{:?}` quoting
+
+
+@dataclass(frozen=True, repr=False)
+class EntityConfig:
+    name: str
+    domain: str | None
+    source_format: str
+    source_path: str
+    source_storage: str | None
+    accepted_format: str
+    accepted_path: str
+    accepted_storage: str | None
+    incremental_mode: str
+
+    def __repr__(self) -> str:
+        return f"EntityConfig(name={_debug(self.name)}, source_format={_debug(self.source_format)}, accepted_format={_debug(self.accepted_format)})"  # fmt: skip
+
+
+@dataclass(frozen=True, repr=False)
+class RootConfig:
+    version: str
+    entities: list[EntityConfig]
+
+    @property
+    def entity_names(self) -> list[str]:
+        return [e.name for e in self.entities]
+
+    def __repr__(self) -> str:
+        return f"RootConfig(version={_debug(self.version)}, entities={len(self.entities)})"  # fmt: skip
+
+
+@dataclass(frozen=True, repr=False)
+class RunOutcome:
+    run_id: str
+    report_base_path: str | None
+    dry_run: bool
+    summary: dict[str, Any]
+    entity_reports: list[dict[str, Any]] = field(default_factory=list[dict[str, Any]])
+    dry_run_previews: list[dict[str, Any]] | None = None
+
+    def to_dict(self) -> dict[str, Any]:
+        return asdict(self)
+
+    def __repr__(self) -> str:
+        return f"RunOutcome(run_id={_debug(self.run_id)}, entities={len(self.entity_reports)}, dry_run={str(self.dry_run).lower()})"  # fmt: skip
+
+    def _repr_html_(self) -> str:
+        colors = {"success": "#2e7d32", "success_with_warnings": "#e65100"}
+        status = self.summary.get("run", {}).get("status", "unknown")
+        totals = self.summary.get("results", {})
+        rows = "".join(
+            f'<tr><td style="padding:4px 8px">{escape(e["name"])}</td>'
+            f'<td style="padding:4px 8px;color:{colors.get(e["status"], "#c62828")};font-weight:bold">{e["status"]}</td>'
+            f'<td style="padding:4px 8px;text-align:right">{e["results"]["accepted_total"]}</td>'
+            f'<td style="padding:4px 8px;text-align:right">{e["results"]["rejected_total"]}</td></tr>'
+            for e in self.summary.get("entities", [])
+        )  # fmt: skip
+        return (
+            '<div style="font-family:monospace;border:1px solid #ddd;border-radius:4px;padding:12px;max-width:600px">'
+            '<div style="margin-bottom:8px"><strong>RunOutcome</strong> '
+            f'<code style="color:#555">{escape(self.run_id)}</code> '
+            f'<span style="color:{colors.get(status, "#c62828")};font-weight:bold;margin-left:8px">{status}</span></div>'
+            f'<div style="margin-bottom:8px;color:#555">{totals.get("rows_total", 0)} rows &nbsp;·&nbsp; '
+            f'<span style="color:#2e7d32">{totals.get("accepted_total", 0)} accepted</span> &nbsp;·&nbsp; '
+            f'<span style="color:#c62828">{totals.get("rejected_total", 0)} rejected</span></div>'
+            '<table style="border-collapse:collapse;width:100%"><thead><tr style="border-bottom:1px solid #ddd">'
+            '<th style="padding:4px 8px;text-align:left">Entity</th><th style="padding:4px 8px;text-align:left">Status</th>'
+            '<th style="padding:4px 8px;text-align:right">Accepted</th><th style="padding:4px 8px;text-align:right">Rejected</th>'
+            f"</tr></thead><tbody>{rows}</tbody></table></div>"
+        )  # fmt: skip
+
+
+def _profile(
+    path: str | None, variables: dict[str, str] | None
+) -> ProfileConfig | None:
+    """Rust `load_optional_profile`: `profile_vars` extend the profile's, or stand alone."""
+    if path is None:
+        return None if variables is None else ProfileConfig("", {}, variables, None, None, None)  # fmt: skip
+    try:
+        profile = parse_profile(Path(path))
+    except FloeError as e:
+        raise FloeConfigError(f"failed to load profile {_debug(path)}: {e}") from e
+    return ProfileConfig(profile.name, profile.runner, profile.variables | (variables or {}),
+                         profile.catalogs, profile.storages, profile.lineage)  # fmt: skip
+
+
+def _load(config_path: str, profile: ProfileConfig | None = None) -> tuple[Path, _Root]:
+    path = Path(config_path).absolute()
+    root = parse_config(path, profile.variables if profile else None)
+    return path, apply_profile(root, profile) if profile else root
+
+
+def validate(
+    config_path: str,
+    entities: list[str] | None = None,
+    profile_vars: dict[str, str] | None = None,
+    profile_path: str | None = None,
+) -> None:
+    _, root = _load(config_path, _profile(profile_path, profile_vars))
+    validate_config(root)
+    _run.select_entities(root, entities or [])
+
+
+def run(
+    config_path: str,
+    entities: list[str] | None = None,
+    dry_run: bool = False,
+    run_id: str | None = None,
+    full_refresh: bool = False,
+    profile_vars: dict[str, str] | None = None,
+    profile_path: str | None = None,
+) -> RunOutcome:
+    profile = _profile(profile_path, profile_vars)
+    if profile:  # Rust `run_with_runtime`: profile vars resolved against the config's env vars first
+        profile = replace(profile, variables=resolve_vars(profile.variables, {}, _env_vars(Path(config_path).absolute())))  # fmt: skip
+    path, root = _load(config_path, profile)
+    # as `floe run -c`: OpenLineage events, and validation after the observer so lineage sees a failure
+    out = run_with_lineage(
+        path, root, root.entities, str(path), _emit, validate=True, run_id=run_id,
+        entities=entities or [], dry_run=dry_run, full_refresh=full_refresh,
+    )  # fmt: skip
+    return _outcome(root, entities, out)
+
+
+def maintain(
+    config_path: str,
+    entities: list[str] | None = None,
+    older_than_days: int = FLOOR_DAYS,
+    retain_last: int = FLOOR_SNAPSHOTS,
+    profile_vars: dict[str, str] | None = None,
+    profile_path: str | None = None,
+    orphan_delay_days: int = ORPHAN_DELAY_DAYS,
+    dry_run: bool = False,
+    compact: bool = False,
+    experimental: bool = False,
+) -> list[dict[str, Any]]:
+    """`floe maintain`: expire Iceberg snapshots behind the retention floor (7 days, 10 snapshots), then remove orphan files."""
+    path, root = _load(config_path, _profile(profile_path, profile_vars))
+    return _maintain(path, root, entities or [], older_than_days, retain_last, orphan_delay_days, dry_run, compact, experimental)  # fmt: skip
+
+
+def run_manifest(
+    manifest_path: str,
+    entities: list[str] | None = None,
+    dry_run: bool = False,
+    run_id: str | None = None,
+    full_refresh: bool = False,
+) -> RunOutcome:
+    """`floe run --manifest`, OpenLineage included; the manifest was validated when it was generated."""
+    root, observed, path = load_manifest(manifest_path)
+    out = run_with_lineage(
+        path, root, observed, "", _emit, validate=False, run_id=run_id,
+        entities=entities or [], dry_run=dry_run, full_refresh=full_refresh,
+        config_uri=shown(manifest_path),
+    )  # fmt: skip
+    return _outcome(root, entities, out)
+
+
+def build_manifest(
+    config_path: str,
+    profile_path: str | None = None,
+    *,
+    deterministic: bool = True,
+    manifest_name: str | None = None,
+    default_domain: str | None = None,
+    path_mode: str = "default",
+    runtime: str | None = None,
+    manifest_uri: str | None = None,
+    entities: list[str] | None = None,
+) -> dict[str, Any]:
+    """What `floe manifest generate` writes; `manifest_uri` is a remote `-o` (where it is deployed)."""
+    from floe._cli import _load as _cli_load  # pyright: ignore[reportPrivateUsage] -- the CLI's config loading, so both build the same manifest
+    from floe._cli import _realpath  # pyright: ignore[reportPrivateUsage] -- as above
+
+    path = _realpath(config_path)
+    profile = parse_profile(_realpath(profile_path)) if profile_path else None
+    root = _cli_load(path, profile)
+    validate_config(root)
+    options = _manifest.Options(
+        config_path, deterministic, manifest_name, default_domain, path_mode,
+        runtime, manifest_uri, profile_path, profile,
+    )  # fmt: skip
+    return _manifest.build_manifest(root, path, options, entities or [])
+
+
+def _emit(event: dict[str, Any]) -> None:
+    if _observer:
+        _observer(cast(RunEvent, event))
+
+
+def _outcome(
+    root: _Root, entities: list[str] | None, out: _run.RunOutcome
+) -> RunOutcome:
+    base = out.summary["report"]["path"]
+    if out.dry_run is None:
+        return RunOutcome(out.run_id, base, False, out.summary, out.entity_reports)
+    previews = [
+        {
+            "name": e.id, "input_path": e.source.path, "input_format": e.source.format,
+            "accepted_path": e.sink.accepted.path, "accepted_format": e.sink.accepted.format,
+            "rejected_path": e.sink.rejected and e.sink.rejected.path,
+            "rejected_format": e.sink.rejected and e.sink.rejected.format,
+            "archive_path": e.sink.archive.path if e.sink.archive else "",
+            "archive_storage": e.sink.archive and e.sink.archive.storage,
+            "report_file": f"{out.run_dir}/{id_path(e)}/run.json",
+            "scanned_files": out.dry_run[e.id],
+        }
+        for e in _run.select_entities(root, entities or [])
+    ]  # fmt: skip
+    return RunOutcome(out.run_id, base, True, out.summary, [], previews)
+
+
+def load_config(config_path: str) -> RootConfig:
+    _, root = _load(config_path)
+    return RootConfig(root.version, [
+        EntityConfig(e.name, e.domain, e.source.format, e.source.path, e.source.storage,
+                     e.sink.accepted.format, e.sink.accepted.path, e.sink.accepted.storage,
+                     e.incremental_mode)
+        for e in root.entities
+    ])  # fmt: skip
+
+
+def extract_config_env_vars(config_path: str) -> dict[str, str]:
+    return _env_vars(Path(config_path))
+
+
+def _state(config_path: str, entity_name: str) -> tuple[str, str, str, StorageClient]:
+    path, root = _load(config_path)
+    [entity] = _run.select_entities(root, [entity_name])
+    uri, client = state_uri(entity, normalize_local_path(path.parent), root.storages)
+    return entity.name, entity.incremental_mode, uri, client
+
+
+def inspect_entity_state(config_path: str, entity_name: str) -> dict[str, Any]:
+    name, mode, uri, client = _state(config_path, entity_name)
+    state = read_state(client, uri, name)
+    return {
+        "entity_name": name,
+        "incremental_mode": mode,
+        "path_uri": uri,
+        "path_local": uri.removeprefix("local://")
+        if uri.startswith("local://")
+        else None,
+        "state": json.loads(dump_state(state)) if state else None,
+    }
+
+
+def reset_entity_state(config_path: str, entity_name: str) -> bool:
+    name, _, uri, client = _state(config_path, entity_name)
+    return reset(client, uri, name)
+
+
+def set_observer(callback: Callable[[RunEvent], None]) -> bool:
+    global _observer
+    if not callable(callback):
+        raise TypeError("observer callback must be callable")
+    _observer = callback
+    return True
+
+
+def clear_observer() -> None:
+    global _observer
+    _observer = None
+
+
+__all__ = [
+    "EntityConfig", "EntityFinishedEvent", "EntityStartedEvent", "FileFinishedEvent", "FileStartedEvent",
+    "FloeConfigError", "FloeError", "FloeIoError", "FloeRunError", "FloeStorageError", "LogEvent", "RootConfig",
+    "RunEvent", "RunFinishedEvent", "RunOutcome", "RunStartedEvent", "SchemaEvolutionAppliedEvent", "__version__",
+    "build_manifest", "clear_observer", "extract_config_env_vars", "inspect_entity_state", "load_config", "maintain", "reset_entity_state", "run",
+    "run_manifest", "set_observer", "validate",
+]  # fmt: skip

floe/__main__.py

@@ -0,0 +1,5 @@
+import sys
+
+from floe._cli import main
+
+sys.exit(main())

floe/_cli.py

@@ -0,0 +1,302 @@
+import argparse
+import json
+import os
+import sys
+from datetime import UTC, datetime
+from pathlib import Path
+
+from floe import __version__, build_manifest
+from floe._cli_output import Console, run_output
+from floe.add_entity import add_entity
+from floe.config.parse import parse_config
+from floe.config.profile import (
+    API_VERSION,
+    KIND,
+    ProfileConfig,
+    apply_profile,
+    parse_profile,
+)
+from floe.config.project import RootConfig
+from floe.config.validate import validate_config
+from floe.config.vars import extract_config_env_vars, resolve_vars
+from floe.errors import FloeConfigError, FloeError, FloeIoError
+from floe.lineage.observer import run_with_lineage
+from floe.maintain import FLOOR_DAYS, FLOOR_SNAPSHOTS, ORPHAN_DELAY_DAYS, maintain
+from floe.manifest_run import load_manifest, shown
+from floe.run import select_entities
+from floe.run.entity import state_uri
+from floe.state import dump_state, read_state, reset
+from floe.storage.paths import normalize_local_path, parse_s3_uri
+from floe.storage.s3 import S3Client
+
+
+def _realpath(path: str) -> Path:
+    try:
+        return Path(os.path.realpath(path, strict=True))
+    except OSError as e:
+        raise FloeIoError(f"{e.strerror} (os error {e.errno})") from e
+
+
+def _load(path: Path, profile: ProfileConfig | None) -> RootConfig:
+    variables = (
+        resolve_vars(profile.variables, {}, extract_config_env_vars(path))
+        if profile
+        else {}
+    )
+    root = parse_config(path, variables)
+    if profile:
+        root = apply_profile(root, profile)
+    return root
+
+
+def _validate(args: argparse.Namespace) -> int:
+    profile = parse_profile(_realpath(args.profile)) if args.profile else None
+    if args.config is None:
+        if profile is None:
+            raise FloeConfigError(
+                "floe validate requires --config unless --profile is provided"
+            )
+        print(f"Profile valid: {profile.name}")
+        print(f"Schema: {API_VERSION}/{KIND}")
+        print(f"Catalogs: {len(profile.catalogs.definitions) if profile.catalogs else 0}")  # fmt: skip
+        return 0
+    path = _realpath(args.config)
+    root = _load(path, profile)
+    validate_config(root)
+    select_entities(root, args.entities)
+    print(f"Config valid: {path}")
+    print(f"Version: {root.version}")
+    print(f"Report: {root.report.path}")
+    print(f"Entities: {len(root.entities)}")
+    for e in root.entities:
+        print(f"Entity: {e.name}")
+        print(f"  Source: {e.source.format} ({e.source.path})")
+        print(f"  Sink accepted: {e.sink.accepted.format} ({e.sink.accepted.path})")
+        if e.sink.rejected:
+            print(f"  Sink rejected: {e.sink.rejected.format} ({e.sink.rejected.path})")  # fmt: skip
+        print(f"  Severity: {e.policy.severity}")
+    profile_arg = f" -p {os.path.realpath(args.profile)}" if args.profile else ""
+    print(f"Next: floe run -c {path}{profile_arg}")
+    return 0
+
+
+def _run(args: argparse.Namespace) -> int:
+    run_id = args.run_id or datetime.now(UTC).strftime("%Y-%m-%dT%H-%M-%S.%fZ")
+    console = Console(args.log_format, run_id)
+    if args.manifest is not None:  # Rust ignores `-p` here: the manifest is compiled
+        try:  # Rust logs a manifest that fails to load after a `run_started`
+            root, observed, path = load_manifest(args.manifest)
+        except FloeIoError as e:  # Rust: a bare io error, logged with code `error`
+            console.failed(FloeError(str(e)), args.manifest)
+            raise
+        except FloeError as e:
+            console.failed(e, args.manifest)
+            raise
+        config_uri = shown(args.manifest)  # as typed, as Rust
+        job = ""  # Rust names the lineage job `floe-run` (or `job_name`)
+    elif args.config is None:
+        raise FloeConfigError("one of --config or --manifest is required")
+    else:
+        profile = parse_profile(_realpath(args.profile)) if args.profile else None
+        try:  # Rust logs a missing config without `run_started`
+            path = _realpath(args.config)
+        except FloeError as e:
+            console.failed(e, None)
+            raise
+        try:
+            root = _load(path, profile)
+        except FloeError as e:
+            console.failed(e, str(path))
+            raise
+        observed, job, config_uri = root.entities, str(path), None
+    try:
+        outcome = run_with_lineage(
+            path, root, observed, job, console, validate=args.manifest is None,
+            run_id=run_id, entities=args.entities, dry_run=args.dry_run, full_refresh=args.full_refresh,
+            config_uri=config_uri,
+        )  # fmt: skip
+    except FloeError as e:
+        console.failed(e, config_uri or str(path))
+        raise
+    mode = "quiet" if args.quiet else "verbose" if args.verbose else "default"
+    out = run_output(outcome, root.entities, mode, console.timings)
+    print(out, file=sys.stderr if args.log_format == "json" else sys.stdout)
+    return 0 if args.dry_run else outcome.summary["run"]["exit_code"]
+
+
+def _manifest(args: argparse.Namespace) -> int:
+    remote = "://" in args.output
+    if remote and not args.output.startswith("s3://"):  # D1: gcs and adls are dropped
+        raise FloeConfigError(f"remote manifest output is not supported yet: {args.output}")  # fmt: skip
+    manifest = build_manifest(
+        args.config, args.profile, deterministic=args.deterministic,
+        manifest_name=args.manifest_name, default_domain=args.default_domain,
+        path_mode=args.manifest_path_mode, runtime=args.runtime,
+        manifest_uri=args.output if remote else None,  # a remote `-o` is where the manifest is deployed
+        entities=args.entities,
+    )  # fmt: skip
+    text = json.dumps(manifest, indent=2, ensure_ascii=False)
+    if args.output == "-":
+        print(text)
+        return 0
+    if (
+        remote
+    ):  # one PutObject: readers see the old or the new manifest, never a partial one
+        S3Client(parse_s3_uri(args.output)[0]).write(args.output, text.encode())
+    else:
+        out = Path(args.output)
+        out.parent.mkdir(parents=True, exist_ok=True)
+        tmp = out.with_name(f".{out.name}.tmp")
+        tmp.write_text(text)
+        tmp.replace(out)
+    print(f"Manifest written: {args.output}")
+    return 0
+
+
+def _add_entity(args: argparse.Namespace) -> int:
+    config = (
+        args.config if not os.path.exists(args.config) else str(_realpath(args.config))
+    )
+    added = add_entity(
+        config, args.input, args.format, args.name, args.domain,
+        args.source_ref, args.resource, args.output, args.dry_run,
+    )  # fmt: skip
+    if added.rendered is not None:
+        print(f"# add-entity dry run (no file written)\n# entity: {added.name}")
+        for note in added.notes:
+            print(f"# note: {note}")
+        print(added.rendered)
+    else:
+        print(f"Entity added: {added.name} (format={added.format}, columns={added.columns})")  # fmt: skip
+        print(f"Config written: {added.output}")
+        for note in added.notes:
+            print(f"Note: {note}")
+    return 0
+
+
+def _state(args: argparse.Namespace) -> int:
+    if args.state_command == "reset" and not args.yes:
+        raise FloeConfigError("state reset is destructive, rerun with --yes to confirm")
+    profile = parse_profile(_realpath(args.profile)) if args.profile else None
+    path = _realpath(args.config)
+    root = _load(path, profile)
+    [entity] = select_entities(root, [args.entity])
+    uri, client = state_uri(entity, normalize_local_path(path.parent), root.storages)
+    if args.state_command == "reset":
+        removed = reset(client, uri, entity.name)
+        print(f"Entity: {entity.name}\nState path: {uri}")
+        print(f"State reset: {'removed state object' if removed else 'no state object found'}")  # fmt: skip
+        return 0
+    state = read_state(client, uri, entity.name)
+    print(f"Entity: {entity.name}\nIncremental mode: {entity.incremental_mode}\nState path: {uri}")  # fmt: skip
+    if state is None:
+        print("State exists: no\nTracked files: 0\nActive claims: 0")
+        return 0
+    print(f"State exists: yes\nTracked files: {len(state.files)}\nActive claims: {len(state.claims)}")  # fmt: skip
+    print(f"Updated at: {state.updated_at or '(unknown)'}\n")
+    print(dump_state(state).decode())
+    return 0
+
+
+def _maintain(args: argparse.Namespace) -> int:
+    profile = parse_profile(_realpath(args.profile)) if args.profile else None
+    path = _realpath(args.config)
+    results = maintain(
+        path, _load(path, profile), args.entities, args.older_than_days, args.retain_last,
+        args.orphan_delay_days, args.dry_run, args.compact, args.experimental,
+    )  # fmt: skip
+    expired, removed = ("to expire", "to remove") if args.dry_run else ("expired", "removed")  # fmt: skip
+    for r in results:
+        print(f"Entity: {r['entity']}\n  Table: {r['table']}")
+        if c := r["compaction"]:
+            print(f"  Compaction: {c['rewritten_data_files']} data files and {c['removed_delete_files']} delete files rewritten into {c['added_data_files']} data file(s)")  # fmt: skip
+        print(f"  Snapshots {expired}: {r['expired_snapshots']}, kept: {r['kept_snapshots']}")  # fmt: skip
+        print(f"  Orphan files {removed}: {len(r['orphan_files'])} ({r['orphan_bytes']} bytes)")  # fmt: skip
+        for uri in r["orphan_files"] if args.dry_run else ():
+            print(f"    {uri}")
+    return 0
+
+
+def _parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="floe")
+    parser.add_argument("--version", action="version", version=f"floe {__version__}")
+    commands = parser.add_subparsers(dest="command", required=True)
+    validate = commands.add_parser("validate")
+    run = commands.add_parser("run")
+    run_source = run.add_mutually_exclusive_group()
+    run_source.add_argument("-c", "--config")
+    run_source.add_argument("--manifest")
+    run.add_argument("--run-id")
+    run.add_argument("-F", "--full-refresh", action="store_true")
+    run.add_argument("--dry-run", action="store_true")
+    run.add_argument("--log-format", choices=("off", "text", "json"), default="off")
+    verbosity = run.add_mutually_exclusive_group()
+    verbosity.add_argument("--quiet", action="store_true")
+    verbosity.add_argument("--verbose", action="store_true")
+    validate.add_argument("-c", "--config")
+    for command in (validate, run):
+        command.add_argument("--entities", action="extend", type=lambda s: s.split(","), default=[])  # fmt: skip
+        command.add_argument("-p", "--profile")
+    generate = (
+        commands.add_parser("manifest")
+        .add_subparsers(dest="manifest_command", required=True)
+        .add_parser("generate")
+    )
+    generate.add_argument("-c", "--config", required=True)
+    generate.add_argument("-o", "--output", required=True)
+    generate.add_argument("-p", "--profile")
+    generate.add_argument("--deterministic", action="store_true")
+    generate.add_argument("--manifest-name")
+    generate.add_argument("--default-domain")
+    generate.add_argument("--manifest-path-mode", default="default")
+    generate.add_argument("--runtime", choices=("image", "cli"))
+    generate.add_argument(
+        "--entities", action="extend", default=[], type=lambda v: v.split(",")
+    )
+    add = commands.add_parser("add-entity")
+    add.add_argument("-c", "--config", required=True)
+    add.add_argument("--input", required=True)
+    add.add_argument("--format", choices=("csv", "json", "parquet"))
+    for flag in ("--name", "--domain", "--resource", "--output"):
+        add.add_argument(flag)
+    add.add_argument("--source", dest="source_ref")
+    add.add_argument("--dry-run", action="store_true")
+    state = commands.add_parser("state").add_subparsers(dest="state_command", required=True)  # fmt: skip
+    for name in ("inspect", "reset"):
+        command = state.add_parser(name)
+        command.add_argument("-c", "--config", required=True)
+        command.add_argument("--entity", required=True)
+        command.add_argument("-p", "--profile")
+        if name == "reset":
+            command.add_argument("--yes", action="store_true")
+    maintain = commands.add_parser("maintain")
+    maintain.add_argument("-c", "--config", required=True)
+    maintain.add_argument("-p", "--profile")
+    maintain.add_argument("--entities", action="extend", type=lambda s: s.split(","), default=[])  # fmt: skip
+    maintain.add_argument("--older-than-days", type=int, default=FLOOR_DAYS)
+    maintain.add_argument("--retain-last", type=int, default=FLOOR_SNAPSHOTS)
+    maintain.add_argument("--orphan-delay-days", type=int, default=ORPHAN_DELAY_DAYS)
+    maintain.add_argument("--dry-run", action="store_true")
+    maintain.add_argument("--compact", action="store_true")
+    maintain.add_argument("--experimental", action="store_true")
+    return parser
+
+
+def main() -> int:
+    args, extra = _parser().parse_known_args()
+    if extra:  # clap's wording for an unknown flag
+        print(f"error: unexpected argument '{extra[0]}' found\n\nFor more information, try '--help'.", file=sys.stderr)  # fmt: skip
+        return 2
+    try:
+        if args.command == "manifest":
+            return _manifest(args)
+        if args.command == "add-entity":
+            return _add_entity(args)
+        if args.command == "state":
+            return _state(args)
+        if args.command == "maintain":
+            return _maintain(args)
+        return _run(args) if args.command == "run" else _validate(args)
+    except FloeError as e:
+        print(f"Error: {e}", file=sys.stderr)
+        return 1