Add declarative Flow CLI support (#6294)

* Add declarative Flow CLI support

Currently, declarative flows can be loaded by the runtime, but the CLI
still treats them as an experimental definition file instead of a
first-class Flow project shape.

With this PR, `crewai create flow --declarative` scaffolds a YAML-backed
Flow project, and `crewai run`, `crewai flow kickoff`, and `crewai flow
plot` can run against the configured definition.

This also lets crew actions reference reusable crew definition files or
folders and override their inputs from the Flow definition, so
declarative flows can compose existing declarative crews without
inlining everything.

* Address code review comments

lib/cli/src/crewai_cli/run_declarative_flow.py

@@ -0,0 +1,212 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+import subprocess
+from typing import Any
+
+import click
+
+from crewai_cli.utils import build_env_with_all_tool_credentials
+
+
+def run_declarative_flow_in_project_env(
+    definition: str, inputs: str | None = None
+) -> None:
+    """Run a declarative flow inside the project's Python environment."""
+    if is_declarative_flow_project_env() or not _has_project_file():
+        run_declarative_flow(definition=definition, inputs=inputs)
+        return
+
+    if inputs is not None:
+        raise click.UsageError("--inputs is only supported with --definition")
+
+    _execute_declarative_flow_command(["uv", "run", "crewai", "flow", "kickoff"])
+
+
+def plot_declarative_flow_in_project_env(definition: str) -> None:
+    """Plot a declarative flow inside the project's Python environment."""
+    if is_declarative_flow_project_env() or not _has_project_file():
+        plot_declarative_flow(definition=definition)
+        return
+
+    _execute_declarative_flow_command(["uv", "run", "crewai", "flow", "plot"])
+
+
+def run_declarative_flow(definition: str, inputs: str | None = None) -> None:
+    """Run a declarative flow from a YAML/JSON file path."""
+    parsed_inputs = _parse_inputs(inputs)
+
+    try:
+        flow = load_declarative_flow(definition)
+        result = flow.kickoff(inputs=parsed_inputs)
+    except Exception as exc:
+        click.echo(
+            f"An error occurred while running the declarative flow: {exc}", err=True
+        )
+        raise SystemExit(1) from exc
+
+    click.echo(_format_result(result))
+
+
+def plot_declarative_flow(definition: str) -> None:
+    """Plot a declarative flow from a YAML/JSON file path."""
+    try:
+        flow = load_declarative_flow(definition)
+        flow.plot()
+    except Exception as exc:
+        click.echo(
+            f"An error occurred while plotting the declarative flow: {exc}", err=True
+        )
+        raise SystemExit(1) from exc
+
+
+def load_declarative_flow(definition: str) -> Any:
+    """Load a declarative Flow instance from a YAML/JSON file path."""
+    try:
+        from crewai.flow.flow import Flow
+        from crewai.flow.flow_definition import FlowDefinition
+    except ImportError as exc:
+        click.echo(
+            "Running declarative flows requires the full crewai package.",
+            err=True,
+        )
+        raise SystemExit(1) from exc
+
+    definition_path = Path(definition).expanduser()
+    definition_source = _read_declarative_flow_source(definition_path, definition)
+
+    flow_definition = _parse_declarative_flow(
+        FlowDefinition,
+        definition_source,
+        source_path=definition_path,
+    )
+    return Flow.from_definition(flow_definition)
+
+
+def configured_project_declarative_flow(
+    pyproject_data: dict[str, Any] | None = None,
+) -> str | None:
+    """Return the configured declarative flow source for flow projects."""
+    if pyproject_data is None:
+        try:
+            from crewai_cli.utils import read_toml
+
+            pyproject_data = read_toml()
+        except Exception:
+            return None
+
+    crewai_config = pyproject_data.get("tool", {}).get("crewai", {})
+    if crewai_config.get("type") != "flow":
+        return None
+    definition = crewai_config.get("definition")
+    if not isinstance(definition, str):
+        return None
+    return definition.strip() or None
+
+
+def _execute_declarative_flow_command(command: list[str]) -> None:
+    env = build_env_with_all_tool_credentials()
+
+    try:
+        subprocess.run(  # noqa: S603
+            command,
+            capture_output=False,
+            text=True,
+            check=True,
+            env=env,
+        )
+    except subprocess.CalledProcessError as e:
+        raise SystemExit(e.returncode) from e
+    except Exception as e:
+        click.echo(
+            f"An unexpected error occurred while running the declarative flow: {e}",
+            err=True,
+        )
+        raise SystemExit(1) from e
+
+
+def is_declarative_flow_project_env() -> bool:
+    import os
+
+    return os.environ.get("UV_RUN_RECURSION_DEPTH") is not None
+
+
+def _has_project_file(project_root: Path | None = None) -> bool:
+    root = project_root or Path.cwd()
+    return (root / "pyproject.toml").is_file()
+
+
+def _parse_inputs(inputs: str | None) -> dict[str, Any] | None:
+    if inputs is None:
+        return None
+
+    try:
+        parsed = json.loads(inputs)
+    except json.JSONDecodeError as exc:
+        click.echo(f"Invalid --inputs JSON: {exc}", err=True)
+        raise SystemExit(1) from exc
+
+    if not isinstance(parsed, dict):
+        click.echo("Invalid --inputs JSON: expected an object.", err=True)
+        raise SystemExit(1)
+
+    return parsed
+
+
+def _read_declarative_flow_source(path: Path, definition: str) -> str:
+    try:
+        if path.is_file():
+            source = _read_declarative_flow_file(path)
+        elif path.exists():
+            click.echo(
+                f"Invalid --definition path: {definition} is not a file.", err=True
+            )
+            raise SystemExit(1)
+        else:
+            click.echo(
+                f"Invalid --definition path: {definition} does not exist.", err=True
+            )
+            raise SystemExit(1)
+    except OSError as exc:
+        click.echo(f"Invalid --definition path: {definition} ({exc})", err=True)
+        raise SystemExit(1) from exc
+
+    return source
+
+
+def _read_declarative_flow_file(path: Path) -> str:
+    try:
+        source = path.read_text(encoding="utf-8")
+    except (OSError, UnicodeError) as exc:
+        click.echo(
+            f"Unable to read --definition path {path}: {exc}",
+            err=True,
+        )
+        raise SystemExit(1) from exc
+    return source
+
+
+def _parse_declarative_flow(
+    flow_definition_cls: type[Any], source: str, *, source_path: Path
+) -> Any:
+    if _looks_like_json(source):
+        return flow_definition_cls.from_json(source, source_path=source_path)
+
+    return flow_definition_cls.from_yaml(source, source_path=source_path)
+
+
+def _looks_like_json(source: str) -> bool:
+    stripped = source.lstrip()
+    return stripped.startswith("{")
+
+
+def _format_result(result: Any) -> str:
+    raw_result = getattr(result, "raw", result)
+    if isinstance(raw_result, str):
+        return raw_result
+
+    try:
+        return json.dumps(raw_result, default=str)
+    except TypeError:
+        return str(raw_result)