feat(cli): migrate flow-run command to cyclopts (wave 3b)

Native cyclopts implementation of all flow-run subcommands: inspect,
ls, delete, cancel, retry, logs, execute. Includes the
_get_flow_run_by_id_or_name helper for retry-by-name support.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: zzstoatzz

.github/workflows/python-tests.yaml

@@ -102,7 +102,7 @@ jobs:
           # PREFECT_CLI_FAST=1 so invoke_and_assert routes through the
           # cyclopts runner.  Only includes test files for commands that have
           # been migrated to cyclopts (config, profile, server, worker, shell,
-          # version).  Expand this list as more commands are migrated; when
+          # version, flow, flow-run).  Expand this list as more commands are migrated; when
           # the migration is complete replace with tests/cli/.
           - test-type:
               name: CLI Tests (Cyclopts)
@@ -115,6 +115,8 @@ jobs:
                 tests/cli/test_server_services.py
                 tests/cli/test_version.py
                 tests/cli/test_root.py
+                tests/cli/test_flow.py
+                tests/cli/test_flow_run.py
                 tests/cli/test_cyclopts_runner.py
                 tests/cli/test_cyclopts_parity.py
             database: "postgres:14"

benches/cli-bench.toml

@@ -60,3 +60,15 @@ name = "prefect shell --help (cyclopts)"
 args = ["env", "PREFECT_CLI_FAST=1", "prefect", "shell", "--help"]
 category = "startup"
 description = "shell help via cyclopts"
+
+[[commands]]
+name = "prefect flow ls (cyclopts)"
+args = ["env", "PREFECT_CLI_FAST=1", "prefect", "flow", "ls"]
+category = "startup"
+description = "flow ls via cyclopts"
+
+[[commands]]
+name = "prefect flow-run ls (cyclopts)"
+args = ["env", "PREFECT_CLI_FAST=1", "prefect", "flow-run", "ls"]
+category = "startup"
+description = "flow-run ls via cyclopts"

src/prefect/cli/__init__.py

@@ -26,6 +26,7 @@
 # to cyclopts instead of delegating to typer.
 _CYCLOPTS_COMMANDS: set[str] = {
     "config",
+    "flow-run",
     "profile",
     "server",
     "shell",

src/prefect/cli/_cyclopts/__init__.py

@@ -212,7 +212,6 @@ def app():
     "events",
     "experimental",
     "flow",
-    "flow-run",
     "global-concurrency-limit",
     "sdk",
     "task",
@@ -297,15 +296,9 @@ def flow_default(
 
 
 # --- flow-run ---
-flow_run_app = _delegated_app("flow-run", "Interact with flow runs.")
-_app.command(flow_run_app)
-
+from prefect.cli._cyclopts.flow_run import flow_run_app
 
-@flow_run_app.default
-def flow_run_default(
-    *tokens: Annotated[str, cyclopts.Parameter(show=False, allow_leading_hyphen=True)],
-):
-    _delegate("flow-run", tokens)
+_app.command(flow_run_app)
 
 
 # --- deployment ---