Mcloud Local

--- name: mcloud-local description: Execute mcloud local build to reproduce a Cloud build on the local machine. Use when debugging a build-failed deployment without pushing to the tracked branch, iterating on a build fix, or testing build-variable changes locally. Requires Docker and must run inside the project's Git repo. allowed-tools: Bash(mcloud local*), Bash(mcloud deployments*), Bash(mcloud use*), Bash(git*), Bash(jq*) --- # Cloud CLI: Local Command Execute `mcloud local build` to run a Cloud build on the local machine, mirroring how Cloud builds the project. Use it to debug `build-failed` deployments without pushing changes and waiting for a full Cloud build. ## Constraints - **No `--json` flag.** `local build` streams plaintext build output and signals the result through its **exit code** (`0` = success). Do not parse its output as JSON. - **Requires Docker installed and running**, and must run from **inside the project's Git repository**. - Reproduces `build-failed` (build) failures only — not `deployment-failed` (runtime) failures. For runtime failures, use `mcloud logs --deployment `. - Available since mcloud CLI v0.1.10. - The Docker build cache is **disabled by default** so variable changes always invalidate the cache; pass `--docker-cache` to enable it. ## Command ### local build Run a Cloud build locally. Infers the root path and build variables from the linked Cloud project and environment. Builds the backend by default; pass `--type storefront` for the storefront. ```bash mcloud local build \ --organization \ --project \ --environment ``` **Options:** - `-o/--organization ` — Organization ID (falls back to active context) - `-p/--project ` — Project ID or handle (falls back to active context) - `-e/--environment ` — Environment whose variables are used (falls back to active context) - `-t/--type ` — Build type (default: `backend`) - `--root-path ` — Backend root path relative to the repo root (inferred if omitted; `.` if no Cloud project found) - `--storefront-path ` — Storefront path relative to the repo root, for `--type storefront` (inferred if omitted) - `--env-file ` — Use a local `.env` file instead of the Cloud environment's variables - `-v/--var ` — Override a single build variable; repeatable - `--docker-cache` — Enable the Docker build cache (default: `false`) **Output:** - On success (exit `0`), the backend image is tagged `:cloud-local-build-`; a storefront build writes its output directory and prints the path. - On failure (non-zero exit), the command exits with the failing step's error — debug it as you would a Cloud build. ## Reproduce a Build Failure Check out the same commit the failed deployment built so the local build matches, then route on the exit code: ```bash # Identify the failing deployment and the commit it built DEPLOYMENT_ID=$( mcloud deployments list --json \ | jq -r '[.[] | select(.backend_status == "build-failed")][0].id' ) COMMIT=$(mcloud deployments get "$DEPLOYMENT_ID" --json | jq -r '.commit_hash') git checkout "$COMMIT" if mcloud local build; then echo "Build succeeded locally; failure not reproducible from this commit." else echo "Build failed locally; inspect the streamed output for the failing step." fi ``` Once the local build exits `0`, push the fix to the tracked branch and start a fresh Cloud build with `mcloud environments trigger-build `. ## Examples ```bash # Reproduce the backend build for the active context mcloud local build # Reproduce the storefront build mcloud local build --type storefront --storefront-path apps/storefront # Test a build-variable fix without editing code mcloud local build --var NODE_ENV=production # Build against a local .env file mcloud local build --env-file .env # Reuse the Docker cache for a faster rebuild mcloud local build --docker-cache ```