mcloud-local

Name: mcloud-local
Author: medusajs

202stars24forks

How to install mcloud-local?

medusajs/medusa-agent-skills/mcloud-local

$npx -y skills add medusajs/medusa-agent-skills --skill mcloud-local

Installs into the current project.

Summary

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 G

Files · 1

View on GitHub

SKILL.md

1	# Cloud CLI: Local Command
2
3	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.
4
5	## Constraints
6
7	- 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.
8	- Requires Docker installed and running, and must run from inside the project's Git repository.
9	- Reproduces `build-failed` (build) failures only — not `deployment-failed` (runtime) failures. For runtime failures, use `mcloud logs --deployment <id>`.
10	- Available since mcloud CLI v0.1.10.
11	- The Docker build cache is disabled by default so variable changes always invalidate the cache; pass `--docker-cache` to enable it.
12
13	## Command
14
15	### local build
16
17	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.
18
19	```bash
20	mcloud local build \
21	--organization <org-id> \
22	--project <project-id-or-handle> \
23	--environment <environment-handle>
24	```
25
26	Options:
27	- `-o/--organization <id>` — Organization ID (falls back to active context)
28	- `-p/--project <id-or-handle>` — Project ID or handle (falls back to active context)
29	- `-e/--environment <handle>` — Environment whose variables are used (falls back to active context)
30	- `-t/--type <backend\|storefront>` — Build type (default: `backend`)
31	- `--root-path <path>` — Backend root path relative to the repo root (inferred if omitted; `.` if no Cloud project found)
32	- `--storefront-path <path>` — Storefront path relative to the repo root, for `--type storefront` (inferred if omitted)
33	- `--env-file <path>` — Use a local `.env` file instead of the Cloud environment's variables
34	- `-v/--var <KEY=VALUE>` — Override a single build variable; repeatable
35	- `--docker-cache` — Enable the Docker build cache (default: `false`)
36
37	Output:
38	- On success (exit `0`), the backend image is tagged `<repository-name>:cloud-local-build-<commit-hash>`; a storefront build writes its output directory and prints the path.
39	- On failure (non-zero exit), the command exits with the failing step's error — debug it as you would a Cloud build.
40
41	## Reproduce a Build Failure
42
43	Check out the same commit the failed deployment built so the local build matches, then route on the exit code:
44
45	```bash
46	# Identify the failing deployment and the commit it built
47	DEPLOYMENT_ID=$(
48	mcloud deployments list --json \
49	\| jq -r '[.[] \| select(.backend_status == "build-failed")][0].id'
50	)
51	COMMIT=$(mcloud deployments get "$DEPLOYMENT_ID" --json \| jq -r '.commit_hash')
52
53	git checkout "$COMMIT"
54
55	if mcloud local build; then
56	echo "Build succeeded locally; failure not reproducible from this commit."
57	else
58	echo "Build failed locally; inspect the streamed output for the failing step."
59	fi
60	```
61
62	Once the local build exits `0`, push the fix to the tracked branch and start a fresh Cloud build with `mcloud environments trigger-build <env>`.
63
64	## Examples
65
66	```bash
67	# Reproduce the backend build for the active context
68	mcloud local build
69
70	# Reproduce the storefront build
71	mcloud local build --type storefront --storefront-path apps/storefront
72
73	# Test a build-variable fix without editing code
74	mcloud local build --var NODE_ENV=production
75
76	# Build against a local .env file
77	mcloud local build --env-file .env
78
79	# Reuse the Docker cache for a faster rebuild
80	mcloud local build --docker-cache
81	```

People who liked this also viewed

6 picks

Type

mcloud-local

202stars24forks

View on GitHub

How to install mcloud-local?

medusajs/medusa-agent-skills/mcloud-local

$npx -y skills add medusajs/medusa-agent-skills --skill mcloud-local

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# Cloud CLI: Local Command
2
3	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.
4
5	## Constraints
6
7	- 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.
8	- Requires Docker installed and running, and must run from inside the project's Git repository.
9	- Reproduces `build-failed` (build) failures only — not `deployment-failed` (runtime) failures. For runtime failures, use `mcloud logs --deployment <id>`.
10	- Available since mcloud CLI v0.1.10.
11	- The Docker build cache is disabled by default so variable changes always invalidate the cache; pass `--docker-cache` to enable it.
12
13	## Command
14
15	### local build
16
17	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.
18
19	```bash
20	mcloud local build \
21	--organization <org-id> \
22	--project <project-id-or-handle> \
23	--environment <environment-handle>
24	```
25
26	Options:
27	- `-o/--organization <id>` — Organization ID (falls back to active context)
28	- `-p/--project <id-or-handle>` — Project ID or handle (falls back to active context)
29	- `-e/--environment <handle>` — Environment whose variables are used (falls back to active context)
30	- `-t/--type <backend\|storefront>` — Build type (default: `backend`)
31	- `--root-path <path>` — Backend root path relative to the repo root (inferred if omitted; `.` if no Cloud project found)
32	- `--storefront-path <path>` — Storefront path relative to the repo root, for `--type storefront` (inferred if omitted)
33	- `--env-file <path>` — Use a local `.env` file instead of the Cloud environment's variables
34	- `-v/--var <KEY=VALUE>` — Override a single build variable; repeatable
35	- `--docker-cache` — Enable the Docker build cache (default: `false`)
36
37	Output:
38	- On success (exit `0`), the backend image is tagged `<repository-name>:cloud-local-build-<commit-hash>`; a storefront build writes its output directory and prints the path.
39	- On failure (non-zero exit), the command exits with the failing step's error — debug it as you would a Cloud build.
40
41	## Reproduce a Build Failure
42
43	Check out the same commit the failed deployment built so the local build matches, then route on the exit code:
44
45	```bash
46	# Identify the failing deployment and the commit it built
47	DEPLOYMENT_ID=$(
48	mcloud deployments list --json \
49	\| jq -r '[.[] \| select(.backend_status == "build-failed")][0].id'
50	)
51	COMMIT=$(mcloud deployments get "$DEPLOYMENT_ID" --json \| jq -r '.commit_hash')
52
53	git checkout "$COMMIT"
54
55	if mcloud local build; then
56	echo "Build succeeded locally; failure not reproducible from this commit."
57	else
58	echo "Build failed locally; inspect the streamed output for the failing step."
59	fi
60	```
61
62	Once the local build exits `0`, push the fix to the tracked branch and start a fresh Cloud build with `mcloud environments trigger-build <env>`.
63
64	## Examples
65
66	```bash
67	# Reproduce the backend build for the active context
68	mcloud local build
69
70	# Reproduce the storefront build
71	mcloud local build --type storefront --storefront-path apps/storefront
72
73	# Test a build-variable fix without editing code
74	mcloud local build --var NODE_ENV=production
75
76	# Build against a local .env file
77	mcloud local build --env-file .env
78
79	# Reuse the Docker cache for a faster rebuild
80	mcloud local build --docker-cache
81	```

People who liked this also viewed

6 picks

Type