refactor(hosting-cli): rename gcp deploy to reflex cloud deploy --gcp, add docs

Flatten the `gcp` group into a single `deploy` command with a `--gcp`
target flag so the surface can grow to other targets without nesting.
`--gcp-project` becomes optional at the Click level and is validated
in-function so the missing-target error fires first.

Add a hosting doc (with Enterprise-only callout) covering prerequisites,
options, what gets created in the GCP project, the env-allowlist
security model, CI usage, and troubleshooting. Wire it into the
sidebar's Self Hosting section and add `Gcp` -> `GCP` to the sidebar
acronym map.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: Kastier1

docs/app/reflex_docs/pages/docs/__init__.py

@@ -149,6 +149,7 @@ def get_previews_from_frontmatter(filepath: str) -> dict[str, str]:
     "docs/events/special_events.md": "Special Events Docs",
     "docs/library/graphing/general/tooltip.md": "Graphing Tooltip",
     "docs/recipes/content/grid.md": "Grid Recipe",
+    "docs/hosting/deploy-to-gcp.md": "Deploy to GCP",
 }
 
 

docs/app/reflex_docs/templates/docpage/sidebar/sidebar_items/item.py

@@ -13,7 +13,14 @@ def create_item(route: Route, children=None):
         # For "Overview", we want to keep the qualifier prefix ("Components overview")
         alt_name_for_next_prev = name if name.endswith("Overview") else ""
         # Capitalize acronyms
-        acronyms = {"Api": "API", "Cli": "CLI", "Ide": "IDE", "Mcp": "MCP", "Ai": "AI"}
+        acronyms = {
+            "Api": "API",
+            "Cli": "CLI",
+            "Ide": "IDE",
+            "Mcp": "MCP",
+            "Ai": "AI",
+            "Gcp": "GCP",
+        }
         name = re.sub(
             r"\b(" + "|".join(acronyms.keys()) + r")\b",
             lambda m: acronyms[m.group(0)],

docs/app/reflex_docs/templates/docpage/sidebar/sidebar_items/learn.py

@@ -250,6 +250,7 @@ def get_sidebar_items_hosting():
             children=[
                 hosting.self_hosting,
                 hosting.databricks,
+                hosting.deploy_to_gcp,
             ],
         ),
     ]

docs/hosting/deploy-to-gcp.md

@@ -0,0 +1,124 @@
+```python exec
+import reflex as rx
+```
+
+# Deploy to GCP Cloud Run
+
+The `reflex cloud deploy --gcp` command deploys a Reflex app to your own [Google Cloud Run](https://cloud.google.com/run) service. Reflex Cloud fetches a Cloud Run-ready Dockerfile and a `gcloud` deploy script, writes the Dockerfile into your project, and runs the script against the Google Cloud project you specify. The image is built on Cloud Build (so it works from any host OS, including Apple Silicon) and pushed to Artifact Registry.
+
+```md alert info
+# Enterprise tier only.
+
+Self-deploying to GCP Cloud Run is part of the **Enterprise tier** of Reflex Cloud. The control plane will return `403` to non-Enterprise tokens, and the CLI surfaces a clear error pointing at this. Contact [sales@reflex.dev](mailto:sales@reflex.dev) to upgrade.
+```
+
+## Prerequisites
+
+Before running the command, install and authenticate the local tools the deploy script invokes:
+
+- `gcloud` — install from the [Google Cloud SDK docs](https://cloud.google.com/sdk/docs/install), then run:
+  - `gcloud auth login`
+  - `gcloud auth application-default login`
+- `docker` — required by `gcloud builds submit` for source upload.
+- `bash` — used to run the deploy script.
+
+You also need:
+
+- A GCP project with **billing enabled**. Without it, `gcloud services enable` fails with `UREQ_PROJECT_BILLING_NOT_FOUND`.
+- An Enterprise-tier Reflex Cloud subscription and a logged-in Reflex CLI (`reflex login`).
+
+## Quick start
+
+From the root of your Reflex app:
+
+```bash
+reflex cloud deploy --gcp \
+    --gcp-project my-gcp-project-id \
+    --service-name my-reflex-app
+```
+
+The CLI will:
+
+1. Authenticate against Reflex Cloud and fetch the deploy manifest (Dockerfile + `gcloud` script).
+2. Print the manifest so you can review it.
+3. Write a `Dockerfile` into your project (after asking, if one already exists).
+4. Ask for confirmation, then run the `gcloud` script: enable the required APIs, create the Artifact Registry repository, build the image on Cloud Build, and deploy a public Cloud Run service.
+
+When it's done, you'll get a service URL like `https://my-reflex-app-<project-number>.us-central1.run.app`.
+
+## Options
+
+| Option | Default | Description |
+| --- | --- | --- |
+| `--gcp` | _(required)_ | Selects the GCP Cloud Run target. |
+| `--gcp-project` | _(required)_ | The GCP **project ID** to deploy into. Project numbers are **not** accepted by `gcloud artifacts repositories`; use the project ID. |
+| `--region` | `us-central1` | Cloud Run region. |
+| `--service-name` | `reflex-app` | Cloud Run service name. |
+| `--ar-repo` | `reflex` | Artifact Registry repository name (created on first deploy). |
+| `--version` | UTC timestamp (`YYYYMMDD-HHMMSS`) | Image version tag. |
+| `--source` | `.` | Directory containing the Reflex app and into which the Dockerfile is written. |
+| `--overwrite-dockerfile` | _off_ | Overwrite an existing `Dockerfile` without prompting. |
+| `--token` | _from `~/.reflex` config_ | Reflex authentication token. |
+| `--interactive / --no-interactive` | `--interactive` | Whether to prompt before overwriting the Dockerfile and running the script. |
+| `--dry-run` | _off_ | Print the manifest without writing the Dockerfile or running the script. |
+| `--loglevel` | `info` | Log verbosity. |
+
+## What gets created in your GCP project
+
+The deploy script enables these APIs (if not already enabled):
+
+- `cloudbuild.googleapis.com`
+- `run.googleapis.com`
+- `artifactregistry.googleapis.com`
+
+It then creates (idempotently) and uses:
+
+- An Artifact Registry Docker repository at `${REGION}-docker.pkg.dev/${GCP_PROJECT}/${AR_REPO}`.
+- A Cloud Build job that builds and pushes the image.
+- A Cloud Run service named `${SERVICE_NAME}`, deployed with `--allow-unauthenticated`, port 8080, 1 vCPU, 1 GiB memory, `--min-instances 1`, and `--session-affinity`.
+
+Re-running the command pushes a new image tag and rolls the Cloud Run service forward.
+
+## Security model
+
+The CLI runs the deploy script under a **restricted environment**. Only an explicit allowlist of host variables is forwarded to `bash` — things like `PATH`, `HOME`, `CLOUDSDK_*`, `DOCKER_*`, and proxy/TLS variables. Unrelated host secrets such as `AWS_*`, `GITHUB_TOKEN`, or arbitrary user variables are **not** forwarded, so a tampered or compromised manifest cannot exfiltrate them.
+
+You can preview the exact script and Dockerfile before anything runs by using `--dry-run`:
+
+```bash
+reflex cloud deploy --gcp \
+    --gcp-project my-gcp-project-id \
+    --dry-run
+```
+
+## Non-interactive use (CI)
+
+For automated pipelines, pass `--no-interactive`, an explicit `--token`, and `--overwrite-dockerfile`:
+
+```bash
+reflex cloud deploy --gcp \
+    --gcp-project "$GCP_PROJECT_ID" \
+    --service-name my-reflex-app \
+    --token "$REFLEX_TOKEN" \
+    --no-interactive \
+    --overwrite-dockerfile
+```
+
+In non-interactive mode the CLI will not prompt — it will refuse to overwrite an existing `Dockerfile` unless `--overwrite-dockerfile` is set, and it will exit non-zero if a token cannot be resolved.
+
+## Troubleshooting
+
+**`Flexgen denied the request (403). GCP Cloud Run deploys require an Enterprise tier subscription.`**
+Your account is not on the Enterprise tier. Contact [sales@reflex.dev](mailto:sales@reflex.dev).
+
+**`Billing must be enabled for activation of service(s) ...` (`UREQ_PROJECT_BILLING_NOT_FOUND`)**
+Attach a billing account to the GCP project, or use a different `--gcp-project`.
+
+**`The value of '--project' flag was set to Project number. To use this command, set it to PROJECT ID instead.`**
+Pass the project ID (e.g. `my-app-123456`), not the numeric project number.
+
+**`No active GCP account found.`**
+Run `gcloud auth login` and `gcloud auth application-default login`.
+
+**`The 'gcloud' / 'docker' / 'bash' CLI was not found on PATH.`**
+Install the missing tool and ensure it's on `PATH` for the shell you're invoking the CLI from.

packages/reflex-hosting-cli/src/reflex_cli/v2/deployments.py

@@ -12,7 +12,7 @@
 from reflex_cli import constants
 from reflex_cli.utils import console
 from reflex_cli.v2.apps import apps_cli
-from reflex_cli.v2.gcp import gcp_cli
+from reflex_cli.v2.gcp import deploy_command as gcp_deploy_command
 from reflex_cli.v2.project import project_cli
 from reflex_cli.v2.secrets import secrets_cli
 from reflex_cli.v2.vmtypes_regions import vm_types_regions_cli
@@ -66,8 +66,8 @@ def hosting_cli(ctx: click.Context) -> None:
     name="secrets",
 )
 hosting_cli.add_command(
-    gcp_cli,
-    name="gcp",
+    gcp_deploy_command,
+    name="deploy",
 )
 for name, command in vm_types_regions_cli.commands.items():
     # Add the command to the hosting CLI

packages/reflex-hosting-cli/src/reflex_cli/v2/gcp.py

@@ -81,17 +81,19 @@
 })
 
 
-@click.group()
-def gcp_cli():
-    """Commands for deploying to GCP Cloud Run."""
-
-
-@gcp_cli.command(name="deploy")
+@click.command(name="deploy")
+@click.option(
+    "--gcp",
+    "use_gcp",
+    is_flag=True,
+    default=False,
+    help="Deploy to GCP Cloud Run. Required (the only supported target today).",
+)
 @click.option(
     "--gcp-project",
     "gcp_project",
-    required=True,
-    help="The GCP project ID to deploy into (sets GCP_PROJECT).",
+    default=None,
+    help="The GCP project ID to deploy into (sets GCP_PROJECT). Required with --gcp.",
 )
 @click.option(
     "--region",
@@ -150,8 +152,9 @@ def gcp_cli():
     default=constants.LogLevel.INFO.value,
     help="The log level to use.",
 )
-def gcp_deploy(
-    gcp_project: str,
+def deploy_command(
+    use_gcp: bool,
+    gcp_project: str | None,
     region: str,
     service_name: str,
     ar_repo: str,
@@ -163,15 +166,25 @@ def gcp_deploy(
     dry_run: bool,
     loglevel: str,
 ):
-    """Deploy a Reflex app to GCP Cloud Run.
+    """Deploy a Reflex app to a cloud target.
 
-    Fetches a Dockerfile and bash deploy script from flexgen, writes the Dockerfile
-    into the source directory, then asks before running the script.
+    Currently the only supported target is GCP Cloud Run via --gcp. The command
+    fetches a Dockerfile and bash deploy script from flexgen, writes the
+    Dockerfile into the source directory, then asks before running the script.
     """
     from reflex_cli.utils import hosting
 
     console.set_log_level(loglevel)
 
+    if not use_gcp:
+        console.error(
+            "Specify a deploy target. Currently supported: --gcp (GCP Cloud Run)."
+        )
+        raise click.exceptions.Exit(2)
+    if not gcp_project:
+        console.error("--gcp-project is required when using --gcp.")
+        raise click.exceptions.Exit(2)
+
     authenticated_client = hosting.get_authenticated_client(
         token=token, interactive=interactive
     )