ENG-11433 Move reflex deploy out of the framework into the Cloud CLI

[FarhanAliRaza]

Closes ENG-11433.

reflex deploy lived in reflex/reflex.py, so cloud-specific code shipped inside the open-source framework. The implementation now lives in reflex-hosting-cli.

What changed

The command moved. reflex/reflex.py loses 245 lines; reflex_cli/v2/deploy.py gains 236. The framework contains no cloud code.

The import is guarded. reflex/reflex.py imports the moved command and falls back when it cannot:

try:
    from reflex_cli.v2.deploy import deploy
    from reflex_cli.v2.deployments import hosting_cli
except ImportError:
    cli.add_command(_missing_command("deploy"), name="deploy")
    cli.add_command(_missing_command("cloud"), name="cloud")
else:
    ...
    cli.add_command(deploy, name="deploy")
    cli.add_command(hosting_cli, name="cloud")

The typer conversion for cloud is unchanged from before; it just moved inside the else.

A missing package no longer fails opaquely. The stand-in is a real command of the same name. ignore_unknown_options plus a click.UNPROCESSED argument make it swallow every flag, so reflex deploy --app-name demo reports pip install reflex-hosting-cli instead of dying on "No such option". login and logout use the same helper on ImportError.

Standalone importability, fixed. deploy.py imported reflex.utils.cli_options, but reflex is not a dependency of reflex-hosting-cli, so importing the package on its own raised ModuleNotFoundError. The shared click options moved to reflex_base.utils.cli_options (adding click >=8.2 to reflex-base); reflex/utils/cli_options.py re-exports them for its existing callers.

The framework surface is one supported module (from review: the command body necessitated six reflex internals — constants, config, environment, reflex.reflex._init, utils.export, utils.prerequisites — that reflex would have to maintain forever). A new reflex/hosting.py is now the explicit interface the framework supports for the hosting CLI:

• prepare_deploy(ssr=...) — sets the DEPLOY compile context, reconciles --ssr with REFLEX_SSR, ensures the cwd is an initialized app, and returns DeployPrep(app_name, loglevel, ssr).
• export_for_deploy(...) — thin wrapper over export() that fills loglevel from config. The export_fn callback shape stays owned by the hosting CLI.

The command body imports nothing else from reflex, and test_deploy_uses_only_the_supported_framework_interface fails if any other reflex.* import sneaks back in. The --ssr/REFLEX_SSR arbitration that was duplicated between deploy and reflex export is now shared as exec.arbitrate_ssr().

Answers to the issue's open questions

How is it wired up? A guarded import, with reflex-hosting-cli still a required dependency. pip install reflex gives a working reflex deploy and nothing changes for existing users. Dropping the dependency would break them, which the "no breaking changes" bullet forbids.

An earlier revision of this PR used a reflex.cli_commands entry point group instead. It was removed: the only thing it bought over a direct import was that the framework did not write the name reflex_cli in its source, which did not justify 173 lines of discovery machinery and an indirection that hides where reflex deploy comes from. The cloud code is out of the framework either way, which is what the issue asks for.

What if the Cloud CLI is not installed? The command name still exists and reports what to install, as above.

No UX change

Verified rather than assumed: the pre-move command is reconstructed from the merge-base copy of reflex/reflex.py and diffed against the live one. All 23 parameters match on name, opts, secondary opts, type, default, multiple and required, and the rendered --help is identical. A separate check runs the command against a real app and asserts the 13 arguments still reach reflex_cli.v2.cli.deploy, and that --no-ssr and --exclude-from-backend still reach export() through the export_fn closure.

Note for the release

reflex deploy now lives in reflex_cli.v2.deploy, which older hosting CLI releases do not carry, so the floor must exclude them. That release is unpublished, so the pin is the workspace development version 0.1.70.post18.dev0 — the same convention reflex-hosting-cli already uses for its reflex-base pin. scripts/check_min_deps.py --check-dev-pins reflex fails while it stands, so it must be re-pinned to the published version before release.

One side effect: check_min_deps.py reflex cannot build the root package while the dev pin stands. [tool.hatch.build.hooks.custom] sets require-runtime-dependencies = true, so runtime deps resolve inside the isolated build environment, which the script's local editable overrides never reach. The other packages still check.

Hitchhiker: repair of #6918 against post-#6939 main

#6918 (reflex cloud whoami/token) merged with day-old green checks, after #6939 had made reflex-base an optional dependency of the hosting CLI, so main is red. Since this branch merges main anyway, the repair rides along:

• auth.py imported reflex_base.utils.log at module scope, breaking test_cli_imports_without_reflex_base; it now goes through the reflex_cli.utils.log shim.
• test_auth.py tripped pyright after the typer upgrade (typer now vendors click, so get_command()'s annotations are incompatible with click.testing.CliRunner); the unwrapped group is cast to click.Group, which is what _patch_typer's get_command actually returns at runtime.

Tests

reflex deploy had no dedicated tests before this branch.

• tests/units/reflex_cli/v2/test_deploy.py — registration, the flag surface, --help, a sys.meta_path probe that imports the module with every reflex import blocked (covers the standalone-import bug above), and the framework-interface boundary guard.
• tests/units/test_hosting.py — prepare_deploy (compile context, SSR arbitration, reinit path, returned config values) and export_for_deploy pass-through.
• tests/units/utils/test_exec.py — arbitrate_ssr both branches.
• tests/units/test_reflex.py — the cloud commands resolve into reflex_cli, and the stand-in reports the package rather than a usage error, including when the real command's flags are passed.

Full suite: 7763 passed, 17 skipped. Ruff clean. Pyright: 0 errors.

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.

[greptile-apps]

Greptile Summary

The PR moves reflex deploy into the hosting CLI while retaining explicit deploy and cloud registration in the framework and adding a supported deployment interface.

• Adds guarded hosting-command imports with informative missing-package placeholders.
• Introduces framework wrappers for deployment preparation and export.
• Shares SSR arbitration between export and deploy.
• Updates minimum-dependency validation to resolve unpublished sibling wheels through a local wheelhouse.
• Adds coverage for command compatibility, standalone imports, deployment preparation, and dependency resolution.

Confidence Score: 5/5

The PR appears safe to merge.

No blocking failure remains; the previously reported command-name collision is invalidated because the extension registration mechanism was removed and current HEAD registers the built-in hosting commands directly.

Important Files Changed

Filename	Overview
packages/reflex-hosting-cli/src/reflex_cli/v2/deploy.py	Moves the deploy command and its existing option surface into the hosting CLI, using only the new supported framework interface.
reflex/hosting.py	Adds the explicit framework boundary for deployment preparation and artifact export.
reflex/reflex.py	Replaces the obsolete extension-discovery approach with direct guarded registration of deploy and cloud commands.
reflex/utils/exec.py	Extracts SSR flag and environment-variable arbitration without changing its precedence.
scripts/check_min_deps.py	Builds unpublished sibling packages into a local wheelhouse so isolated build environments can resolve development pins.
tests/units/reflex_cli/v2/test_deploy.py	Verifies command registration, option compatibility, standalone importability, and the supported framework boundary.

_{Reviews (9): Last reviewed commit: "fix test cases for check_min_deps with n..." | Re-trigger Greptile}

[codspeed-hq]

Merging this PR will not alter performance

✅ 27 untouched benchmarks
⏩ 8 skipped benchmarks¹

---

_{Comparing FarhanAliRaza:farhan/eng-11433-move-reflex-deploy-command-out-of-the-reflex-package-into (4a732f7) with main (a33e02a)}

Footnotes

1. 8 benchmarks were skipped, so the baseline results were used instead. If they were deleted from the codebase, click here and archive them to remove them from the performance reports. ↩

[cubic-dev-ai]

4 issues found and verified against the latest diff

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="tests/units/utils/test_cli_plugins.py">

<violation number="1" location="tests/units/utils/test_cli_plugins.py:282">
P3: This reflex-side test hardcodes `reflex_cli.v2.deploy`, a private module path of the separate reflex-hosting-cli package, to assert eager loading. If the hosting CLI renames or reorganizes that module, this framework test fails spuriously even though the decoupling behavior is unchanged. Derive the expected module from the discovered entry points instead (e.g., check that every module referenced by the entry-point value is present in sys.modules) so the test stays coupled to the entry-point contract rather than to the hosting CLI's internal layout.</violation>
</file>

<file name="reflex/utils/cli_plugins.py">

<violation number="1" location="reflex/utils/cli_plugins.py:75">
P2: When a Typer entry point cannot be converted, `typer.main.get_command` aborts construction of the entire `reflex` CLI. Catch conversion errors, log the plugin failure, and continue so the remaining commands and fallback placeholders remain available.</violation>

<violation number="2" location="reflex/utils/cli_plugins.py:163">
P2: When a contributed entry point exists but fails to load (`entry_point.load()` raises) or does not resolve to a click command, the code still registers the "install/upgrade reflex-hosting-cli" placeholder. That message is wrong for an installed, current package, so the user is told to reinstall or upgrade an already-correct package instead of the real cause. Track names that already had an entry point separately from truly absent ones, and give those a diagnostic that reflects the actual failure (the load error already logged, or the non-click object type).</violation>

<violation number="3" location="reflex/utils/cli_plugins.py:173">
P2: Guard duplicate names before registering the command. Click stores commands by name, so this call overwrites an existing built-in or earlier contributed command; reject or skip collisions instead.</violation>
</file>

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>

[cubic-dev-ai]

All reported issues were addressed across 7 files (changes from recent commits).

<sub>Tip: Review your code locally with the cubic CLI to iterate faster.

Re-trigger cubic</sub>

[cubic-dev-ai]

All reported issues were addressed across 1 file (changes from recent commits).

<sub>Tip: Review your code locally with the cubic CLI to iterate faster.

Re-trigger cubic</sub>