b2c-config

# B2C Config Skill For routine inspection, call `config_inspect` or `b2c setup inspect` directly; no skill read is required. Keep secrets redacted; manually reading `dw.json` is usually unnecessary. Read the relevant section here when configuring sources or diagnosing unexpected/missing values. | Task | CLI | MCP | Preference / difference | Fallback | | ------------------------------------ | ----------------------- | ----------------------------------- | -------------------------------------------------------------------------------------------- | --------------------------------------------------------- | | Inspect resolved configuration | `b2c setup inspect` | `config_inspect` | Either; same resolver, redacted by default. MCP accepts per-call project/instance overrides. | Inspect source files only for edits or unresolved issues. | | Change configuration or authenticate | `b2c setup`, `b2c auth` | No configuration-writing equivalent | CLI; inspect command help for the requested operation. | Edit the intended configuration source. | If `b2c` is unavailable, use `npx @salesforce/b2c-cli`. ## How the CLI Discovers Configuration The CLI **automatically detects** instance hostname, credentials, tenant ID, MRT API key, and other settings from multiple sources. **You usually do not need to pass `--server`, `--client-id`, `--client-secret`, `--username`, `--password`, `--tenant-id`, `--short-code`, or `--api-key` as flags** — the CLI picks them up from the environment or config files. Sources, in resolution order (highest priority first): 1. **CLI flags and environment variables** — explicit values always win. Includes `.env` files in the current project directory (auto-loaded). 2. **Plugin sources (high priority)** — custom configuration plugins (e.g., secret managers). 3. **`dw.json`** — selected by `--config` / `SFCC_CONFIG`, the project's `.env`, the project-local file, or the shared global `dw.json`. Supports a single instance or a `configs[]` array with `active: true` / `-i <name>` selection. 4. **`~/.mobify`** — home-directory file (MRT API key only). 5. **Plugin sources (low priority)**. 6. **`package.json`** under the `b2c` key — non-sensitive project defaults (e.g., `shortCode`, `clientId`, `mrtProject`). Sensitive fields like `clientSecret`/`password` are intentionally **not** allowed here. For unexpected values, inspect resolved configuration and sources with `config_inspect` or `b2c setup inspect`. ### Shared Global Default Use a shared fallback when the same `dw.json`-format file should work across the CLI, MCP server, and B2C DX VS Code extension: ```bash b2c setup default-config set /path/to/dw.json b2c setup default-config get b2c setup default-config unset ``` The configuration-file selection order is: explicit `--config`; process `SFCC_CONFIG`; project `.env` `SFCC_CONFIG`; project-local `dw.json`; global default. The global file never replaces an explicit or project-local choice. The primary and global `dw.json` files form one instance catalog. `-i <name>` searches the primary file first and then the global file, with same-name primary entries shadowing global entries. Each selected instance is complete—its fields are not merged with a matching entry in the other file. Instance list/remove/set-active operate across both files; create writes to the primary file when present and otherwise to the global `dw.json`. Without `-i`, an active primary instance wins. A root-level primary configuration with no `active` field is its implicit default; set its root to `active: false` to opt it out and allow an active/default global instance to be selected. `b2c setup inspect` shows both files in its Sources section and marks the selected file. ### MCP Project Context For MCP installation or tool selection, use `mcp/server` when available or the [MCP configuration guide](https://salesforcecommercecloud.github.io/b2c-developer-tooling/mcp/configuration). These are client launch settings; `config_inspect` reports B2C values and sources, not enabled toolsets or client filters. Project `.env` does not select MCP tools. Local MCP project tools accept `projectDirectory`. Tools that resolve B2C/MRT configuration accept the same flat `projectDirectory`, `configPath`, and `instanceName` arguments. This override is especially important for plugin installs, where the MCP process working directory may be the plugin directory rather than the open project. For each configuration-aware call, the MCP server: 1. Parses `.env` from `projectDirectory`. 2. Applies all supported B2C/MRT environment variables from that file. 3. Selects a `dw.json`-format configuration file in this order: per-call `configPath`; startup `--config` / `SFCC_CONFIG`; project `.env` `SFCC_CONFIG`; `${projectDirectory}/dw.json`; shared global default. 4. Resolves relative per-call `configPath` and project `.env` `SFCC_CONFIG` values from `projectDirectory`. 5. Selects `instanceName`, when supplied, from the primary file first and then the shared global `dw.json`, without changing either file. 6. Continues through the normal tooling configuration sources, including registered plugin sources, MRT credentials, and `package.json`. 7. Resolves specialized paths such as `cartridgeDirectory`, `buildDirectory`, and `outputDirectory` from the same root when relative. Project `.env` values are scoped to that MCP call so one project's environment does not leak into another. Each project/config-aware result includes an authoritative, compact `resolution` block. It reports the selected project, configuration file, instance, hostname, and specialized directories without relying on paths embedded in tool descriptions. Session and watch start calls retain it, and their list tools expose it for later follow-up calls. The MCP `config_inspect` tool additionally returns the full source graph and uses the same SDK resolver and registered CLI plugin configuration sources as `b2c setup inspect`. Use `projectDirectory`, `configPath`, and/or `instanceName` to compare the intended project, file, and instance. ### `dw.json` Key Casing Field names in `dw.json` accept **both camelCase and kebab-case** — they're equivalent. For example: | Either form works | | ------------------------------------------------------------------------- | | `clientId` ≡ `client-id` | | `clientSecret` ≡ `client-secret` | | `codeVersion` ≡ `code-version` | | `tenantId` ≡ `tenant-id` | | `shortCode` ≡ `short-code` ≡ `scapi-shortcode` | | `webdavHostname` ≡ `webdav-hostname` ≡ `webdav-server` ≡ `secureHostname` | | `certificatePassphrase` ≡ `certificate-passphrase` ≡ `passphrase` | Legacy aliases like `server` (for `hostname`) are also still supported. If a value isn't being picked up, casing is rarely the cause — check spelling, then run `b2c setup inspect` to see what the CLI actually parsed. For the full field reference, see the [Configuration guide](https://salesforcecommercecloud.github.io/b2c-developer-tooling/guide/configuration) (or `docs/guide/configuration.md` in the repo). ## Authentication Most commands that interact with a B2C Commerce instance require authentication. The CLI supports several methods: - **Client credentials (API client):** Configure `clientId` and `clientSecret` in dw.json or environment variables. This is the default for automated/CI use. - **Browser-based (implicit OAuth):** Use `--user-auth` on any OAuth-enabled command to authenticate interactively via the browser. This opens Account Manager in your default browser for login. - **Basic auth:** Configure `username` and `password` for WebDAV operations. - **Stateful sessions:** Use `b2c auth login` for persistent browser-based login sessions or `b2c auth client` for persistent client authentication. Later commands reuse the valid saved session when no other client is configured. ### `--user-auth` Flag Many commands support `--user-auth` to use browser-based OAuth instead of client credentials. As of B2C Commerce release 26.8, SCAPI Admin APIs do not support this flow; migrated commands use OCAPI in `auto` mode, while explicit SCAPI reports an actionable authentication error before making an API request. User auth remains useful when: - You don't have a `clientSecret` configured - You need user-level permissions (e.g., Account Manager admin roles) - You're working interactively ```bash # Interactive browser-based auth for any OAuth command b2c sandbox list --user-auth b2c scapi schemas list --user-auth b2c auth token --user-auth ``` Coding agents can also use `--user-auth` — the browser flow works in any environment where a browser can be opened. The flag is exclusive with `--auth-methods`. **Running behind a proxy:** If `localhost:8080` isn't reachable by the browser (e.g., running in a container or behind a reverse proxy), set `SFCC_REDIRECT_URI` to the proxy URL. The local OAuth server still listens on the default port (or `SFCC_OAUTH_LOCAL_PORT`), but the redirect URI sent to Account Manager will use your proxy URL. Add the proxy URL to the API client's redirect URLs in Account Manager. ## Tenant ID and Organization ID B2C Commerce uses two related identifiers: - **Tenant ID** — the short form (e.g., `zzxy_prd` or `zzxy-prd`) - **Organization ID** — the SCAPI form with `f_ecom_` prefix (e.g., `f_ecom_zzxy_prd`) The CLI automatically normalizes and translates between these formats. You can provide either form in configuration or flags — the CLI handles the conversion. It also extracts tenant IDs from hostnames (e.g., `zzxy-prd.dx.commercecloud.salesforce.com` resolves to `zzxy_prd`). In dw.json or environment variables, use the `tenantId` config key. The CLI will add the `f_ecom_` prefix when making SCAPI calls. ## Inspecting Configuration Use `b2c setup inspect` to view the resolved configuration and understand where each value comes from. Use `b2c setup instance` commands to manage named instance configurations. > **Note:** `b2c setup config` works as an alias for `b2c setup inspect`. ### When to Use Use `b2c setup inspect` when you need to: - Verify which configuration file is being used - Check if environment variables are being read correctly - Debug authentication failures by confirming credentials are loaded - Understand credential source priority (dw.json vs env vars vs plugins) - Identify hostname mismatch protection issues - Verify MRT API key is loaded from ~/.mobify ### View Current Configuration ```bash # Display resolved configuration (sensitive values masked by default) b2c setup inspect # View configuration for a specific instance from dw.json b2c setup inspect -i staging # View configuration with a specific config file b2c setup inspect --config /path/to/dw.json ``` ### Debug Sensitive Values ```bash # Reveal secrets only when the user explicitly requests their values b2c setup inspect --unmask ``` ### JSON Output for Scripting ```bash # Output as JSON for parsing in scripts b2c setup inspect --json # Pretty-print with jq b2c setup inspect --json | jq '.config' # Check which sources are loaded b2c setup inspect --json | jq '.sources' ``` ## IDE Integration Use `b2c setup ide` to configure IDE tooling that consumes the resolved CLI configuration and to enable Script API IntelliSense. ```bash # Vendor Script API TypeScript definitions + jsconfig.json (plain VS Code, WebStorm, etc.) b2c setup ide vscode-types # Print the TS Server plugin path for LSP-based editors (Neovim, Helix, Zed, ...) b2c setup ide tsserver-plugin --json ``` The B2C DX VS Code extension needs no setup — it injects the same TypeScript Server plugin at runtime. ## Managing Instances ### List Configured Instances ```bash # Show all instances from dw.json b2c setup instance list # Output as JSON b2c setup instance list --json ``` ### Create a New Instance ```bash # Interactive mode - prompts for all values b2c setup instance create staging # With hostname b2c setup instance create staging --hostname staging.example.com # Create and set as active b2c setup instance create staging --hostname staging.example.com --active # Optionally save SCAPI coordinates and use SCAPI-first active-version detection b2c setup instance create staging --hostname staging.example.com \ --short-code kv7kzm78 --tenant-id zzxy_prd --api-backend auto # Non-interactive mode (for scripts) b2c setup instance create staging \ --hostname staging.example.com \ --username admin \ --password secret \ --force ``` `shortCode` and `tenantId` are optional. When present with stateless OAuth, setup tries SCAPI first to detect the active code version; otherwise `auto` uses OCAPI. If detection fails, interactive setup reports the reason and allows manual code-version entry. ### Switch Active Instance ```bash # Set staging as the default instance b2c setup instance set-active staging # Now commands use staging by default b2c code list # Uses staging ``` ### Remove an Instance ```bash # Remove with confirmation prompt b2c setup instance remove staging # Remove without confirmation b2c setup instance remove staging --force ``` ## Understanding the Output The `setup inspect` command displays configuration organized by category: - **Instance**: hostname, webdavHostname (if set), codeVersion - **Authentication (Basic)**: username, password (for WebDAV) - **Authentication (OAuth)**: clientId, clientSecret, scopes and authMethods (if set), accountManagerHost (if set) - **Authentication (JWT Bearer)**: jwtCertPath, jwtKeyPath, jwtPassphrase (only shown when configured) - **Authentication (SLAS)**: slasClientId, slasClientSecret (only shown when configured) - **TLS/mTLS**: certificate, certificatePassphrase, selfSigned (only shown when configured) - **SCAPI**: shortCode, tenantId - **Commerce Intelligence (CIP)**: cipHost (only shown when configured) - **On-Demand Sandbox (ODS)**: sandboxApiHost, realm (only shown when configured) - **Managed Runtime (MRT)**: mrtProject, mrtEnvironment, mrtApiKey, mrtOrigin (if set) - **Project**: configured deployment, content, and documentation defaults - **Metadata**: siteId, instanceName, and projectDirectory (only shown when configured) - **Safety**: safety configuration (only shown when configured) - **Sources**: List of all configuration sources that were loaded Each value shows its source in brackets: - `[DwJsonSource]` — Value from the primary `dw.json` file - `[default]` — Value from the shared default `dw.json` (shown as `DwJsonSource (default)` in the Sources table) - `[EnvSource]` — Value from an SFCC\_\* environment variable - `[MobifySource]` — Value from ~/.mobify file - `[PackageJsonSource]` — Value from package.json `b2c` key - Plugin-provided source names (e.g., a credential plugin) ## Configuration Priority Values are resolved with this priority (highest to lowest): 1. CLI flags and environment variables 2. Plugin sources (high priority) 3. dw.json file 4. ~/.mobify file (MRT API key only) 5. Plugin sources (low priority) 6. package.json `b2c` key When troubleshooting, check the source column to understand which configuration is taking precedence. ## Project Defaults in package.json Put non-sensitive defaults shared by the project under the `b2c` key. `siteId` supplies the default site/channel for commands that accept configured site context. For content commands, set `contentLibrary` and list the same ID with `siteLibrary: true` when it is the site's private library: ```json { "b2c": { "siteId": "RefArch", "contentLibrary": "RefArch",