@salesforce/b2c-cli 2.3.1 → 2.5.0

package/content/guidance/b2c-cli/b2c-mrt/references/BUNDLE-COMMANDS.md

@@ -0,0 +1,203 @@
+# MRT Bundle Commands Reference
+
+Detailed reference for MRT bundle deployment, listing, history, and download commands.
+
+## Bundle Deploy
+
+Push a local build or deploy an existing bundle to Managed Runtime.
+
+### Push Local Build
+
+```bash
+# Push local build to project (no deployment)
+b2c mrt bundle deploy --project my-storefront
+
+# Push and deploy to staging
+b2c mrt bundle deploy -p my-storefront -e staging
+
+# Push and deploy to production with message
+b2c mrt bundle deploy -p my-storefront -e production --message "Release v1.0.0"
+
+# Push from custom build directory
+b2c mrt bundle deploy -p my-storefront --build-dir ./dist
+
+# Specify Node.js version
+b2c mrt bundle deploy -p my-storefront --node-version 20.x
+
+# Set SSR parameters
+b2c mrt bundle deploy -p my-storefront --ssr-param SSRProxyPath=/api
+
+# Multiple SSR parameters
+b2c mrt bundle deploy -p my-storefront \
+  --ssr-param SSRProxyPath=/api \
+  --ssr-param SSRTimeout=30000
+
+# Push a local build and deploy it via the SCAPI backend
+b2c mrt bundle deploy -p my-storefront -e staging --mrt-backend scapi
+
+# Push via SCAPI with a custom v2 archive layout
+b2c mrt bundle deploy -p my-storefront --mrt-backend scapi --root-dir bld --match-mode ignore_missing
+
+# Push via the legacy v2 endpoint (opt in with --v2)
+b2c mrt bundle deploy -p my-storefront --mrt-backend legacy --v2 --match-mode ignore_missing
+```
+
+**Bundle format:** SCAPI always uploads the v2 format. The legacy backend defaults to v1; pass `--v2` to upload through the legacy v2 endpoint (upload, plus a separate deploy when `-e` is given). `--root-dir`, `--config-path`, and `--match-mode` control the v2 archive layout and only take effect on a v2 upload — on a legacy v1 push they are ignored and the command warns (pass `--v2` to enable them). `b2c mrt bundle deploy --v2` performs the same v2 upload as `b2c mrt bundle upload-v2` and can also deploy in one step.
+
+### Deploy Existing Bundle
+
+Both the local-build push and deploying an existing bundle (with a bundle ID) are backend-aware — they honor `--mrt-backend` (`auto` / `legacy` / `scapi`). For a local-build push under `auto`, a safe SCAPI upload failure falls back to legacy, but once the bundle is uploaded a later deploy failure is not retried on legacy (so a bundle is never uploaded twice). See the "MRT Backends" section in the skill overview.
+
+```bash
+# Deploy existing bundle by ID
+b2c mrt bundle deploy 12345 -p my-storefront -e production
+
+# Deploy with JSON output
+b2c mrt bundle deploy 12345 -p my-storefront -e staging --json
+
+# Deploy via the SCAPI backend and wait for completion
+b2c mrt bundle deploy 12345 -p my-storefront -e production --mrt-backend scapi --wait
+```
+
+**Flags:**
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--message`, `-m` | Bundle message/description | |
+| `--build-dir`, `-b` | Path to build directory | `build` |
+| `--ssr-only` | Server-only file patterns | `ssr.js,ssr.mjs,server/**/*` |
+| `--ssr-shared` | Shared file patterns | `static/**/*,client/**/*` |
+| `--v2` | Use the v2 bundle format/endpoint (SCAPI always uses v2; opt in on legacy) | `false` |
+| `--root-dir` | Archive path prefix for built files and the config file (v2 uploads only) | `bld` |
+| `--config-path` | In-archive config file path, relative to `--root-dir` (v2 uploads only) | `.mrt/config.json` |
+| `--match-mode` | Handling of SSR patterns matching no files — `strict` or `ignore_missing` (v2 uploads only) | `strict` |
+| `--node-version`, `-n` | Node.js version for SSR | `24.x` |
+| `--ssr-param` | SSR parameters (key=value, can repeat) | |
+
+## Bundle Upload (v2)
+
+Build and upload a **v2-format** bundle. This is **upload only** — it does not deploy. Deploy the returned bundle ID separately with `b2c mrt bundle deploy <bundleId> -e <env>`.
+
+Unlike `deploy` (v1), the v2 archive is a gzip tar whose files live under a root directory (default `bld/`), and the SSR configuration is written **inside** the archive at `{root-dir}/{config-path}` (default `bld/.mrt/config.json`) rather than sent as request fields.
+
+The SSR configuration is read from the build's on-disk v2 config file at `{build-dir}/{config-path}` when present. Otherwise it is read from `config.server.ts` in the project directory (`--project-directory`, default the current directory — a compiled `config.server.js`/`config.server.mjs` or the legacy `build/config.server.js` is also accepted), then defaults. Flags override the resolved values per key. If the build already emits the v2 config file, it is excluded from the archive and replaced by the resolved config (no duplicate entry).
+
+`config.server.ts` is evaluated from source (via jiti), so keep type-only imports as `import type`. A `config.server.ts` that exists but fails to import errors the command rather than silently falling back to defaults.
+
+Both `deploy` (v1) and `upload-v2` record the project's `package.json` dependencies (`dependencies` + `devDependencies`) as bundle metadata (v1 `bundle_metadata.dependencies`; v2 `bundleMetadata.dependencies` inside the archive config), matching pwa-kit/storefront-next. An explicit `--dependencies` (v2) or dependencies already in the v2 config file take precedence; collection is best-effort and never blocks a bundle.
+
+```bash
+# Build and upload from ./build
+b2c mrt bundle upload-v2 --project my-storefront
+
+# Upload from a custom build directory
+b2c mrt bundle upload-v2 -p my-storefront --build-dir ./dist
+
+# Allow SSR patterns that match no files
+b2c mrt bundle upload-v2 -p my-storefront --match-mode ignore_missing
+
+# SSR parameters and bundle metadata
+b2c mrt bundle upload-v2 -p my-storefront --ssr-param EnvBasePath=/mobify --node-version 20.x
+b2c mrt bundle upload-v2 -p my-storefront --dependencies @./deps.json --cc-override plugin-a
+```
+
+**Flags:**
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--message`, `-m` | Bundle message/description | |
+| `--build-dir`, `-b` | Path to build directory | `build` |
+| `--root-dir` | Archive path prefix for built files and the config file | `bld` |
+| `--config-path` | In-archive config file path, relative to `--root-dir` | `.mrt/config.json` |
+| `--match-mode` | Handling of SSR patterns matching no files (`strict` or `ignore_missing`) | `strict` |
+| `--ssr-only` | Server-only file patterns | `ssr.js,ssr.mjs,server/**/*` |
+| `--ssr-shared` | Shared file patterns | `static/**/*,client/**/*` |
+| `--node-version`, `-n` | Node.js version for SSR | `24.x` |
+| `--ssr-param` | SSR parameters (key=value, can repeat) | |
+| `--dependencies` | Bundle dependencies as inline JSON or a `@path` to a JSON file | |
+| `--cc-override` | Commerce Cloud override identifier (can repeat) | |
+
+## Bundle List
+
+List bundles in a project. Backend-aware (`--mrt-backend`); under `--json` it returns the serving backend's native response verbatim (legacy vs SCAPI shapes differ).
+
+```bash
+b2c mrt bundle list --project my-storefront
+b2c mrt bundle list -p my-storefront --limit 10
+b2c mrt bundle list -p my-storefront --offset 20
+b2c mrt bundle list -p my-storefront --json
+
+# Force the SCAPI backend
+b2c mrt bundle list -p my-storefront --mrt-backend scapi
+```
+
+**Output columns:** Bundle ID, Message, Status, User, Created
+
+## Bundle History
+
+View deployment history for an environment. Backend-aware (`--mrt-backend`); under `--json` it returns the serving backend's native response verbatim (legacy vs SCAPI shapes differ).
+
+```bash
+b2c mrt bundle history -p my-storefront -e production
+b2c mrt bundle history -p my-storefront -e staging --limit 5
+b2c mrt bundle history -p my-storefront -e production --json
+b2c mrt bundle history -p my-storefront -e staging --mrt-backend scapi
+```
+
+**Output columns:** Bundle ID, Message, Status, Type, Created
+
+## Bundle Download
+
+Download a bundle artifact.
+
+```bash
+# Download to current directory (bundle-{id}.tgz)
+b2c mrt bundle download 12345 -p my-storefront
+
+# Download to specific path
+b2c mrt bundle download 12345 -p my-storefront -o ./artifacts/bundle.tgz
+
+# Get download URL only (for use in scripts)
+b2c mrt bundle download 12345 -p my-storefront --url-only
+
+# JSON output with download URL
+b2c mrt bundle download 12345 -p my-storefront --json
+```
+
+## Common Workflows
+
+### Development to Production Pipeline
+
+```bash
+# 1. Build your PWA Kit application
+npm run build
+
+# 2. Push to staging for testing
+b2c mrt bundle deploy -p my-storefront -e staging -m "v1.0.0-rc1"
+
+# 3. After testing, deploy same bundle to production
+# First, find the bundle ID from the staging deployment
+b2c mrt bundle list -p my-storefront --limit 1
+
+# 4. Deploy that bundle to production
+b2c mrt bundle deploy 12345 -p my-storefront -e production
+```
+
+### Rollback to Previous Bundle
+
+```bash
+# 1. View deployment history
+b2c mrt bundle history -p my-storefront -e production
+
+# 2. Deploy previous bundle
+b2c mrt bundle deploy 12340 -p my-storefront -e production
+```
+
+### Download and Inspect Bundle
+
+```bash
+# Download the bundle
+b2c mrt bundle download 12345 -p my-storefront -o bundle.tgz
+
+# Extract and inspect
+tar -xzf bundle.tgz
+ls -la
+```

package/content/guidance/b2c-cli/b2c-mrt/references/ENVIRONMENT-COMMANDS.md

@@ -0,0 +1,218 @@
+# MRT Environment Commands Reference
+
+Detailed reference for MRT environment, variable, redirect, and access control commands.
+
+## Environment Management
+
+### List Environments
+
+```bash
+b2c mrt env list --project my-storefront
+b2c mrt env list -p my-storefront --json
+```
+
+### Create Environment
+
+```bash
+# Basic staging environment
+b2c mrt env create staging --project my-storefront --name "Staging Environment"
+
+# Production environment in specific region
+b2c mrt env create production -p my-storefront --name "Production" \
+  --production --region eu-west-1
+
+# With external hostname configuration
+b2c mrt env create prod -p my-storefront --name "Production" \
+  --production \
+  --external-hostname www.example.com \
+  --external-domain example.com
+
+# With cookie forwarding and source maps
+b2c mrt env create dev -p my-storefront --name "Development" \
+  --allow-cookies --enable-source-maps
+
+# The new environment's slug may be given as the positional OR via --environment / -e
+b2c mrt env create -p my-storefront -e staging --name "Staging Environment"
+```
+
+> **Slug as positional or flag:** the environment slug can be supplied as the positional argument **or** via `-e` / `--environment` (also honoring `MRT_ENVIRONMENT` / `dw.json`). An explicit positional wins if both are given.
+
+**Flags:**
+| Flag | Description |
+|------|-------------|
+| `--name`, `-n` | Display name (required) |
+| `--region`, `-r` | AWS region for SSR deployment |
+| `--production` | Mark as production environment |
+| `--hostname` | Hostname pattern for V8 Tag loading |
+| `--external-hostname` | Full external hostname (e.g., www.example.com) |
+| `--external-domain` | External domain for Universal PWA SSR |
+| `--allow-cookies` | Forward HTTP cookies to origin |
+| `--enable-source-maps` | Enable source map support |
+
+### Get Environment Details
+
+```bash
+b2c mrt env get --project my-storefront --environment staging
+b2c mrt env get -p my-storefront -e production --json
+```
+
+### Update Environment
+
+```bash
+b2c mrt env update -p my-storefront -e staging --name "Updated Staging"
+b2c mrt env update -p my-storefront -e production --allow-cookies
+b2c mrt env update -p my-storefront -e dev --no-enable-source-maps
+```
+
+### Delete Environment
+
+```bash
+b2c mrt env delete staging --project my-storefront
+b2c mrt env delete old-env -p my-storefront --force
+
+# The env slug may be given as the positional OR via --environment / -e
+b2c mrt env delete -p my-storefront -e old-env --force
+```
+
+> **Slug as positional or flag:** the environment slug can be supplied as the positional argument **or** via `-e` / `--environment` (also honoring `MRT_ENVIRONMENT` / `dw.json`). An explicit positional wins if both are given.
+
+### Invalidate Cache
+
+Invalidate CDN cached content for an environment.
+
+```bash
+# Invalidate all cached content
+b2c mrt env invalidate -p my-storefront -e production
+
+# Invalidate specific paths
+b2c mrt env invalidate -p my-storefront -e production \
+  --path "/products/*" --path "/categories/*"
+```
+
+### B2C Commerce Connection
+
+Get or set B2C Commerce instance connection for an environment.
+
+```bash
+# Get current configuration
+b2c mrt env b2c -p my-storefront -e production
+
+# Set B2C instance
+b2c mrt env b2c -p my-storefront -e production --instance-id aaaa_prd
+
+# Set B2C instance with specific sites
+b2c mrt env b2c -p my-storefront -e production \
+  --instance-id aaaa_prd --sites RefArch,SiteGenesis
+
+# Clear sites list
+b2c mrt env b2c -p my-storefront -e production --clear-sites
+```
+
+## Environment Variables
+
+The `mrt env var` commands (`list` / `set` / `push` / `delete`) are backend-aware: they honor `--mrt-backend` (`auto` / `legacy` / `scapi`) and, over SCAPI, use the Storefront Environments API (scopes `sfcc.storefront.environments` for reads, `sfcc.storefront.environments.rw` for writes). See the [MRT Backends](../SKILL.md#mrt-backends-legacy-vs-scapi) section for backend selection. Values are always masked by both backends. `set` and `delete` apply a merge-PATCH — only the keys you pass change (`delete` sends the key with a `null` value); other variables are preserved. Under `--json`, each command returns the serving backend's native shape.
+
+### List Variables
+
+```bash
+b2c mrt env var list --project my-storefront --environment production
+b2c mrt env var list -p my-storefront -e staging --json
+
+# Force the SCAPI backend
+b2c mrt env var list -p my-storefront -e staging --mrt-backend scapi
+```
+
+### Set Variables
+
+```bash
+# Single variable
+b2c mrt env var set MY_VAR=value -p my-storefront -e production
+
+# Multiple variables
+b2c mrt env var set API_KEY=secret DEBUG=true FEATURE_FLAG=enabled \
+  -p my-storefront -e staging
+
+# Value with spaces (use quotes)
+b2c mrt env var set "MESSAGE=hello world" -p my-storefront -e production
+
+# Force the SCAPI backend
+b2c mrt env var set API_KEY=secret -p my-storefront -e staging --mrt-backend scapi
+
+# Using environment variables for auth
+export MRT_API_KEY=your-api-key
+export MRT_PROJECT=my-storefront
+export MRT_ENVIRONMENT=staging
+b2c mrt env var set MY_VAR=value
+```
+
+### Push Variables from a .env File
+
+Diff a local `.env` file against the remote environment and apply the additions/updates (remote-only variables are not deleted). `push` resolves the backend once from its initial read and pins every write to it; over SCAPI the changes are applied as a single merge-PATCH.
+
+```bash
+# Push ./.env, with confirmation prompt
+b2c mrt env var push -p my-storefront -e production
+
+# Push a custom file, skipping confirmation, over SCAPI
+b2c mrt env var push -p my-storefront -e staging --file config/.env --yes --mrt-backend scapi
+```
+
+### Delete Variable
+
+```bash
+b2c mrt env var delete MY_VAR -p my-storefront -e production
+
+# Force the SCAPI backend
+b2c mrt env var delete MY_VAR -p my-storefront -e production --mrt-backend scapi
+```
+
+## URL Redirects
+
+### List Redirects
+
+```bash
+b2c mrt env redirect list -p my-storefront -e production
+b2c mrt env redirect list -p my-storefront -e production --limit 50
+b2c mrt env redirect list -p my-storefront -e production --json
+```
+
+### Create Redirect
+
+```bash
+# Basic redirect
+b2c mrt env redirect create -p my-storefront -e production \
+  --from "/old-path" --to "/new-path"
+
+# Permanent redirect (301)
+b2c mrt env redirect create -p my-storefront -e production \
+  --from "/legacy/*" --to "/modern/$1" --permanent
+
+# Temporary redirect (302, default)
+b2c mrt env redirect create -p my-storefront -e production \
+  --from "/promo" --to "/sale"
+```
+
+### Delete Redirect
+
+```bash
+b2c mrt env redirect delete abc-123 -p my-storefront -e production
+b2c mrt env redirect delete abc-123 -p my-storefront -e production --force
+```
+
+### Clone Redirects
+
+Copy redirects from one environment to another.
+
+```bash
+b2c mrt env redirect clone -p my-storefront \
+  --source staging --target production
+```
+
+## Access Control Headers
+
+### List Access Control Headers
+
+```bash
+b2c mrt env access-control list -p my-storefront -e staging
+b2c mrt env access-control list -p my-storefront -e production --json
+```

package/content/guidance/b2c-cli/b2c-mrt/references/PROJECT-COMMANDS.md

@@ -0,0 +1,154 @@
+# MRT Project Commands Reference
+
+Detailed reference for MRT project, member, and notification commands.
+
+> **`storefront` alias:** `mrt storefront` is an alias for `mrt project` (including `member` and `notification` subtopics), and `--storefront` / `-s` are aliases for `--project` / `-p` on every command that accepts it — all four are interchangeable. The `MRT_STOREFRONT` / `SFCC_MRT_STOREFRONT` environment variables work as fallbacks for `MRT_PROJECT` / `SFCC_MRT_PROJECT`. The alias matches SCAPI MRT API terminology; the `project` forms continue to work unchanged. Examples below use `project`, but `storefront` is interchangeable. On `mrt project create`, this flag sets the new project's slug (auto-generated from the name if omitted).
+
+## Project Management
+
+### List Projects
+
+```bash
+b2c mrt project list
+b2c mrt project list --limit 10 --offset 0
+b2c mrt project list --json
+```
+
+### Create Project
+
+The positional argument is the project **name**; `--organization` / `-o` is required. Choose the new project's slug with `--project` / `--storefront` (`-p` / `-s`); when omitted, MRT auto-generates it from the name.
+
+```bash
+b2c mrt project create "My Storefront" --organization my-org
+b2c mrt project create "My Storefront" -o my-org --storefront my-storefront
+b2c mrt project create "My Storefront" -o my-org -s my-storefront --region us-east-1
+```
+
+> **Slug as positional or flag:** `get`, `update`, and `delete` accept the project slug **either** as a positional argument **or** via `-p` / `-s` / `--project` / `--storefront` (or `MRT_PROJECT` / `dw.json`). An explicit positional wins if both are given; at least one source must resolve.
+
+### Get Project Details
+
+```bash
+b2c mrt project get my-storefront            # positional
+b2c mrt project get --project my-storefront  # flag
+b2c mrt project get -p my-storefront --json
+```
+
+### Update Project
+
+```bash
+b2c mrt project update my-storefront --name "Updated Name"
+b2c mrt project update --project my-storefront --name "Updated Name"
+```
+
+### Delete Project
+
+```bash
+b2c mrt project delete my-storefront
+b2c mrt project delete --project my-storefront
+b2c mrt project delete -p my-storefront --force  # skip confirmation
+```
+
+## Member Management
+
+Members can have one of three roles: `admin`, `developer`, or `viewer`.
+
+### List Members
+
+```bash
+b2c mrt project member list --project my-storefront
+b2c mrt project member list -p my-storefront --json
+```
+
+### Add Member
+
+```bash
+b2c mrt project member add user@example.com --project my-storefront --role admin
+b2c mrt project member add user@example.com -p my-storefront --role developer
+b2c mrt project member add user@example.com -p my-storefront --role viewer
+```
+
+### Get Member Details
+
+```bash
+b2c mrt project member get user@example.com --project my-storefront
+```
+
+### Update Member Role
+
+```bash
+b2c mrt project member update user@example.com --project my-storefront --role viewer
+```
+
+### Remove Member
+
+```bash
+b2c mrt project member remove user@example.com --project my-storefront
+b2c mrt project member remove user@example.com -p my-storefront --force
+```
+
+## Deployment Notifications
+
+Configure email notifications for deployment events (start, success, failure).
+
+### List Notifications
+
+```bash
+b2c mrt project notification list --project my-storefront
+b2c mrt project notification list -p my-storefront --json
+```
+
+### Create Notification
+
+```bash
+# Notify on deployment failures only
+b2c mrt project notification create -p my-storefront \
+  --target staging --target production \
+  --recipient ops@example.com \
+  --on-failed
+
+# Notify on all deployment events
+b2c mrt project notification create -p my-storefront \
+  --target production \
+  --recipient team@example.com \
+  --on-start --on-success --on-failed
+
+# Multiple recipients
+b2c mrt project notification create -p my-storefront \
+  --target production \
+  --recipient dev@example.com --recipient ops@example.com \
+  --on-failed
+```
+
+**Flags:**
+| Flag | Description |
+|------|-------------|
+| `--target`, `-t` | Target environment (can specify multiple). Aliases: `--environment`, `-e`. |
+| `--recipient`, `-r` | Email recipient (can specify multiple) |
+| `--on-start` | Notify when deployment starts |
+| `--on-success` | Notify when deployment succeeds |
+| `--on-failed` | Notify when deployment fails |
+
+### Get Notification Details
+
+```bash
+b2c mrt project notification get abc-123 --project my-storefront
+b2c mrt project notification get abc-123 -p my-storefront --json
+```
+
+### Update Notification
+
+```bash
+# Change notification events
+b2c mrt project notification update abc-123 -p my-storefront --on-start --no-on-failed
+
+# Update recipients
+b2c mrt project notification update abc-123 -p my-storefront --recipient new-team@example.com
+```
+
+### Delete Notification
+
+```bash
+b2c mrt project notification delete abc-123 --project my-storefront
+b2c mrt project notification delete abc-123 -p my-storefront --force
+```

package/content/guidance/b2c-cli/b2c-sandbox/SKILL.md

@@ -0,0 +1,112 @@
+---
+name: b2c-sandbox
+description: Create and manage on-demand sandboxes (ODS) for B2C Commerce using the b2c CLI. Use this skill whenever the user needs to spin up a new development sandbox, list running sandboxes, start/stop/restart an instance, or manage sandbox lifecycle — even if they just say "I need a sandbox" or "restart my instance".
+---
+
+# B2C Sandbox Skill
+
+Only create or delete sandboxes when explicitly requested. Always confirm destructive actions.
+
+Use the `b2c` CLI plugin to manage Salesforce B2C Commerce On-demand sandboxes (ODS). Only create or delete a sandbox if explicitly asked as this may be a billable or destructible action.
+
+> **Tip:** If `b2c` is not installed globally, use `npx @salesforce/b2c-cli` instead (e.g., `npx @salesforce/b2c-cli sandbox list`).
+
+> **Alias:** The `ods` prefix is still supported as a backward-compatible alias (e.g., `b2c ods list` works the same as `b2c sandbox list`).
+
+## Configuration & Authentication
+
+The CLI auto-discovers credentials from `SFCC_*` environment variables (including project `.env`), the selected project-local or shared `dw.json`, and configuration plugins. `package.json` supplies only non-sensitive defaults. **Flags like `--client-id` and `--client-secret` are usually unnecessary** — only pass them to override what's auto-detected. Use `--user-auth` only when you need browser-based login (e.g., no client secret, or interactive use).
+
+Run `b2c setup inspect` to see the resolved configuration and which source provided each value (use `--json` for scripting; secrets stay masked by default). For precedence rules and troubleshooting, see the `b2c-cli:b2c-config` skill.
+
+## Sandbox ID Formats
+
+Commands that operate on a specific sandbox accept two ID formats:
+
+- **UUID**: The full sandbox UUID (e.g., `abc12345-1234-1234-1234-abc123456789`)
+- **Realm-instance**: The realm-instance format (e.g., `zzzv-123` or `zzzv_123`)
+
+The realm-instance format uses the 4-character realm code followed by a dash or underscore and the instance number. When using a realm-instance format, the CLI will automatically look up the corresponding UUID.
+
+## Examples
+
+### List Sandboxes
+
+```bash
+b2c sandbox list
+
+# for realm zzpq with JSON output
+b2c sandbox list --realm zzpq --json
+
+# filter by status and those created by a specific user, only print the columns id,state,hostname
+b2c sandbox list --filter-params 'state=started,creating&createdBy=clavery@salesforce.com' --realm zzpq --columns id,state,hostname
+```
+
+### Create Sandbox
+
+Only create a sandbox if explicitly asked as this may be a billable action.
+
+```bash
+# create in realm zzpq with 4 hour TTL (0 = infinite); json output and wait for completion (this may take 5-10 minutes; timeout is 10 minutes)
+b2c sandbox create --realm zzpq --ttl 4 --json --wait
+
+# create in realm zzpq with large profile (medium is default)
+b2c sandbox create --realm zzpq --profile large
+
+# create without automatic OCAPI/WebDAV permissions
+b2c sandbox create --realm zzpq --no-set-permissions
+
+# use a different client ID for default permissions
+b2c sandbox create --realm zzpq --permissions-client-id my-other-client
+
+# custom OCAPI settings (replaces defaults)
+b2c sandbox create --realm zzpq --ocapi-settings '[{"client_id":"my-client","resources":[{"resource_id":"/code_versions","methods":["get"]}]}]'
+
+# with start/stop scheduler
+b2c sandbox create --realm zzpq --start-scheduler '{"weekdays":["MONDAY","TUESDAY"],"time":"08:00:00Z"}' --stop-scheduler '{"weekdays":["MONDAY","TUESDAY"],"time":"19:00:00Z"}'
+
+# get full log trace output to debug
+b2c sandbox create --realm zzpq --log-level trace
+```
+
+### Get/Start/Stop/Restart/Delete Sandbox
+
+Commands that operate on a specific sandbox support both UUID and realm-instance formats:
+
+```bash
+# Using UUID
+b2c sandbox get abc12345-1234-1234-1234-abc123456789
+b2c sandbox start abc12345-1234-1234-1234-abc123456789
+b2c sandbox stop abc12345-1234-1234-1234-abc123456789
+
+# Using realm-instance format
+b2c sandbox get zzzv-123
+b2c sandbox start zzzv_123
+b2c sandbox stop zzzv-123
+b2c sandbox restart zzzv-123
+b2c sandbox delete zzzv-123 --force
+```
+
+### Clone Sandbox
+
+```bash
+# clone a sandbox (defaults to source profile, 24h TTL)
+b2c sandbox clone create zzzv-123
+
+# clone with a different profile and wait for completion
+b2c sandbox clone create zzzv-123 --target-profile large --wait
+
+# create 3 clones from the same source in one request (1 to many cloning), and wait for all of them
+b2c sandbox clone create zzzv-123 --target-count 3 --wait
+
+# list clones for a sandbox, optionally filtered to a specific 1 to many batch
+b2c sandbox clone list zzzv-123
+b2c sandbox clone list zzzv-123 --batch-id batch-abcd-002-1700000000000-a1b2c3d4
+
+# get details for a specific clone
+b2c sandbox clone get zzzv-123 aaaa-002-1642780893121
+```
+
+### More Commands
+
+See `b2c sandbox --help` for a full list of available commands and options in the `sandbox` topic.