changes to inspect and configuration skills for clarity and progressive disclosure

Author: clavery

packages/b2c-cli/src/commands/setup/inspect.ts

@@ -13,7 +13,13 @@ import {withDocs} from '../../i18n/index.js';
 /**
  * Sensitive fields that should be masked by default.
  */
-const SENSITIVE_FIELDS = new Set<keyof NormalizedConfig>(['clientSecret', 'mrtApiKey', 'password', 'slasClientSecret']);
+const SENSITIVE_FIELDS = new Set<keyof NormalizedConfig>([
+  'certificatePassphrase',
+  'clientSecret',
+  'mrtApiKey',
+  'password',
+  'slasClientSecret',
+]);
 
 /**
  * JSON output structure for the inspect command.
@@ -169,7 +175,7 @@ export default class SetupInspect extends BaseCommand<typeof SetupInspect> {
       'Instance',
       [
         ['hostname', config.hostname],
-        ['webdavHostname', config.webdavHostname],
+        ...(config.webdavHostname ? [['webdavHostname', config.webdavHostname] as [string, unknown]] : []),
         ['codeVersion', config.codeVersion],
       ],
       fieldSources,
@@ -197,13 +203,28 @@ export default class SetupInspect extends BaseCommand<typeof SetupInspect> {
         ['clientSecret', config.clientSecret],
         ['scopes', config.scopes],
         ['authMethods', config.authMethods],
-        ['accountManagerHost', config.accountManagerHost],
-        ['sandboxApiHost', config.sandboxApiHost],
+        ...(config.accountManagerHost ? [['accountManagerHost', config.accountManagerHost] as [string, unknown]] : []),
+        ...(config.sandboxApiHost ? [['sandboxApiHost', config.sandboxApiHost] as [string, unknown]] : []),
       ],
       fieldSources,
       unmask,
     );
 
+    // TLS/mTLS section (only shown when at least one TLS field is configured)
+    if (config.certificate || config.certificatePassphrase || config.selfSigned) {
+      this.renderSection(
+        ui,
+        'TLS/mTLS',
+        [
+          ['certificate', config.certificate],
+          ['certificatePassphrase', config.certificatePassphrase],
+          ['selfSigned', config.selfSigned],
+        ],
+        fieldSources,
+        unmask,
+      );
+    }
+
     // SCAPI section
     this.renderSection(
       ui,
@@ -224,7 +245,7 @@ export default class SetupInspect extends BaseCommand<typeof SetupInspect> {
         ['mrtProject', config.mrtProject],
         ['mrtEnvironment', config.mrtEnvironment],
         ['mrtApiKey', config.mrtApiKey],
-        ['mrtOrigin', config.mrtOrigin],
+        ...(config.mrtOrigin ? [['mrtOrigin', config.mrtOrigin] as [string, unknown]] : []),
       ],
       fieldSources,
       unmask,

skills/b2c-cli/skills/b2c-config/SKILL.md

@@ -5,11 +5,54 @@ description: View and debug b2c CLI configuration and understand where credentia
 
 # B2C Config Skill
 
-Use the `b2c setup inspect` command to view the resolved configuration and understand where each value comes from. Use the `b2c setup instance` commands to manage named instance configurations.
+The B2C CLI (`@salesforce/b2c-cli`) is a command-line tool for Salesforce B2C Commerce development. It provides commands organized by topic: `auth`, `code`, `webdav`, `sandbox`, `mrt`, `scapi`, `slas`, `ecdn`, `job`, `logs`, `sites`, `content`, `cip`, `setup`, and more. Use `b2c --help` or `b2c <topic> --help` for a full list.
 
-> **Tip:** `b2c setup config` still works as an alias. If `b2c` is not installed globally, use `npx @salesforce/b2c-cli` instead (e.g., `npx @salesforce/b2c-cli setup inspect`).
+> **Tip:** If `b2c` is not installed globally, use `npx @salesforce/b2c-cli` instead (e.g., `npx @salesforce/b2c-cli setup inspect`).
 
-## When to Use
+## 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.
+
+### `--user-auth` Flag
+
+Many commands support `--user-auth` to use browser-based implicit OAuth instead of client credentials. This is 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`.
+
+## 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:
 
@@ -20,15 +63,6 @@ Use `b2c setup inspect` when you need to:
 - Identify hostname mismatch protection issues
 - Verify MRT API key is loaded from ~/.mobify
 
-Use `b2c setup instance` commands when you need to:
-
-- List all configured instances
-- Create a new instance configuration
-- Switch between instances (set active)
-- Remove an instance configuration
-
-## Inspecting Configuration
-
 ### View Current Configuration
 
 ```bash
@@ -135,21 +169,22 @@ b2c setup instance remove staging --force
 
 The `setup inspect` command displays configuration organized by category:
 
-- **Instance**: hostname, webdavHostname, codeVersion
+- **Instance**: hostname, webdavHostname (if set), codeVersion
 - **Authentication (Basic)**: username, password (for WebDAV)
-- **Authentication (OAuth)**: clientId, clientSecret, scopes, authMethods
-- **TLS/mTLS**: certificate, certificatePassphrase, selfSigned (for two-factor auth)
-- **SCAPI**: shortCode
-- **Managed Runtime (MRT)**: mrtProject, mrtEnvironment, mrtApiKey
+- **Authentication (OAuth)**: clientId, clientSecret, scopes, authMethods, accountManagerHost (if set), sandboxApiHost (if set)
+- **TLS/mTLS**: certificate, certificatePassphrase, selfSigned (only shown when configured)
+- **SCAPI**: shortCode, tenantId
+- **Managed Runtime (MRT)**: mrtProject, mrtEnvironment, mrtApiKey, mrtOrigin (if set)
 - **Metadata**: instanceName (from multi-instance configs)
 - **Sources**: List of all configuration sources that were loaded
 
 Each value shows its source in brackets:
 
-- `[DwJsonSource]` - Value from dw.json file
-- `[MobifySource]` - Value from ~/.mobify file
-- `[SFCC_*]` - Value from environment variable
-- `[password-store]` - Value from a credential plugin
+- `[DwJsonSource]` — Value from dw.json file
+- `[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
 
@@ -160,7 +195,7 @@ Values are resolved with this priority (highest to lowest):
 3. dw.json file
 4. ~/.mobify file (MRT API key only)
 5. Plugin sources (low priority)
-6. package.json b2c key
+6. package.json `b2c` key
 
 When troubleshooting, check the source column to understand which configuration is taking precedence.
 
@@ -194,6 +229,9 @@ Use `b2c auth token` to get an admin OAuth access token for Account Manager cred
 # Get access token (outputs raw token to stdout)
 b2c auth token
 
+# Get token with browser-based auth
+b2c auth token --user-auth
+
 # Get token with specific scopes
 b2c auth token --auth-scope sfcc.orders --auth-scope sfcc.products
 
@@ -205,7 +243,7 @@ curl -H "Authorization: Bearer $(b2c auth token)" \
   "https://your-instance.dx.commercecloud.salesforce.com/s/-/dw/data/v24_1/sites"
 ```
 
-The token is obtained using the `clientId` and `clientSecret` from your configuration (dw.json or environment variables). If only `clientId` is configured, an implicit OAuth flow is used (browser-based).
+The token is obtained using the `clientId` and `clientSecret` from your configuration (dw.json or environment variables). If only `clientId` is configured, or `--user-auth` is used, an implicit OAuth flow is used (browser-based).
 
 **Note:** This command returns **admin** tokens for OCAPI/Admin APIs. For **shopper** tokens (SLAS), see the [b2c-slas skill](../b2c-slas/SKILL.md).