Skip to content

Commit 3590c0d

Browse files
claveryclavery
committed
update docs
1 parent 834137a commit 3590c0d

File tree

1 file changed

+336
-25
lines changed

1 file changed

+336
-25
lines changed

‎docs/cli/mrt.md‎

Lines changed: 336 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -1,52 +1,363 @@
11
# MRT Commands
22

3-
Commands for managing Managed Runtime (MRT) environments.
3+
Commands for managing Managed Runtime (MRT) projects, environments, and bundles.
44

5-
## b2c mrt env-var set
5+
## Global MRT Flags
66

7-
Set an environment variable on a Managed Runtime project.
7+
These flags are available on all MRT commands:
8+
9+
| Flag | Short | Environment Variable | Description |
10+
|------|-------|---------------------|-------------|
11+
| `--api-key` | | `SFCC_MRT_API_KEY` | MRT API key |
12+
| `--project` | `-p` | `SFCC_MRT_PROJECT` | MRT project slug |
13+
| `--environment` | `-e` | `SFCC_MRT_ENVIRONMENT` | Target environment (e.g., staging, production) |
14+
15+
### Configuration Sources
16+
17+
MRT commands resolve configuration in the following order of precedence:
18+
19+
1. Command-line flags
20+
2. Environment variables
21+
3. `dw.json` file (`mrtProject`, `mrtEnvironment` fields)
22+
4. `~/.mobify` config file (for `api_key`)
23+
24+
---
25+
26+
## b2c mrt push
27+
28+
Push a bundle to Managed Runtime.
29+
30+
Creates a bundle from the build directory and uploads it to the specified MRT project. Optionally deploys the bundle to a target environment.
31+
32+
### Usage
33+
34+
```bash
35+
b2c mrt push [FLAGS]
36+
```
37+
38+
### Flags
39+
40+
In addition to [global MRT flags](#global-mrt-flags):
41+
42+
| Flag | Short | Description | Default |
43+
|------|-------|-------------|---------|
44+
| `--message` | `-m` | Bundle message/description | |
45+
| `--build-dir` | `-b` | Path to the build directory | `build` |
46+
| `--ssr-only` | | Glob patterns for server-only files (comma-separated) | `ssr.js,server/**/*` |
47+
| `--ssr-shared` | | Glob patterns for shared files (comma-separated) | `static/**/*,client/**/*` |
48+
| `--node-version` | `-n` | Node.js version for SSR runtime | `20.x` |
49+
| `--ssr-param` | | SSR parameter in key=value format (can be specified multiple times) | |
50+
| `--json` | | Output result as JSON | |
51+
52+
### Examples
53+
54+
```bash
55+
# Push a bundle to a project
56+
b2c mrt push --project my-storefront
57+
58+
# Push and deploy to staging
59+
b2c mrt push --project my-storefront --environment staging
60+
61+
# Push with a release message
62+
b2c mrt push --project my-storefront --environment production --message "Release v1.0.0"
63+
64+
# Push from a custom build directory
65+
b2c mrt push --project my-storefront --build-dir ./dist
66+
67+
# Specify Node.js version for SSR
68+
b2c mrt push --project my-storefront --node-version 20.x
69+
70+
# Set SSR parameters
71+
b2c mrt push --project my-storefront --ssr-param SSRProxyPath=/api
72+
73+
# Using environment variables
74+
export SFCC_MRT_API_KEY=your-api-key
75+
export SFCC_MRT_PROJECT=my-storefront
76+
export SFCC_MRT_ENVIRONMENT=staging
77+
b2c mrt push
78+
```
79+
80+
### Output
81+
82+
On success, the command displays the bundle ID, project, and deployment status:
83+
84+
```
85+
Pushing bundle to my-storefront...
86+
Bundle will be deployed to staging
87+
Bundle #42 pushed to my-storefront and deployed to staging (Release v1.0.0)
88+
```
89+
90+
---
91+
92+
## b2c mrt env create
93+
94+
Create a new environment (target) in a Managed Runtime project.
95+
96+
### Usage
97+
98+
```bash
99+
b2c mrt env create SLUG [FLAGS]
100+
```
101+
102+
### Arguments
103+
104+
| Argument | Description | Required |
105+
|----------|-------------|----------|
106+
| `SLUG` | Environment slug/identifier (e.g., staging, production) | Yes |
107+
108+
### Flags
109+
110+
In addition to [global MRT flags](#global-mrt-flags):
111+
112+
| Flag | Short | Description | Default |
113+
|------|-------|-------------|---------|
114+
| `--name` | `-n` | Display name for the environment | **Required** |
115+
| `--region` | `-r` | AWS region for SSR deployment | |
116+
| `--production` | | Mark as a production environment | `false` |
117+
| `--hostname` | | Hostname pattern for V8 Tag loading | |
118+
| `--external-hostname` | | Full external hostname (e.g., www.example.com) | |
119+
| `--external-domain` | | External domain for Universal PWA SSR (e.g., example.com) | |
120+
| `--allow-cookies` | | Forward HTTP cookies to origin | `false` |
121+
| `--no-allow-cookies` | | Disable cookie forwarding | |
122+
| `--enable-source-maps` | | Enable source map support in the environment | `false` |
123+
| `--no-enable-source-maps` | | Disable source map support | |
124+
| `--json` | | Output result as JSON | |
125+
126+
### Supported Regions
127+
128+
Available AWS regions: `us-east-1`, `us-east-2`, `us-west-1`, `us-west-2`, `ap-south-1`, `ap-south-2`, `ap-northeast-1`, `ap-northeast-2`, `ap-northeast-3`, `ap-southeast-1`, `ap-southeast-2`, `ap-southeast-3`, `ca-central-1`, `eu-central-1`, `eu-central-2`, `eu-west-1`, `eu-west-2`, `eu-west-3`, `eu-north-1`, `eu-south-1`, `il-central-1`, `me-central-1`, `sa-east-1`
129+
130+
### Examples
131+
132+
```bash
133+
# Create a staging environment
134+
b2c mrt env create staging --project my-storefront --name "Staging Environment"
135+
136+
# Create a production environment
137+
b2c mrt env create production --project my-storefront --name "Production" --production
138+
139+
# Create an environment in a specific region
140+
b2c mrt env create feature-test -p my-storefront -n "Feature Test" --region eu-west-1
141+
142+
# Create with external hostname configuration
143+
b2c mrt env create prod -p my-storefront -n "Production" --production \
144+
--external-hostname www.example.com \
145+
--external-domain example.com
146+
147+
# Output as JSON
148+
b2c mrt env create staging -p my-storefront -n "Staging" --json
149+
```
150+
151+
### Output
152+
153+
On success, displays the created environment details:
154+
155+
```
156+
Creating environment "staging" in my-storefront...
157+
Environment created successfully.
158+
159+
Slug: staging
160+
Name: Staging Environment
161+
Project: my-storefront
162+
State: created
163+
Production: No
164+
Region: us-east-1
165+
Hostname: staging-my-storefront.mobify-storefront.com
166+
```
167+
168+
---
169+
170+
## b2c mrt env delete
171+
172+
Delete an environment (target) from a Managed Runtime project.
8173

9174
### Usage
10175

11176
```bash
12-
b2c mrt env-var set <KEY> <VALUE>
177+
b2c mrt env delete SLUG [FLAGS]
13178
```
14179

15180
### Arguments
16181

17182
| Argument | Description | Required |
18183
|----------|-------------|----------|
19-
| `KEY` | Environment variable name | Yes |
20-
| `VALUE` | Environment variable value | Yes |
184+
| `SLUG` | Environment slug/identifier to delete | Yes |
21185

22186
### Flags
23187

24-
| Flag | Short | Description | Required |
25-
|------|-------|-------------|----------|
26-
| `--project` | | MRT project ID | Yes |
27-
| `--environment` | `-e` | Target environment | Yes |
28-
| `--api-key` | | MRT API key | Yes |
188+
In addition to [global MRT flags](#global-mrt-flags):
189+
190+
| Flag | Short | Description | Default |
191+
|------|-------|-------------|---------|
192+
| `--force` | `-f` | Skip confirmation prompt | `false` |
193+
| `--json` | | Output result as JSON | |
29194

30195
### Examples
31196

32197
```bash
33-
# Set an environment variable
34-
b2c mrt env-var set MY_VAR "my value" \
35-
--project acme-storefront \
36-
--environment production \
37-
--api-key your-api-key
198+
# Delete an environment (with confirmation prompt)
199+
b2c mrt env delete feature-test --project my-storefront
38200

39-
# Using environment variables
201+
# Delete without confirmation
202+
b2c mrt env delete old-staging -p my-storefront --force
203+
```
204+
205+
### Notes
206+
207+
- The command will prompt for confirmation unless `--force` is used
208+
- Be cautious when deleting production environments
209+
210+
---
211+
212+
## b2c mrt env var list
213+
214+
List environment variables on a Managed Runtime environment.
215+
216+
### Usage
217+
218+
```bash
219+
b2c mrt env var list [FLAGS]
220+
```
221+
222+
### Flags
223+
224+
Uses [global MRT flags](#global-mrt-flags). Both `--project` and `--environment` are required.
225+
226+
| Flag | Description |
227+
|------|-------------|
228+
| `--json` | Output result as JSON |
229+
230+
### Examples
231+
232+
```bash
233+
# List environment variables
234+
b2c mrt env var list --project acme-storefront --environment production
235+
236+
# Short form
237+
b2c mrt env var list -p my-project -e staging
238+
239+
# Output as JSON
240+
b2c mrt env var list -p my-project -e production --json
241+
```
242+
243+
### Output
244+
245+
Displays a table of environment variables:
246+
247+
```
248+
Listing env vars for my-project/production...
249+
Name Value Status Updated
250+
─────────────────────────────────────────────────────────────────────
251+
API_KEY sk-xxx...xxx Published 12/10/2024, 2:30:00 PM
252+
DEBUG false Published 12/9/2024, 10:15:00 AM
253+
FEATURE_FLAG enabled Pending 12/10/2024, 3:00:00 PM
254+
```
255+
256+
---
257+
258+
## b2c mrt env var set
259+
260+
Set environment variables on a Managed Runtime environment.
261+
262+
### Usage
263+
264+
```bash
265+
b2c mrt env var set KEY=value [KEY=value...] [FLAGS]
266+
```
267+
268+
### Arguments
269+
270+
| Argument | Description | Required |
271+
|----------|-------------|----------|
272+
| `KEY=value` | Environment variable(s) in KEY=value format | Yes |
273+
274+
### Flags
275+
276+
Uses [global MRT flags](#global-mrt-flags). Both `--project` and `--environment` are required.
277+
278+
| Flag | Description |
279+
|------|-------------|
280+
| `--json` | Output result as JSON |
281+
282+
### Examples
283+
284+
```bash
285+
# Set a single environment variable
286+
b2c mrt env var set MY_VAR=value --project acme-storefront --environment production
287+
288+
# Set multiple environment variables
289+
b2c mrt env var set API_KEY=secret DEBUG=true -p my-project -e staging
290+
291+
# Set a value with spaces (use quotes)
292+
b2c mrt env var set "MESSAGE=hello world" -p my-project -e production
293+
294+
# Using environment variables for auth
40295
export SFCC_MRT_API_KEY=your-api-key
41-
b2c mrt env-var set MY_VAR "my value" \
42-
--project acme-storefront \
43-
--environment production
296+
export SFCC_MRT_PROJECT=my-project
297+
export SFCC_MRT_ENVIRONMENT=staging
298+
b2c mrt env var set MY_VAR=value
44299
```
45300

46-
### Authentication
301+
### Notes
302+
303+
- Variable values are set immediately but may take time to propagate
304+
- Use quotes around values containing spaces
305+
- Multiple variables can be set in a single command
306+
307+
---
47308

48-
MRT commands use API key authentication. Provide `--api-key` or set the `SFCC_MRT_API_KEY` environment variable.
309+
## b2c mrt env var delete
49310

50-
::: warning
51-
This command is currently a stub and not yet fully implemented.
52-
:::
311+
Delete an environment variable from a Managed Runtime environment.
312+
313+
### Usage
314+
315+
```bash
316+
b2c mrt env var delete KEY [FLAGS]
317+
```
318+
319+
### Arguments
320+
321+
| Argument | Description | Required |
322+
|----------|-------------|----------|
323+
| `KEY` | Environment variable name to delete | Yes |
324+
325+
### Flags
326+
327+
Uses [global MRT flags](#global-mrt-flags). Both `--project` and `--environment` are required.
328+
329+
| Flag | Description |
330+
|------|-------------|
331+
| `--json` | Output result as JSON |
332+
333+
### Examples
334+
335+
```bash
336+
# Delete an environment variable
337+
b2c mrt env var delete MY_VAR --project acme-storefront --environment production
338+
339+
# Short form
340+
b2c mrt env var delete OLD_API_KEY -p my-project -e staging
341+
```
342+
343+
---
344+
345+
## Authentication
346+
347+
All MRT commands use API key authentication. You can provide credentials in several ways:
348+
349+
1. **Command-line flag**: `--api-key your-api-key`
350+
2. **Environment variable**: `export SFCC_MRT_API_KEY=your-api-key`
351+
3. **Mobify config file**: `~/.mobify` with `api_key` field
352+
353+
### Getting an API Key
354+
355+
Obtain your MRT API key from the Managed Runtime dashboard in your Salesforce Commerce Cloud account.
356+
357+
### Example ~/.mobify File
358+
359+
```json
360+
{
361+
"api_key": "your-mrt-api-key"
362+
}
363+
```

0 commit comments

Comments
 (0)