npm - @salesforce/b2c-dx-mcp - Versions diffs - 2.1.2 → 3.0.0 - Mend

@salesforce/b2c-dx-mcp 2.1.2 → 3.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (1439) hide show

package/node_modules/@salesforce/b2c-agent-plugins/b2c-cli/assets/logo.svg ADDED Viewed

@@ -0,0 +1,31 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<svg id="Layer_1" data-name="Layer 1" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 92 64">
+  <defs>
+    <style>
+      .cls-1, .cls-2 {
+        fill: #fff;
+      }
+      .cls-3 {
+        fill: #0d9dda;
+      }
+      .cls-2 {
+        fill-rule: evenodd;
+      }
+    </style>
+  </defs>
+  <path class="cls-3" d="m38.33,6.98c2.95-3.07,7.05-4.98,11.59-4.98,6.04,0,11.3,3.37,14.11,8.36,2.44-1.09,5.14-1.7,7.97-1.7,10.89,0,19.71,8.9,19.71,19.89s-8.83,19.89-19.71,19.89c-1.33,0-2.63-.13-3.88-.39-2.47,4.4-7.18,7.38-12.58,7.38-2.26,0-4.4-.52-6.3-1.45-2.5,5.89-8.34,10.02-15.13,10.02s-13.11-4.48-15.43-10.76c-1.01.21-2.06.33-3.14.33-8.43,0-15.26-6.9-15.26-15.42,0-5.71,3.07-10.69,7.63-13.36-.94-2.16-1.46-4.55-1.46-7.05C6.45,7.94,14.4,0,24.21,0,29.97,0,35.09,2.74,38.33,6.98Z"/>
+  <g>
+    <path class="cls-1" d="m13.53,33.19c-.06.15.02.18.04.21.17.12.35.21.52.32.93.49,1.81.64,2.73.64,1.88,0,3.04-1,3.04-2.6v-.03c0-1.48-1.32-2.02-2.55-2.41l-.16-.05c-.93-.3-1.73-.56-1.73-1.18v-.03c0-.52.47-.91,1.2-.91.81,0,1.77.27,2.38.61,0,0,.18.12.25-.06.04-.1.35-.94.38-1.03.04-.1-.03-.17-.09-.21-.71-.43-1.68-.72-2.69-.72h-.19c-1.72,0-2.92,1.04-2.92,2.52v.03c0,1.57,1.32,2.07,2.56,2.43l.2.06c.9.28,1.68.52,1.68,1.15v.03c0,.58-.51,1.01-1.32,1.01-.32,0-1.33,0-2.42-.7-.13-.08-.21-.13-.31-.19-.05-.03-.19-.09-.25.08l-.37,1.03Z"/>
+    <path class="cls-1" d="m40.98,33.19c-.06.15.02.18.04.21.17.12.35.21.52.32.93.49,1.81.64,2.73.64,1.88,0,3.04-1,3.04-2.6v-.03c0-1.48-1.31-2.02-2.55-2.41l-.16-.05c-.93-.3-1.73-.56-1.73-1.18v-.03c0-.52.47-.91,1.2-.91.81,0,1.77.27,2.38.61,0,0,.18.12.25-.06.04-.1.35-.94.38-1.03.04-.1-.03-.17-.09-.21-.71-.43-1.68-.72-2.69-.72h-.19c-1.72,0-2.92,1.04-2.92,2.52v.03c0,1.57,1.32,2.07,2.56,2.43l.2.06c.9.28,1.68.52,1.68,1.15v.03c0,.58-.51,1.01-1.32,1.01-.32,0-1.33,0-2.42-.7-.13-.08-.21-.13-.31-.19-.03-.02-.19-.08-.25.08l-.37,1.03Z"/>
+    <path class="cls-1" d="m61.29,28.36c-.15-.52-.39-.98-.71-1.36-.32-.38-.72-.69-1.2-.91-.48-.22-1.04-.34-1.68-.34s-1.2.11-1.68.34c-.48.22-.88.53-1.2.91-.32.38-.56.84-.71,1.36-.15.52-.23,1.08-.23,1.68s.08,1.17.23,1.68c.15.52.39.98.71,1.36.32.38.73.69,1.2.91.48.22,1.04.33,1.68.33s1.2-.11,1.68-.33c.48-.22.88-.52,1.2-.91.32-.38.56-.84.71-1.36.15-.52.23-1.08.23-1.68s-.08-1.17-.23-1.68m-1.57,1.68c0,.91-.17,1.62-.5,2.13-.33.5-.83.74-1.52.74s-1.19-.24-1.52-.74c-.33-.51-.5-1.22-.5-2.13s.17-1.62.49-2.12c.33-.5.82-.74,1.52-.74s1.19.24,1.52.74c.33.5.5,1.21.5,2.12"/>
+    <path class="cls-2" d="m74.15,32.67c-.05-.15-.2-.09-.2-.09-.23.09-.47.17-.73.21-.26.04-.55.06-.86.06-.76,0-1.36-.23-1.79-.67-.43-.45-.68-1.17-.67-2.14,0-.89.22-1.55.6-2.06.38-.51.96-.76,1.74-.76.65,0,1.14.07,1.66.24,0,0,.12.05.18-.11.14-.38.24-.65.39-1.07.04-.12-.06-.17-.1-.18-.2-.08-.68-.21-1.04-.26-.34-.05-.73-.08-1.17-.08-.66,0-1.24.11-1.75.34-.5.22-.92.53-1.26.91-.34.38-.59.84-.76,1.36-.17.52-.26,1.08-.26,1.69,0,1.3.35,2.35,1.04,3.12.69.77,1.73,1.16,3.09,1.16.8,0,1.62-.16,2.22-.4,0,0,.11-.05.06-.19l-.38-1.06Z"/>
+    <path class="cls-2" d="m82.16,28.07c-.13-.5-.46-1.01-.68-1.24-.34-.37-.67-.62-1.01-.77-.43-.19-.95-.31-1.52-.31-.66,0-1.26.11-1.75.34-.49.23-.9.54-1.22.93-.32.39-.56.85-.72,1.38-.15.52-.23,1.09-.23,1.69s.08,1.18.24,1.69c.16.52.42.97.77,1.35.35.38.8.68,1.33.88.53.21,1.18.31,1.92.31,1.53,0,2.34-.35,2.67-.53.06-.03.11-.09.05-.25l-.35-.97c-.05-.14-.2-.09-.2-.09-.38.14-.92.39-2.18.39-.82,0-1.43-.24-1.81-.62-.39-.39-.58-.96-.62-1.76h5.3s.14,0,.15-.13c0-.06.18-1.09-.16-2.28Zm-5.27,1.11c.07-.5.21-.92.43-1.25.32-.5.82-.77,1.52-.77s1.15.27,1.48.77c.22.33.31.76.35,1.25h-3.78Z"/>
+    <path class="cls-2" d="m39.72,28.07c-.13-.5-.46-1.01-.68-1.24-.34-.37-.67-.62-1.01-.77-.43-.19-.95-.31-1.52-.31-.66,0-1.26.11-1.75.34-.49.23-.9.54-1.22.93-.32.39-.56.85-.72,1.38-.15.52-.23,1.09-.23,1.69s.08,1.18.24,1.69c.16.52.42.97.77,1.35.35.38.8.68,1.33.88.53.21,1.18.31,1.92.31,1.53,0,2.34-.35,2.67-.53.06-.03.11-.09.04-.25l-.35-.97c-.05-.14-.2-.09-.2-.09-.38.14-.92.39-2.18.39-.82,0-1.43-.24-1.81-.62-.39-.39-.58-.96-.62-1.76h5.3s.14,0,.15-.13c0-.06.18-1.09-.16-2.28Zm-5.27,1.11c.07-.5.21-.92.43-1.25.33-.5.82-.77,1.52-.77s1.15.27,1.49.77c.22.33.31.76.35,1.25h-3.78Z"/>
+    <path class="cls-1" d="m25.1,28.92c-.22-.02-.49-.02-.83-.02-.45,0-.89.06-1.31.17-.41.11-.79.28-1.11.51-.32.23-.58.52-.77.87-.19.35-.28.76-.28,1.22s.08.88.24,1.21c.16.33.39.61.69.83.29.21.66.37,1.08.47.42.09.89.14,1.4.14.54,0,1.09-.05,1.61-.13.52-.09,1.16-.22,1.33-.26.18-.04.37-.09.37-.09.13-.03.12-.17.12-.17v-4.85c0-1.06-.29-1.85-.85-2.34-.56-.49-1.37-.73-2.43-.73-.4,0-1.04.05-1.42.13,0,0-1.16.22-1.63.6,0,0-.1.06-.05.21l.38,1.01c.05.13.17.09.17.09,0,0,.04-.02.09-.04,1.02-.55,2.31-.54,2.31-.54.57,0,1.01.12,1.31.34.29.22.44.56.44,1.26v.22c-.45-.07-.87-.1-.87-.1Zm-2.11,3.72c-.21-.17-.24-.21-.31-.31-.1-.16-.16-.39-.16-.69,0-.47.15-.8.47-1.03,0,0,.46-.4,1.54-.38.76,0,1.44.12,1.44.12v2.41h0s-.67.14-1.43.19c-1.08.06-1.56-.31-1.55-.31Z"/>
+    <path class="cls-2" d="m67.84,26.19c.04-.12-.04-.18-.08-.19-.09-.03-.54-.13-.89-.15-.67-.04-1.04.07-1.37.22-.33.15-.69.39-.9.66v-.65c0-.09-.06-.16-.15-.16h-1.36c-.09,0-.15.07-.15.16v7.91c0,.09.07.16.16.16h1.39c.09,0,.16-.07.16-.16v-3.95c0-.53.06-1.06.18-1.39.11-.33.27-.59.46-.78.19-.19.41-.32.65-.39.25-.08.52-.1.71-.1.28,0,.58.07.58.07.1.01.16-.05.19-.14.09-.24.35-.97.4-1.11Z"/>
+    <path class="cls-2" d="m54.77,22.53c-.17-.05-.32-.09-.52-.12-.2-.04-.45-.06-.72-.06-.96,0-1.71.27-2.24.81-.53.53-.89,1.34-1.06,2.4l-.06.36h-1.2s-.15,0-.18.15l-.2,1.1c-.01.11.03.17.17.17h1.17l-1.19,6.63c-.09.53-.2.97-.32,1.31-.12.33-.23.57-.37.75-.14.17-.26.3-.48.37-.18.06-.39.09-.62.09-.13,0-.3-.02-.43-.05-.13-.02-.19-.05-.29-.09,0,0-.14-.05-.19.09-.04.11-.36.97-.39,1.08-.04.1.02.19.08.21.16.06.27.09.48.14.29.07.54.07.78.07.49,0,.93-.07,1.3-.2.37-.13.69-.37.98-.68.31-.34.5-.7.69-1.19.18-.48.34-1.08.47-1.78l1.19-6.76h1.75s.15,0,.18-.15l.2-1.1c.01-.11-.03-.17-.17-.17h-1.69s.09-.63.28-1.2c.08-.24.24-.43.37-.57.13-.13.28-.22.44-.28.17-.05.36-.08.57-.08.16,0,.32.02.44.04.16.03.23.05.27.07.17.05.2,0,.23-.08l.41-1.11c.04-.12-.06-.17-.1-.18Z"/>
+    <path class="cls-2" d="m31.1,33.99c0,.09-.06.16-.15.16h-1.41c-.09,0-.15-.07-.15-.16v-11.31c0-.09.06-.16.15-.16h1.41c.09,0,.15.07.15.16v11.31Z"/>
+  </g>
+</svg>

package/node_modules/@salesforce/b2c-agent-plugins/b2c-cli/plugin.json ADDED Viewed

@@ -0,0 +1,44 @@
+{
+  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
+  "name": "b2c-cli",
+  "version": "1.9.0",
+  "description": "B2C CLI Skills for Salesforce Commerce Cloud development.",
+  "author": {
+    "name": "Salesforce"
+  },
+  "homepage": "https://salesforcecommercecloud.github.io/b2c-developer-tooling/",
+  "repository": "https://github.com/SalesforceCommerceCloud/b2c-developer-tooling",
+  "license": "Apache-2.0",
+  "keywords": [
+    "salesforce",
+    "b2c-commerce",
+    "commerce-cloud",
+    "sfra",
+    "scapi",
+    "ocapi"
+  ],
+  "extensions": {
+    "com.openai": {
+      "interface": {
+        "displayName": "B2C CLI",
+        "shortDescription": "Use the Salesforce B2C Commerce CLI from your AI assistant.",
+        "longDescription": "Skills for driving the Salesforce B2C Commerce CLI — deploy cartridges, run jobs, manage On-Demand Sandboxes, stream logs, and perform WebDAV operations without leaving your editor.",
+        "developerName": "Salesforce",
+        "category": "Productivity",
+        "capabilities": [
+          "Read"
+        ],
+        "logo": "./assets/logo.svg",
+        "composerIcon": "./assets/logo.svg",
+        "brandColor": "#0D9DDA",
+        "websiteURL": "https://salesforcecommercecloud.github.io/b2c-developer-tooling/",
+        "defaultPrompt": [
+          "Deploy the cartridges in ./cartridges to my sandbox",
+          "Run the reindex job on my sandbox",
+          "Create a new On-Demand Sandbox with a 48-hour TTL",
+          "Tail the latest error logs from my instance"
+        ]
+      }
+    }
+  }
+}

package/node_modules/@salesforce/b2c-agent-plugins/b2c-cli/skills/b2c-am/SKILL.md ADDED Viewed

@@ -0,0 +1,277 @@
+---
+name: b2c-am
+description: Manage Account Manager resources including API clients, users, roles, and organizations. Use this skill whenever the user needs to create or update API clients, onboard or offboard developers, assign Account Manager roles scoped to tenants, audit user permissions, look up organizations, or provision API clients for CI/CD pipelines. Also use when managing AM role assignments or querying Account Manager data — even if they just say "add a new developer" or "set up an API client". For instance-level Business Manager administration (BM roles, BM users, BM access keys, BM whoami), defer to the `b2c-cli:b2c-bm-users-roles` skill.
+---
+# B2C Account Manager Skill
+Use the `b2c am` commands to manage Account Manager resources: API clients, users, roles, and organizations.
+> **Tip:** If `b2c` is not installed globally, use `npx @salesforce/b2c-cli` instead (e.g., `npx @salesforce/b2c-cli am clients list`).
+## Authentication
+Account Manager commands work out of the box with no configuration. The CLI uses a built-in public client and opens a browser for login.
+- **Zero-config (browser login):** Default. Just run the commands -- the CLI opens a browser for login.
+- **Client credentials:** For CI/CD and automation. The CLI auto-discovers `clientId`/`clientSecret` from `SFCC_*` env vars (including project `.env`), the selected project-local or shared `dw.json`, or configuration plugins — **passing `--client-id`/`--client-secret` flags is usually unnecessary**.
+- **Force browser login (`--user-auth`):** When client credentials are configured but you need browser-based login (required for org and client management).
+> Run `b2c setup inspect` to confirm which credentials the CLI sees and where they came from. For precedence and troubleshooting, see the `b2c-cli:b2c-config` skill.
+### Role Requirements
+| Operations       | Client Credentials (roles on API client) | User Auth (roles on user account)           |
+| ---------------- | ---------------------------------------- | ------------------------------------------- |
+| AM Users & Roles | User Administrator                       | Account Administrator or User Administrator |
+| AM Organizations | Not supported -- use `--user-auth`       | Account Administrator                       |
+| AM API Clients   | Not supported -- use `--user-auth`       | Account Administrator or API Administrator  |
+Organization and API client management are only available with user authentication. For Business Manager administration (BM roles, users, access keys, whoami), see the `b2c-cli:b2c-bm-users-roles` skill.
+## API Clients
+### List Clients
+```bash
+b2c am clients list
+# with pagination
+b2c am clients list --size 50 --page 2
+# JSON output
+b2c am clients list --json
+```
+### Get Client
+```bash
+# by UUID
+b2c am clients get <api-client-id>
+# with expanded organizations and roles
+b2c am clients get <api-client-id> --expand organizations,roles
+```
+### Create Client
+Clients are created inactive by default. Requires user auth.
+```bash
+b2c am clients create \
+  --name "My API Client" \
+  --orgs <org-id> \
+  --password "securePassword123"
+# with roles, role tenant filter, and redirect URLs
+b2c am clients create \
+  --name "CI/CD Pipeline" \
+  --orgs <org-id> \
+  --password "securePassword123" \
+  --roles SALESFORCE_COMMERCE_API \
+  --role-tenant-filter "SALESFORCE_COMMERCE_API:zzxy_prd" \
+  --redirect-urls "https://example.com/callback" \
+  --active
+```
+### Update Client
+Partial update -- only specified fields are changed.
+```bash
+b2c am clients update <api-client-id> --name "New Name"
+b2c am clients update <api-client-id> --active
+```
+### Change Client Password
+```bash
+b2c am clients password <api-client-id> --current "oldPass" --new "newSecurePass123"
+```
+### Delete Client
+Client must be disabled for 7+ days before deletion. Destructive operation (safe mode check).
+```bash
+b2c am clients delete <api-client-id>
+```
+## Users
+### List Users
+```bash
+b2c am users list
+# with extended columns (roles, organizations)
+b2c am users list --extended
+# JSON output with pagination
+b2c am users list --size 100 --json
+```
+### Get User
+```bash
+b2c am users get user@example.com
+# with expanded roles and organizations
+b2c am users get user@example.com --expand-all
+```
+### Create User
+```bash
+b2c am users create \
+  --org "My Organization" \
+  --mail user@example.com \
+  --first-name Jane \
+  --last-name Doe
+```
+The `--org` flag accepts either an org ID or org name. Users are created in INITIAL state with no roles.
+### Update User
+```bash
+b2c am users update user@example.com --first-name Janet --last-name Smith
+```
+### Delete User
+Soft-deletes by default. Use `--purge` for hard delete (user must already be in DELETED state).
+```bash
+# soft delete
+b2c am users delete user@example.com
+# hard delete (purge)
+b2c am users delete developer@example.com --purge
+```
+### Reset User Password
+Resets password to INITIAL state, clearing expiration. Destructive operation (safe mode check).
+```bash
+b2c am users reset user@example.com
+```
+## Roles
+### List Roles
+```bash
+b2c am roles list
+# filter by target type
+b2c am roles list --target-type User
+b2c am roles list --target-type ApiClient
+```
+### Get Role
+```bash
+b2c am roles get bm-admin
+b2c am roles get SLAS_ORGANIZATION_ADMIN
+```
+### Grant Role to User
+```bash
+b2c am roles grant user@example.com --role bm-admin
+# with tenant scope
+b2c am roles grant user@example.com --role bm-admin --scope zzzz_001,zzzz_002
+```
+### Revoke Role from User
+```bash
+# revoke entire role
+b2c am roles revoke user@example.com --role bm-admin
+# revoke specific tenant scopes only
+b2c am roles revoke user@example.com --role bm-admin --scope zzzz_001
+```
+## Organizations
+### List Organizations
+```bash
+b2c am orgs list
+# all organizations (max page size)
+b2c am orgs list --all
+# extended columns
+b2c am orgs list --extended
+```
+### Get Organization
+Accepts org ID or name.
+```bash
+b2c am orgs get <org-id>
+b2c am orgs get "My Organization"
+```
+## Business Manager Administration
+BM-side resources (instance roles, instance users, access keys, whoami) live in the **`b2c-cli:b2c-bm-users-roles`** skill. Use it for:
+- `b2c bm roles` — list/get/create/delete instance access roles, grant/revoke users, manage permissions
+- `b2c bm users` — list, get, search, update, and delete instance users via the OCAPI `/users` resource
+- `b2c bm whoami` — show the BM user the current OAuth token resolves to
+- `b2c bm access-key` — provision and rotate WebDAV/OCAPI/Storefront access keys for SSO-managed users
+Defer to that skill for BM examples and patterns. AM-side onboarding flows (creating an AM user, granting AM roles scoped to tenants) stay here.
+## Common Workflows
+### User Onboarding
+```bash
+# Create the user
+b2c am users create --org $ORG_ID --mail developer@example.com \
+  --first-name Alex --last-name Developer
+# Grant Business Manager Admin role scoped to a specific tenant
+b2c am roles grant developer@example.com --role bm-admin --scope zzxy_prd
+```
+### User Offboarding
+```bash
+# Revoke roles
+b2c am roles revoke developer@example.com --role bm-admin
+# Soft delete the user
+b2c am users delete developer@example.com
+# Permanent deletion (user must be in DELETED state first)
+b2c am users delete developer@example.com --purge
+```
+### Bulk Operations with JSON
+```bash
+# Export all users as JSON
+b2c am users list --size 4000 --json
+# Pipe to jq for filtering
+b2c am users list --json | jq '.[] | select(.userState == "ACTIVE")'
+```
+## Common Patterns
+All `am` commands support `--json` for programmatic output. List commands support `--columns`, `--extended`, `--size`, and `--page` for pagination and column control.
+Destructive operations (user delete, user reset, client delete) check safe mode. Only delete or purge users when explicitly requested.
+### More Commands
+See `b2c am --help` for a full list of available commands and options.

package/node_modules/@salesforce/b2c-agent-plugins/b2c-cli/skills/b2c-am/evals/trigger-evals.json ADDED Viewed

@@ -0,0 +1,12 @@
+[
+  {"query": "I need to onboard a new developer. Create a user in Account Manager and grant them the bm-admin role scoped to our production tenant.", "should_trigger": true},
+  {"query": "How do I create an API client for our CI/CD pipeline that has permissions to deploy code and import site data?", "should_trigger": true},
+  {"query": "Can you list all users in our organization and show which ones have admin roles? I want to audit permissions before our security review.", "should_trigger": true},
+  {"query": "A contractor left our team. I need to remove their Account Manager user and revoke all their role assignments across tenants.", "should_trigger": true},
+  {"query": "I need to look up which organization ID our sandbox belongs to so I can assign the right roles to a new team member.", "should_trigger": true},
+  {"query": "We're setting up a new project and need to create an API client with the SALESFORCE_COMMERCE_API role and scope it to two tenants.", "should_trigger": true},
+  {"query": "How do I grant a Business Manager user access to specific sites using site-level roles in BM itself?", "should_trigger": true},
+  {"query": "How do I create a SLAS client for my headless storefront to handle shopper login and guest sessions?", "should_trigger": false},
+  {"query": "I need to configure OAuth scopes for my SCAPI integration. Where do I set the allowed scopes on my client credentials?", "should_trigger": false},
+  {"query": "I want to set up SSO with our corporate identity provider for Business Manager logins.", "should_trigger": false}
+]

package/node_modules/@salesforce/b2c-agent-plugins/b2c-cli/skills/b2c-bm-users-roles/SKILL.md ADDED Viewed

@@ -0,0 +1,210 @@
+---
+name: b2c-bm-users-roles
+description: Manage Business Manager users, access roles, role permissions, and per-user access keys on a B2C Commerce instance using the b2c CLI. Use this skill whenever the user needs to list or search BM users on a sandbox or production instance, identify which BM user an OAuth token resolves to ("whoami"), assign or revoke instance-level access roles, edit role permissions, look up a user's WebDAV / OCAPI / Storefront access key, or rotate access keys for SSO-managed users. Also use when the user asks "what's my BM login on sandbox X", "rotate my WebDAV password", "how do I make a custom BM role", "audit BM users on this instance", or "delete a stale BM user from a sandbox".
+---
+# B2C Business Manager Users, Roles, and Access Keys
+Use the `b2c bm` commands to administer instance-level Business Manager resources (users, roles, access keys) over SCAPI. These commands target a specific Commerce Cloud instance — pass `--server`/`-s` or set the active instance in `dw.json` first.
+> **Tip:** If `b2c` is not installed globally, use `npx @salesforce/b2c-cli` instead (e.g., `npx @salesforce/b2c-cli bm whoami`).
+For **Account Manager** user/role/client management (cross-instance, scoped to tenants), see the `b2c-cli:b2c-am` skill instead.
+## API Backend
+`bm users` (list, get, portable search, update, delete) and `bm roles` (all subcommands including permissions) run over the SCAPI Merchant Users / Merchant Roles APIs. Configure `shortCode`, `tenantId`, and the `sfcc.users(.rw)` / `sfcc.roles(.rw)` scopes to use SCAPI. Search is implemented by filtering the paginated SCAPI user listing.
+OCAPI-only operations as of B2C Commerce release 26.8 (no current live SCAPI equivalent, unavailable on OCAPI-disabled instances): raw `bm users search --query` JSON, `bm whoami`, and `bm access-key *`. `auto` uses the temporary OCAPI compatibility path. Explicit SCAPI mode fails before contacting OCAPI and directs the user to `--api-backend ocapi` until support becomes available.
+OCAPI is deprecated and disabled on newer instances. `--api-backend auto` (the default) falls back on safe SCAPI capability/auth/request rejections; force a backend with `--api-backend scapi|ocapi` if needed. SCAPI updates `disabled` by reading the current user and preserving its writable fields through PUT because PATCH omits that field.
+## Authentication
+The CLI auto-discovers the target instance and 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 `--server`, `--client-id`, and `--client-secret` are usually unnecessary** — only pass them to override what's auto-detected. Run `b2c setup inspect` to see the resolved configuration and which source provided each value. For precedence and troubleshooting, see the `b2c-cli:b2c-config` skill.
+As of release 26.8, SCAPI Admin APIs require client credentials or JWT Bearer and do not support browser-based user auth. User auth continues to work through OCAPI and WebDAV, and `auto` selects OCAPI for that flow. Explicit SCAPI fails with actionable guidance. A handful of OCAPI endpoints require a _real BM user identity_ and default to user auth.
+| Command group                                  | Default auth                        | Why                                                                                          |
+| ---------------------------------------------- | ----------------------------------- | -------------------------------------------------------------------------------------------- |
+| `b2c bm roles ...`                             | client-credentials → jwt → implicit | OCAPI permissions for `/roles`                                                               |
+| `b2c bm users {list,get,search,update,delete}` | client-credentials → jwt → implicit | OCAPI permissions for `/users`                                                               |
+| `b2c bm whoami`                                | **implicit (browser)**              | OCAPI `/users/this` requires the token to resolve to a BM user                               |
+| `b2c bm access-key {get,create,set,delete}`    | **implicit (browser)**              | OCAPI access-key endpoints require "a valid user" plus `Manage_Users_Access_Keys` permission |
+Override the default with `--auth-methods client-credentials` (or `--client-secret` flags) when your service-client setup is configured to issue user-bearing tokens.
+## Business Manager Roles
+BM roles are instance-level Business Manager access roles (e.g. `Administrator`, `Support`, plus any custom roles).
+```bash
+# list roles on the configured instance
+b2c bm roles list
+# target a different instance
+b2c bm roles list --server my-sandbox.demandware.net
+# get role details, including assigned users
+b2c bm roles get Administrator --expand users
+# create a custom role
+b2c bm roles create MyEditor --description "Custom role for content editors"
+# delete a custom role (system roles cannot be deleted)
+b2c bm roles delete MyEditor
+# assign / unassign a user
+b2c bm roles grant user@example.com --role Administrator
+b2c bm roles revoke user@example.com --role Administrator
+# all commands accept --json for machine-readable output
+b2c bm roles list --json
+```
+### Role Permissions
+Permissions use a file-based get/set workflow because the API replaces the entire permission set on each write.
+```bash
+# view a permission summary
+b2c bm roles permissions get Administrator
+# export to a JSON file for editing
+b2c bm roles permissions get Administrator --output admin-perms.json
+# edit the file, then apply
+b2c bm roles permissions set Administrator --file admin-perms.json
+```
+The permissions JSON has four sections: `functional`, `module`, `locale`, and `webdav`. Each can be scoped to organization, site, or unscoped depending on the permission type.
+## Business Manager Users
+These commands cover the full lifecycle — **create/read/search/update/delete** — for BM users, plus the per-user access-key administration below. Note that `bm users create` is a create-or-replace that only works on instances configured to allow _local_ BM users; most production instances use SSO with Account Manager and reject it with `LocalUserCreationException`, in which case users are provisioned in Account Manager and managed here for the rest of their lifecycle.
+```bash
+# list (default 25)
+b2c bm users list
+b2c bm users list --count 50 --start 50            # pagination
+b2c bm users list --extended                       # add lastLogin, externalId
+b2c bm users list --columns login,email,lastLogin  # custom column set
+# get one user by login (email)
+b2c bm users get user@example.com
+# create a user (create-or-replace; --email required, --role repeatable)
+# only on instances that allow local users — else LocalUserCreationException
+b2c bm users create user@example.com --email user@example.com
+b2c bm users create user@example.com --email user@example.com --first-name Jane --last-name Doe --role Administrator
+# search by attribute (any combination of flags)
+b2c bm users search --search-phrase smith
+b2c bm users search --login user@example.com
+b2c bm users search --locked --sort-by last_login_date --sort-order desc
+b2c bm users search --query '{"text_query":{"fields":["login"],"search_phrase":"foo"}}'
+# update non-identity fields (locale, external_id, disabled, name)
+b2c bm users update user@example.com --disabled
+b2c bm users update user@example.com --no-disabled --preferred-ui-locale en_US
+b2c bm users update user@example.com --first-name Jane --last-name Doe
+# delete (prompts for confirmation; --force to skip)
+b2c bm users delete user@example.com
+b2c bm users delete user@example.com --force --json
+```
+**Cannot be updated via `update`:** the `locked` flag and the user `password` (those are governed by AM/SSO).
+## Whoami — Identify the Current BM User
+`bm whoami` calls `GET /users/this` and returns the BM user the OAuth token resolves to. Useful for verifying which identity will be used for downstream commands and for sanity-checking that a token actually carries a user claim.
+```bash
+b2c bm whoami
+b2c bm whoami --json
+```
+Defaults to browser-based user-auth — a fresh shell will trigger an `b2c auth login` flow. Once logged in, the saved session is reused across commands until it expires.
+## Access Keys (WebDAV, OCAPI, Storefront)
+Access keys let SSO-managed BM users authenticate to non-OAuth surfaces (WebDAV, classic OCAPI/SCAPI Basic auth, or Storefront diagnostics). Three scopes exist; pick the one matching the surface you need to use.
+| Scope                         | Used for                                              |
+| ----------------------------- | ----------------------------------------------------- |
+| `WEBDAV_AND_STUDIO` (default) | WebDAV uploads (cartridge sync, IMPEX), Studio access |
+| `AGENT_USER_AND_OCAPI`        | Customer Service Center (CSC) and OCAPI Basic auth    |
+| `STOREFRONT`                  | Storefront diagnostic / agent login passwords         |
+`[LOGIN]` is **optional** on every access-key command — when omitted, the CLI calls `bm whoami` first and operates on your own user. Passing an explicit login lets administrators manage someone else's keys (requires `Manage_Users_Access_Keys` permission).
+```bash
+# get access-key state for the current user (defaults to WEBDAV_AND_STUDIO)
+b2c bm access-key get
+b2c bm access-key get --scope STOREFRONT
+b2c bm access-key get user@example.com --scope AGENT_USER_AND_OCAPI
+# create or rotate an access key — the secret is shown ONCE at creation
+b2c bm access-key create
+b2c bm access-key create --scope STOREFRONT
+b2c bm access-key create --json | jq -r '.access_key'
+# enable / disable an existing key
+b2c bm access-key set --enabled
+b2c bm access-key set --no-enabled
+b2c bm access-key set user@example.com --scope STOREFRONT --enabled
+# delete (prompts for confirmation; --force to skip)
+b2c bm access-key delete
+b2c bm access-key delete --scope STOREFRONT --force
+```
+> **Important:** the `access_key` value is only returned in the response of `create`. Subsequent `get` calls do not return it. If you lose the value, run `create` again — the previous key is removed automatically.
+## Common Workflows
+### Rotate my own WebDAV password (no admin privileges needed)
+```bash
+b2c bm access-key create
+# record the printed access_key — it's the new password for WebDAV/IMPEX
+```
+### Audit users with admin role and stale logins
+```bash
+b2c bm roles get Administrator --expand users --json | jq '.users[].login'
+b2c bm users search --sort-by last_login_date --sort-order asc --json
+```
+### Provision a new custom role and assign one user
+```bash
+b2c bm roles create MyEditor --description "Content editors"
+b2c bm roles permissions get MyEditor --output role.json
+# edit role.json
+b2c bm roles permissions set MyEditor --file role.json
+b2c bm roles grant editor@example.com --role MyEditor
+```
+### Cycle access keys for an SSO user (admin)
+```bash
+# disable temporarily
+b2c bm access-key set user@example.com --scope WEBDAV_AND_STUDIO --no-enabled
+# rotate
+b2c bm access-key create user@example.com --scope WEBDAV_AND_STUDIO
+```
+## Common Patterns
+- All list/search commands support `--columns`, `--extended` / `-x`, and `--json`.
+- `bm users` and `bm roles` use OCAPI pagination: `--count`/`-n` and `--start`. AM commands use `--size`/`--page` instead — don't mix them up.
+- Destructive commands (`bm users delete`, `bm access-key delete`) prompt for confirmation. Use `--force` for non-interactive scripts. `--json` mode skips the prompt automatically.
+- When a service client cannot resolve a BM user (e.g. AM-only credential), `whoami` and `access-key` commands return `UserNotAvailableException` from the API — re-run with `--user-auth` or `b2c auth login` first.
+### More
+See `b2c bm --help`, `b2c bm users --help`, and `b2c bm access-key --help` for the full flag list. The OCAPI Data API user resource documentation describes the underlying endpoints and their fault codes.