feat(cli): run declarative flows on the TUI (headless terminal fallback)

[joaomdmoura]

What

Normalizes declarative flow execution onto the CrewRunApp TUI, matching how declarative (JSON) crews and conversational flows already run. Headless contexts keep a direct-terminal path for deploy/CI.

Before this PR, crewai run used four surfaces: declarative crews → TUI, conversational flows → TUI, classic Python flows → terminal, declarative flows → terminal. This is the first step toward running everything on the TUI.

Behavior

• Interactive terminal → the TUI. A new STEPS panel shows each declarative flow method as a first-class step (driven by FlowStarted / MethodExecutionStarted/Finished/Failed events), labeled with its call type (crew/agent/expression/…) read from the flow definition. Crews/agents inside a method keep streaming in the main panel.
• Headless (deploy/CREWAI_DMN, piped output, CI, any non-TTY) → the existing direct-terminal kickoff + printed result. Gated by is_interactive().

Changes

• crew_run_tui.py: _run_flow_worker (runs flow.kickoff in a thread worker, reuses _on_crew_done/_on_crew_failed + _stringify_output); an _is_flow_run gate so crew rendering is byte-identical; flow-event subscriptions building _flow_steps; STEPS sidebar + flow-aware header.
• run_declarative_flow.py: is_interactive() branch → _run_declarative_flow_tui (instantiates EventListener, derives the method-type map from flow._definition, mirrors the crew exit-code + deploy-chain contract) or the existing terminal path.

Design note

The approved plan gated on is_dmn_mode_enabled() alone; I switched to is_interactive() (which folds in the DMN check and requires a TTY) so non-TTY runs — CI, pipes, CliRunner — never launch a TUI. This is strictly more correct and keeps existing headless flow tests green.

Out of scope / follow-ups

• Classic Python flows onto the TUI (next step toward full normalization).
• crewai deploy validation has a separate declarative-flow-entrypoint gap (DeployValidator._check_flow_entrypoint) unrelated to the TUI Deploy button, which uses skip_validate=True.

Testing

• New tests in test_crew_run_tui.py (flow dispatch, method-event STEPS build, completion sweep, end-to-end run_test() mount) and test_run_declarative_flow.py (TUI vs terminal routing, exit codes, deploy chaining, method-type extraction).
• Full lib/cli suite: 659 passed; the 7 remaining failures are pre-existing and unrelated (version-string drift + a git fetch mock in create/tools tests).
• ruff format/ruff check/mypy clean; mirrored lib/crewai/tests/cli still green.

🤖 Generated with Claude Code

---

Note

Medium Risk
Changes default CLI run behavior for interactive declarative flows and threads kickoff through the TUI; crew paths are gated but shared completion handlers and event subscriptions are extended.

Overview
Interactive declarative flows now launch CrewRunApp instead of printing kickoff output on the terminal, aligning them with JSON crews and conversational flows. Routing uses is_interactive() (TTY + not DMN); flows with @human_feedback still use the terminal path.

CrewRunApp gains a declarative-flow mode (_is_flow_run): _run_flow_worker runs flow.kickoff in a thread, subscribes to flow method events to build a STEPS sidebar (with call-type labels from the definition), and updates the header for active/paused methods without letting nested crew kickoffs rename the flow. Completion/failure messaging uses “flow” vs “crew” via _run_noun.

run_declarative_flow.py adds _run_declarative_flow_tui (starts EventListener, forces suppress_flow_events off for the TUI, post-run Rich summary, exit codes, quit → os._exit(130), deploy chaining like JSON crews).

ConsoleFormatter.print_panel skips Rich flow panels when is_tui_mode() is set so output does not corrupt the Textual UI.

Tests cover TUI vs terminal routing, STEPS/event behavior, and TUI-mode panel suppression.

^{Reviewed by Cursor Bugbot for commit 63a8378. Bugbot is set up for automated code reviews on this repo. Configure here.}

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

📝 Walkthrough

Walkthrough

Adds declarative flow TUI execution, flow-step tracking, TTY-based routing, and TUI-mode console suppression. Interactive flow runs now use the TUI, update step status from flow events, and print a post-run Rich summary with exit handling.

Changes

Declarative Flow TUI Support

Layer / File(s)	Summary
Flow state and gating in CrewRunApp lib/cli/src/crewai_cli/crew_run_tui.py	Adds flow-specific state fields and an _is_flow_run gate, and routes mount-time execution to the flow worker for flow runs.
Flow worker execution and step status updates lib/cli/src/crewai_cli/crew_run_tui.py	Runs declarative flow kickoff in _run_flow_worker, records the raw and display results, and marks active flow steps done or failed during overall completion handling.
Flow lifecycle event subscription lib/cli/src/crewai_cli/crew_run_tui.py	Imports declarative-flow event types and registers handlers that create and update _flow_steps from flow-start and method execution events.
STEPS panel and flow task header rendering lib/cli/src/crewai_cli/crew_run_tui.py	Renders a flow STEPS sidebar and flow-specific task header text instead of the standard task and agent display.
run_declarative_flow TUI routing and summary lib/cli/src/crewai_cli/run_declarative_flow.py	Routes interactive runs through a TUI path, keeps non-interactive kickoff behavior with error handling, and adds flow method type extraction plus post-TUI Rich summary rendering.
CrewRunApp flow tests lib/cli/tests/test_crew_run_tui.py	Adds tests for flow-run gating, flow step updates from method events, overlapping active methods, agent clearing, and an end-to-end flow completion path.
run_declarative_flow routing and helper tests lib/cli/tests/test_run_declarative_flow.py	Adds a headless default fixture, a fake TUI app helper, and tests for routing, exit behavior, deploy chaining, flow event suppression, and flow method type extraction.
TUI flow panel suppression lib/crewai/src/crewai/events/utils/console_formatter.py, lib/crewai/tests/utilities/test_console_formatter_tui_mode.py	Skips Rich flow panel printing in TUI mode and verifies flow and non-flow panel output behavior under TUI mode.

Sequence Diagram(s)

sequenceDiagram
  participant CLI as run_declarative_flow
  participant App as CrewRunApp
  participant Bus as EventListener
  participant Flow
  CLI->>App: _run_declarative_flow_tui(flow, inputs)
  App->>Bus: initialize listener
  App->>Flow: kickoff(inputs)
  Flow->>Bus: emit flow and method events
  Bus->>App: update _flow_steps and status
  App->>App: _print_flow_post_tui_summary()
  App-->>CLI: return _crew_result or exit

Loading

Suggested reviewers: greysonlalonde, gabemilani

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Title check	✅ Passed	The title clearly describes the main change: declarative flows now run on the TUI with a headless terminal fallback.
Description check	✅ Passed	The description is detailed and directly matches the changes in routing declarative flows to the TUI with terminal fallback.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch joaomdmoura/declarative-flow-tui

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@lib/cli/src/crewai_cli/crew_run_tui.py`:
- Around line 735-739: The flow header is reusing the previous method’s agent
because _current_agent is not reset when _current_method changes in
crew_run_tui.py. Update the method-switching logic around the block that
compares finished_name and selects the next active step so that whenever
_current_method is reassigned to a different step, _current_agent is also
cleared. Apply the same behavior in the other affected location tied to the
active-step transition so the header does not briefly show a stale agent until a
new agent event arrives.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 1aec9379-2d5c-462f-8c83-291abea76eb7

📥 Commits

Reviewing files that changed from the base of the PR and between 6b7529f and ec55c31.

📒 Files selected for processing (2)

• lib/cli/src/crewai_cli/crew_run_tui.py
• lib/cli/tests/test_crew_run_tui.py

🚧 Files skipped from review as they are similar to previous changes (1)

• lib/cli/tests/test_crew_run_tui.py

[coderabbitai]

🧹 Nitpick comments (1)

lib/cli/tests/test_crew_run_tui.py (1)

1644-1667: 🩺 Stability & Availability | 🔵 Trivial | 💤 Low value

Paused-event test correctly validates the _current_method contract.

The on_method_paused handler only calls _set_flow_step_status and does not explicitly set _current_method — it relies on the preceding MethodExecutionStartedEvent having set it. The test correctly emits the started event first and then asserts _current_method == "ask" after the pause, validating that _current_method persists across the pause transition as intended by the implementation comment ("_current_method stays pointed at it").

One consideration: if a MethodExecutionPausedEvent were ever emitted without a prior MethodExecutionStartedEvent, _current_method would be None. This is unlikely in practice (a method must start before it can pause), but you may want to add a defensive self._current_method = event.method_name in the paused handler if you want the contract to be self-contained. This is optional.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@lib/cli/tests/test_crew_run_tui.py` around lines 1644 - 1667, The
paused-event flow in CrewRunApp is currently only covered by a test that relies
on MethodExecutionStartedEvent having already set _current_method; if you want
the paused handler to be self-contained, update on_method_paused to also assign
_current_method from the event before calling _set_flow_step_status. Keep the
existing test in test_method_paused_marks_step_paused, and add or adjust
coverage to verify _current_method still points to the paused method even if the
paused event is handled directly.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Nitpick comments:
In `@lib/cli/tests/test_crew_run_tui.py`:
- Around line 1644-1667: The paused-event flow in CrewRunApp is currently only
covered by a test that relies on MethodExecutionStartedEvent having already set
_current_method; if you want the paused handler to be self-contained, update
on_method_paused to also assign _current_method from the event before calling
_set_flow_step_status. Keep the existing test in
test_method_paused_marks_step_paused, and add or adjust coverage to verify
_current_method still points to the paused method even if the paused event is
handled directly.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 0cfa35bc-3fee-41c0-be07-da7453b83826

📥 Commits

Reviewing files that changed from the base of the PR and between 46cae1a and 3a7196f.

📒 Files selected for processing (2)

• lib/cli/src/crewai_cli/crew_run_tui.py
• lib/cli/tests/test_crew_run_tui.py

🚧 Files skipped from review as they are similar to previous changes (1)

• lib/cli/src/crewai_cli/crew_run_tui.py

[cursor]

Cursor Bugbot has reviewed your changes using default effort and found 2 potential issues.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 3a7196f. Configure here.}