diff --git a/.changeset/setup-skills-upgrade-prompt.md b/.changeset/setup-skills-upgrade-prompt.md new file mode 100644 index 00000000..c2f9ff26 --- /dev/null +++ b/.changeset/setup-skills-upgrade-prompt.md @@ -0,0 +1,6 @@ +--- +'@salesforce/b2c-cli': patch +'@salesforce/b2c-tooling-sdk': patch +--- + +`b2c setup skills` now prompts to overwrite already-installed skills in interactive mode instead of silently skipping them with a "use --update to overwrite" message. The existing `--update` and `--force` flags still work non-interactively. diff --git a/.changeset/skill-config-first-examples.md b/.changeset/skill-config-first-examples.md new file mode 100644 index 00000000..9fa50df9 --- /dev/null +++ b/.changeset/skill-config-first-examples.md @@ -0,0 +1,5 @@ +--- +'@salesforce/b2c-cli': patch +--- + +Refine b2c CLI skills (`scapi-schemas`, `scapi-custom`, `slas`, `ecdn`, `cip`, `users-roles`) to show config-first idiomatic usage. Examples now assume values like `tenantId`, `shortCode`, and `clientId` are resolved from `dw.json` / `SFCC_*` env vars, with flags shown only as overrides. This prevents coding agents from prompting users for values that are already configured. diff --git a/packages/b2c-cli/src/commands/setup/skills.ts b/packages/b2c-cli/src/commands/setup/skills.ts index 1256ad11..7e503d98 100644 --- a/packages/b2c-cli/src/commands/setup/skills.ts +++ b/packages/b2c-cli/src/commands/setup/skills.ts @@ -16,6 +16,7 @@ import { downloadSkillsArtifact, scanSkills, installSkills, + isSkillInstalled, getIdeDisplayName, getIdeDocsUrl, findSkillsByName, @@ -305,6 +306,34 @@ export default class SetupSkills extends BaseCommand { } } + // Detect already-installed skills and prompt to upgrade (unless --update or --force set) + let update = this.flags.update; + if (!update && !this.flags.force) { + const existingCount = skillsToInstall.reduce((count, skill) => { + return ( + count + + targetIdes.filter((ide) => + isSkillInstalled(skill.name, ide, { + global: this.flags.global, + projectRoot: process.cwd(), + directory, + }), + ).length + ); + }, 0); + + if (existingCount > 0) { + update = await confirm({ + message: t( + 'commands.setup.skills.confirmUpgrade', + '{{count}} skill(s) are already installed. Overwrite with the new version?', + {count: existingCount}, + ), + default: true, + }); + } + } + // Install skills for all skillsets in parallel const installPromises = skillsets .map((skillset) => { @@ -313,7 +342,7 @@ export default class SetupSkills extends BaseCommand { return installSkills(skillsForSet, skillsDirs[skillset], { ides: targetIdes, global: this.flags.global, - update: this.flags.update, + update, projectRoot: process.cwd(), directory, }); diff --git a/packages/b2c-tooling-sdk/src/skills/installer.ts b/packages/b2c-tooling-sdk/src/skills/installer.ts index 79189420..3bd461e3 100644 --- a/packages/b2c-tooling-sdk/src/skills/installer.ts +++ b/packages/b2c-tooling-sdk/src/skills/installer.ts @@ -88,7 +88,7 @@ async function copyDirectory(source: string, target: string): Promise { export function isSkillInstalled( skillName: string, ide: IdeType, - options: {global: boolean; projectRoot?: string}, + options: {global: boolean; projectRoot?: string; directory?: string}, ): boolean { const installPath = getSkillInstallPath(ide, skillName, options); return fs.existsSync(installPath); diff --git a/skills/b2c-cli/skills/b2c-cip/SKILL.md b/skills/b2c-cli/skills/b2c-cip/SKILL.md index d838a391..15cc27ae 100644 --- a/skills/b2c-cli/skills/b2c-cip/SKILL.md +++ b/skills/b2c-cli/skills/b2c-cip/SKILL.md @@ -29,16 +29,22 @@ cip └── top-referrers ``` -## Requirements +## Configuration -- OAuth client credentials (resolved from CLI configuration, or override with `--client-id` / `--client-secret`) -- CIP tenant: `--tenant-id` (or `--tenant`) -- API client has `Salesforce Commerce API` role with tenant filter for your instance +Values like `tenantId`, `clientId`, and `clientSecret` resolve from `dw.json` / `SFCC_*` env vars / the active instance. Examples below show minimal usage; add flags only to override configured values. If a required value is missing, the CLI emits an actionable error pointing at the flag, env var, and config key. See the `b2c-config` skill for precedence details. -Optional: +Relevant overrides: -- `--cip-host` (or `SFCC_CIP_HOST`) to override the default host -- `--staging` (or `SFCC_CIP_STAGING`) to force staging analytics host +- `--tenant-id` (alias `--tenant`) / `SFCC_TENANT_ID` / `tenantId` +- `--client-id` / `SFCC_CLIENT_ID` / `clientId` +- `--client-secret` / `SFCC_CLIENT_SECRET` / `clientSecret` +- `--cip-host` / `SFCC_CIP_HOST` to override the default host +- `--staging` / `SFCC_CIP_STAGING` to force staging analytics host + +## Requirements + +- OAuth client credentials (CIP supports client credentials only; `--user-auth` is not supported) +- API client has `Salesforce Commerce API` role with tenant filter for your instance ::: warning Availability This feature is typically used with production analytics tenants (for example `abcd_prd`). @@ -58,14 +64,17 @@ Reports & Dashboards non-production URL: `https://ccac.stg.analytics.commerceclo ## Metadata Discovery Examples ```bash -# List warehouse tables -b2c cip tables --tenant-id abcd_prd +# List warehouse tables (uses configured tenant) +b2c cip tables # Filter table names -b2c cip tables --tenant-id abcd_prd --pattern "ccdw_aggr_%" +b2c cip tables --pattern "ccdw_aggr_%" # Describe table columns -b2c cip describe ccdw_aggr_ocapi_request --tenant-id abcd_prd +b2c cip describe ccdw_aggr_ocapi_request + +# Target a different tenant than the active config +b2c cip tables --tenant-id abcd_prd ``` ## Known Tables @@ -86,9 +95,8 @@ The list is derived from official JDBC documentation and intended as a quick dis # Show report commands b2c cip report --help -# Run a report +# Run a report (tenant resolves from config) b2c cip report sales-analytics \ - --tenant-id abcd_prd \ --site-id Sites-RefArch-Site \ --from 2025-01-01 \ --to 2025-01-31 @@ -107,15 +115,13 @@ b2c cip report top-referrers --site-id Sites-RefArch-Site --limit 25 --staging - ```bash b2c cip report sales-analytics --site-id Sites-RefArch-Site --sql \ - | b2c cip query --tenant-id abcd_prd + | b2c cip query ``` ## Raw SQL Query Examples ```bash -b2c cip query \ - --tenant-id abcd_prd \ - "SELECT * FROM ccdw_aggr_sales_summary LIMIT 10" +b2c cip query "SELECT * FROM ccdw_aggr_sales_summary LIMIT 10" ``` You can also use: diff --git a/skills/b2c-cli/skills/b2c-ecdn/SKILL.md b/skills/b2c-cli/skills/b2c-ecdn/SKILL.md index 0621e6a4..50d53b29 100644 --- a/skills/b2c-cli/skills/b2c-ecdn/SKILL.md +++ b/skills/b2c-cli/skills/b2c-ecdn/SKILL.md @@ -9,72 +9,79 @@ Use the `b2c` CLI plugin to manage eCDN (embedded Content Delivery Network) zone > **Tip:** If `b2c` is not installed globally, use `npx @salesforce/b2c-cli` instead (e.g., `npx @salesforce/b2c-cli ecdn zones list`). +## Configuration + +Values like `tenantId` resolve from `dw.json` / `SFCC_*` env vars / the active instance. Examples below show minimal usage; add flags only to override configured values. If a required value is missing, the CLI emits an actionable error pointing at the flag, env var, and config key. See the `b2c-config` skill for precedence details. + ## Prerequisites - OAuth credentials with `sfcc.cdn-zones` scope (read operations) - OAuth credentials with `sfcc.cdn-zones.rw` scope (write operations) -- Tenant ID for your B2C Commerce organization +- Tenant ID for your B2C Commerce organization (from config or `--tenant-id`) ## Examples ### List CDN Zones ```bash -# list all CDN zones for a tenant -b2c ecdn zones list --tenant-id zzxy_prd +# list all CDN zones for the configured tenant +b2c ecdn zones list + +# JSON output +b2c ecdn zones list --json -# list with JSON output -b2c ecdn zones list --tenant-id zzxy_prd --json +# target a different tenant than the active config +b2c ecdn zones list --tenant-id zzxy_prd ``` ### Create a Storefront Zone ```bash # create a new storefront zone -b2c ecdn zones create --tenant-id zzxy_prd --domain-name example.com +b2c ecdn zones create --domain-name example.com ``` ### Purge Cache ```bash # purge cache for specific paths -b2c ecdn cache purge --tenant-id zzxy_prd --zone my-zone --path /products --path /categories +b2c ecdn cache purge --zone my-zone --path /products --path /categories # purge by cache tags -b2c ecdn cache purge --tenant-id zzxy_prd --zone my-zone --tag product-123 --tag category-456 +b2c ecdn cache purge --zone my-zone --tag product-123 --tag category-456 ``` ### Manage Certificates ```bash # list certificates for a zone -b2c ecdn certificates list --tenant-id zzxy_prd --zone my-zone +b2c ecdn certificates list --zone my-zone # add a new certificate -b2c ecdn certificates add --tenant-id zzxy_prd --zone my-zone --hostname www.example.com --certificate-file ./cert.pem --private-key-file ./key.pem +b2c ecdn certificates add --zone my-zone --hostname www.example.com --certificate-file ./cert.pem --private-key-file ./key.pem # validate a custom hostname -b2c ecdn certificates validate --tenant-id zzxy_prd --zone my-zone --certificate-id abc123 +b2c ecdn certificates validate --zone my-zone --certificate-id abc123 ``` ### Security Settings ```bash # get security settings -b2c ecdn security get --tenant-id zzxy_prd --zone my-zone +b2c ecdn security get --zone my-zone # update security settings -b2c ecdn security update --tenant-id zzxy_prd --zone my-zone --ssl-mode full --min-tls-version 1.2 --always-use-https +b2c ecdn security update --zone my-zone --ssl-mode full --min-tls-version 1.2 --always-use-https ``` ### Speed Settings ```bash # get speed optimization settings -b2c ecdn speed get --tenant-id zzxy_prd --zone my-zone +b2c ecdn speed get --zone my-zone # update speed settings -b2c ecdn speed update --tenant-id zzxy_prd --zone my-zone --browser-cache-ttl 14400 --auto-minify-html --auto-minify-css +b2c ecdn speed update --zone my-zone --browser-cache-ttl 14400 --auto-minify-html --auto-minify-css ``` ## Additional Topics @@ -84,12 +91,14 @@ For less commonly used eCDN features, see the reference files: - **[SECURITY.md](references/SECURITY.md)** — WAF (v1 and v2), custom firewall rules, rate limiting, and Page Shield (CSP policies, script detection, notification webhooks) - **[ADVANCED.md](references/ADVANCED.md)** — Logpush jobs, MRT routing rules, mTLS certificates, cipher suite configuration, and origin header modification -## Configuration +## Configuration Overrides -The tenant ID can be set via environment variable: -- `SFCC_TENANT_ID`: B2C Commerce tenant ID +The tenant ID can be overridden via flag or environment variable: + +- `--tenant-id` / `SFCC_TENANT_ID` / `tenantId` in dw.json The `--zone` flag accepts either: + - Zone ID (32-character hex string) - Zone name (human-readable, case-insensitive lookup) diff --git a/skills/b2c-cli/skills/b2c-ecdn/references/ADVANCED.md b/skills/b2c-cli/skills/b2c-ecdn/references/ADVANCED.md index e3dfad13..080710d7 100644 --- a/skills/b2c-cli/skills/b2c-ecdn/references/ADVANCED.md +++ b/skills/b2c-cli/skills/b2c-ecdn/references/ADVANCED.md @@ -2,79 +2,81 @@ Logpush, MRT rules, mTLS, cipher suites, and origin header commands for B2C eCDN. +> `tenantId` resolves from `dw.json` / `SFCC_TENANT_ID`. Add `--tenant-id` only to override the active config. + ## Logpush ```bash # create ownership challenge for S3 destination -b2c ecdn logpush ownership --tenant-id zzxy_prd --zone my-zone --destination-path 's3://my-bucket/logs?region=us-east-1' +b2c ecdn logpush ownership --zone my-zone --destination-path 's3://my-bucket/logs?region=us-east-1' # list logpush jobs -b2c ecdn logpush jobs list --tenant-id zzxy_prd --zone my-zone +b2c ecdn logpush jobs list --zone my-zone # create a logpush job -b2c ecdn logpush jobs create --tenant-id zzxy_prd --zone my-zone --name "HTTP logs" --destination-path 's3://my-bucket/logs?region=us-east-1' --log-type http_requests +b2c ecdn logpush jobs create --zone my-zone --name "HTTP logs" --destination-path 's3://my-bucket/logs?region=us-east-1' --log-type http_requests # update a logpush job (enable/disable) -b2c ecdn logpush jobs update --tenant-id zzxy_prd --zone my-zone --job-id 123456 --enabled +b2c ecdn logpush jobs update --zone my-zone --job-id 123456 --enabled # delete a logpush job -b2c ecdn logpush jobs delete --tenant-id zzxy_prd --zone my-zone --job-id 123456 +b2c ecdn logpush jobs delete --zone my-zone --job-id 123456 ``` ## MRT Rules ```bash # get MRT ruleset for a zone -b2c ecdn mrt-rules get --tenant-id zzxy_prd --zone my-zone +b2c ecdn mrt-rules get --zone my-zone # create MRT rules to route to a Managed Runtime environment -b2c ecdn mrt-rules create --tenant-id zzxy_prd --zone my-zone --mrt-hostname customer-pwa.mobify-storefront.com --expressions '(http.host eq "example.com")' +b2c ecdn mrt-rules create --zone my-zone --mrt-hostname customer-pwa.mobify-storefront.com --expressions '(http.host eq "example.com")' # update MRT ruleset hostname -b2c ecdn mrt-rules update --tenant-id zzxy_prd --zone my-zone --mrt-hostname new-customer-pwa.mobify-storefront.com +b2c ecdn mrt-rules update --zone my-zone --mrt-hostname new-customer-pwa.mobify-storefront.com # delete MRT ruleset -b2c ecdn mrt-rules delete --tenant-id zzxy_prd --zone my-zone +b2c ecdn mrt-rules delete --zone my-zone ``` ## mTLS Certificates ```bash # list mTLS certificates (organization level) -b2c ecdn mtls list --tenant-id zzxy_prd +b2c ecdn mtls list # create mTLS certificate for code upload authentication -b2c ecdn mtls create --tenant-id zzxy_prd --name "Build Server" --ca-certificate-file ./ca.pem --leaf-certificate-file ./leaf.pem +b2c ecdn mtls create --name "Build Server" --ca-certificate-file ./ca.pem --leaf-certificate-file ./leaf.pem # get mTLS certificate details -b2c ecdn mtls get --tenant-id zzxy_prd --certificate-id abc123 +b2c ecdn mtls get --certificate-id abc123 # delete mTLS certificate -b2c ecdn mtls delete --tenant-id zzxy_prd --certificate-id abc123 +b2c ecdn mtls delete --certificate-id abc123 ``` ## Cipher Suites ```bash # get cipher suites configuration -b2c ecdn cipher-suites get --tenant-id zzxy_prd --zone my-zone +b2c ecdn cipher-suites get --zone my-zone # update to Modern cipher suite -b2c ecdn cipher-suites update --tenant-id zzxy_prd --zone my-zone --suite-type Modern +b2c ecdn cipher-suites update --zone my-zone --suite-type Modern # update to Custom cipher suite with specific ciphers -b2c ecdn cipher-suites update --tenant-id zzxy_prd --zone my-zone --suite-type Custom --ciphers "ECDHE-ECDSA-AES128-GCM-SHA256,ECDHE-RSA-AES128-GCM-SHA256" +b2c ecdn cipher-suites update --zone my-zone --suite-type Custom --ciphers "ECDHE-ECDSA-AES128-GCM-SHA256,ECDHE-RSA-AES128-GCM-SHA256" ``` ## Origin Headers ```bash # get origin header modification -b2c ecdn origin-headers get --tenant-id zzxy_prd --zone my-zone +b2c ecdn origin-headers get --zone my-zone # set origin header modification (for MRT) -b2c ecdn origin-headers set --tenant-id zzxy_prd --zone my-zone --header-value my-secret-value +b2c ecdn origin-headers set --zone my-zone --header-value my-secret-value # delete origin header modification -b2c ecdn origin-headers delete --tenant-id zzxy_prd --zone my-zone +b2c ecdn origin-headers delete --zone my-zone ``` diff --git a/skills/b2c-cli/skills/b2c-ecdn/references/SECURITY.md b/skills/b2c-cli/skills/b2c-ecdn/references/SECURITY.md index cfe92a0e..6fc93f4a 100644 --- a/skills/b2c-cli/skills/b2c-ecdn/references/SECURITY.md +++ b/skills/b2c-cli/skills/b2c-ecdn/references/SECURITY.md @@ -2,72 +2,74 @@ WAF, firewall rules, rate limiting, and Page Shield commands for B2C eCDN. +> `tenantId` resolves from `dw.json` / `SFCC_TENANT_ID`. Add `--tenant-id` only to override the active config. + ## WAF (Web Application Firewall) ```bash # list WAF v1 groups -b2c ecdn waf groups list --tenant-id zzxy_prd --zone my-zone +b2c ecdn waf groups list --zone my-zone # update WAF v1 group mode -b2c ecdn waf groups update --tenant-id zzxy_prd --zone my-zone --group-id abc123 --mode on +b2c ecdn waf groups update --zone my-zone --group-id abc123 --mode on # list WAF v1 rules in a group -b2c ecdn waf rules list --tenant-id zzxy_prd --zone my-zone --group-id abc123 +b2c ecdn waf rules list --zone my-zone --group-id abc123 # list WAF v2 rulesets -b2c ecdn waf rulesets list --tenant-id zzxy_prd --zone my-zone +b2c ecdn waf rulesets list --zone my-zone # update WAF v2 ruleset -b2c ecdn waf rulesets update --tenant-id zzxy_prd --zone my-zone --ruleset-id abc123 --action block +b2c ecdn waf rulesets update --zone my-zone --ruleset-id abc123 --action block # migrate zone to WAF v2 -b2c ecdn waf migrate --tenant-id zzxy_prd --zone my-zone +b2c ecdn waf migrate --zone my-zone ``` ## Firewall Rules ```bash # list custom firewall rules -b2c ecdn firewall list --tenant-id zzxy_prd --zone my-zone +b2c ecdn firewall list --zone my-zone # create a firewall rule -b2c ecdn firewall create --tenant-id zzxy_prd --zone my-zone --description "Block bad bots" --action block --filter '(cf.client.bot)' +b2c ecdn firewall create --zone my-zone --description "Block bad bots" --action block --filter '(cf.client.bot)' # update a firewall rule -b2c ecdn firewall update --tenant-id zzxy_prd --zone my-zone --rule-id abc123 --action challenge +b2c ecdn firewall update --zone my-zone --rule-id abc123 --action challenge # reorder firewall rules -b2c ecdn firewall reorder --tenant-id zzxy_prd --zone my-zone --rule-ids id1,id2,id3 +b2c ecdn firewall reorder --zone my-zone --rule-ids id1,id2,id3 ``` ## Rate Limiting ```bash # list rate limiting rules -b2c ecdn rate-limit list --tenant-id zzxy_prd --zone my-zone +b2c ecdn rate-limit list --zone my-zone # create a rate limiting rule -b2c ecdn rate-limit create --tenant-id zzxy_prd --zone my-zone --description "API rate limit" --threshold 100 --period 60 --action block --match-url '/api/*' +b2c ecdn rate-limit create --zone my-zone --description "API rate limit" --threshold 100 --period 60 --action block --match-url '/api/*' # delete a rate limiting rule -b2c ecdn rate-limit delete --tenant-id zzxy_prd --zone my-zone --rule-id abc123 +b2c ecdn rate-limit delete --zone my-zone --rule-id abc123 ``` ## Page Shield ```bash # list Page Shield notification webhooks (organization level) -b2c ecdn page-shield notifications list --tenant-id zzxy_prd +b2c ecdn page-shield notifications list # create a notification webhook -b2c ecdn page-shield notifications create --tenant-id zzxy_prd --url https://example.com/webhook --secret my-secret --zones zone1,zone2 +b2c ecdn page-shield notifications create --url https://example.com/webhook --secret my-secret --zones zone1,zone2 # list Page Shield policies (zone level) -b2c ecdn page-shield policies list --tenant-id zzxy_prd --zone my-zone +b2c ecdn page-shield policies list --zone my-zone # create a CSP policy -b2c ecdn page-shield policies create --tenant-id zzxy_prd --zone my-zone --action allow --value script-src +b2c ecdn page-shield policies create --zone my-zone --action allow --value script-src # list detected scripts -b2c ecdn page-shield scripts list --tenant-id zzxy_prd --zone my-zone +b2c ecdn page-shield scripts list --zone my-zone ``` diff --git a/skills/b2c-cli/skills/b2c-scapi-custom/SKILL.md b/skills/b2c-cli/skills/b2c-scapi-custom/SKILL.md index 60872e36..bf6b3302 100644 --- a/skills/b2c-cli/skills/b2c-scapi-custom/SKILL.md +++ b/skills/b2c-cli/skills/b2c-scapi-custom/SKILL.md @@ -9,17 +9,20 @@ Use the `b2c` CLI plugin to manage SCAPI Custom API endpoints and check their re > **Tip:** If `b2c` is not installed globally, use `npx @salesforce/b2c-cli` instead (e.g., `npx @salesforce/b2c-cli scapi custom status`). -## Required: Tenant ID +## Configuration -The `--tenant-id` flag is **required** for all commands. The tenant ID identifies your B2C Commerce instance. +Values like `tenantId` and `shortCode` resolve from `dw.json` / `SFCC_*` env vars / the active instance. Examples below show minimal usage; add flags only to override configured values. If a required value is missing, the CLI emits an actionable error pointing at the flag, env var, and config key. See the `b2c-config` skill for precedence details. -**Important:** The tenant ID is NOT the same as the organization ID: -- **Tenant ID**: `zzxy_prd` (used with commands that require `--tenant-id`) +## Tenant ID vs. Organization ID + +The tenant ID identifies your B2C Commerce instance. It is **not** the same as the organization ID: + +- **Tenant ID**: `zzxy_prd` (the `tenantId` value in dw.json, or `--tenant-id` override) - **Organization ID**: `f_ecom_zzxy_prd` (used in SCAPI URLs, has `f_ecom_` prefix) ### Deriving Tenant ID from Hostname -For sandbox instances, you can derive the tenant ID from the hostname by replacing hyphens with underscores: +For sandbox instances, derive the tenant ID from the hostname by replacing hyphens with underscores: | Hostname | Tenant ID | |----------|-----------| @@ -34,41 +37,44 @@ For production instances, use your realm and instance identifier (e.g., `zzxy_pr ### Get Custom API Endpoint Status ```bash -# list all Custom API endpoints for an organization -b2c scapi custom status --tenant-id zzxy_prd +# list all Custom API endpoints for the configured tenant +b2c scapi custom status # list with JSON output -b2c scapi custom status --tenant-id zzxy_prd --json +b2c scapi custom status --json + +# target a different tenant than the active config +b2c scapi custom status --tenant-id zzxy_prd ``` ### Filter by Status ```bash # list only active endpoints -b2c scapi custom status --tenant-id zzxy_prd --status active +b2c scapi custom status --status active # list only endpoints that failed to register -b2c scapi custom status --tenant-id zzxy_prd --status not_registered +b2c scapi custom status --status not_registered ``` ### Group by Type or Site ```bash # group endpoints by API type (Admin vs Shopper) -b2c scapi custom status --tenant-id zzxy_prd --group-by type +b2c scapi custom status --group-by type # group endpoints by site -b2c scapi custom status --tenant-id zzxy_prd --group-by site +b2c scapi custom status --group-by site ``` ### Customize Output Columns ```bash # show extended columns (includes error reasons, sites, etc.) -b2c scapi custom status --tenant-id zzxy_prd --extended +b2c scapi custom status --extended # select specific columns to display -b2c scapi custom status --tenant-id zzxy_prd --columns type,apiName,status,sites +b2c scapi custom status --columns type,apiName,status,sites # available columns: type, apiName, apiVersion, cartridgeName, endpointPath, httpMethod, status, sites, securityScheme, operationId, schemaFile, implementationScript, errorReason, id ``` @@ -77,14 +83,15 @@ b2c scapi custom status --tenant-id zzxy_prd --columns type,apiName,status,sites ```bash # quickly find and diagnose failed Custom API registrations -b2c scapi custom status --tenant-id zzxy_prd --status not_registered --columns type,apiName,endpointPath,errorReason +b2c scapi custom status --status not_registered --columns type,apiName,endpointPath,errorReason ``` -### Configuration +### Configuration Overrides + +The tenant ID and short code can be overridden via flags or environment variables: -The tenant ID and short code can be set via environment variables: -- `SFCC_TENANT_ID`: Tenant ID (e.g., `zzxy_prd`, not the organization ID) -- `SFCC_SHORTCODE`: SCAPI short code +- `--tenant-id` / `SFCC_TENANT_ID` / `tenantId` in dw.json +- `--short-code` / `SFCC_SHORTCODE` / `shortCode` in dw.json ### More Commands diff --git a/skills/b2c-cli/skills/b2c-scapi-schemas/SKILL.md b/skills/b2c-cli/skills/b2c-scapi-schemas/SKILL.md index a23a98a2..7ef0a671 100644 --- a/skills/b2c-cli/skills/b2c-scapi-schemas/SKILL.md +++ b/skills/b2c-cli/skills/b2c-scapi-schemas/SKILL.md @@ -9,17 +9,20 @@ Use the `b2c` CLI plugin to browse and retrieve SCAPI OpenAPI schema specificati > **Tip:** If `b2c` is not installed globally, use `npx @salesforce/b2c-cli` instead (e.g., `npx @salesforce/b2c-cli scapi schemas list`). -## Required: Tenant ID +## Configuration -The `--tenant-id` flag is **required** for all commands. The tenant ID identifies your B2C Commerce instance. +Values like `tenantId` and `shortCode` resolve from `dw.json` / `SFCC_*` env vars / the active instance. Examples below show minimal usage; add flags only to override configured values. If a required value is missing, the CLI emits an actionable error pointing at the flag, env var, and config key. See the `b2c-config` skill for precedence details. -**Important:** The tenant ID is NOT the same as the organization ID: -- **Tenant ID**: `zzxy_prd` (used with commands that require `--tenant-id`) +## Tenant ID vs. Organization ID + +The tenant ID identifies your B2C Commerce instance for SCAPI calls. It is **not** the same as the organization ID: + +- **Tenant ID**: `zzxy_prd` (the `tenantId` value in dw.json, or `--tenant-id` override) - **Organization ID**: `f_ecom_zzxy_prd` (used in SCAPI URLs, has `f_ecom_` prefix) ### Deriving Tenant ID from Hostname -For sandbox instances, you can derive the tenant ID from the hostname by replacing hyphens with underscores: +For sandbox instances, derive the tenant ID from the hostname by replacing hyphens with underscores: | Hostname | Tenant ID | |----------|-----------| @@ -34,24 +37,27 @@ For production instances, use your realm and instance identifier (e.g., `zzxy_pr ### List Available Schemas ```bash -# list all available SCAPI schemas -b2c scapi schemas list --tenant-id zzxy_prd +# list all available SCAPI schemas (uses configured tenant) +b2c scapi schemas list # list with JSON output -b2c scapi schemas list --tenant-id zzxy_prd --json +b2c scapi schemas list --json + +# target a different tenant than the active config +b2c scapi schemas list --tenant-id zzxy_prd ``` ### Filter Schemas ```bash # filter by API family (e.g., product, checkout, search) -b2c scapi schemas list --tenant-id zzxy_prd --api-family product +b2c scapi schemas list --api-family product # filter by API name -b2c scapi schemas list --tenant-id zzxy_prd --api-name shopper-products +b2c scapi schemas list --api-name shopper-products # filter by status -b2c scapi schemas list --tenant-id zzxy_prd --status current +b2c scapi schemas list --status current ``` ### Get Schema (Collapsed/Outline - Default) @@ -60,10 +66,10 @@ By default, schemas are output in a collapsed format optimized for context effic ```bash # get collapsed schema (paths show methods, schemas show names only) -b2c scapi schemas get product shopper-products v1 --tenant-id zzxy_prd +b2c scapi schemas get product shopper-products v1 # save to file -b2c scapi schemas get product shopper-products v1 --tenant-id zzxy_prd > schema.json +b2c scapi schemas get product shopper-products v1 > schema.json ``` ### Get Schema with Selective Expansion @@ -72,20 +78,20 @@ Expand only the parts of the schema you need: ```bash # expand specific paths -b2c scapi schemas get product shopper-products v1 --tenant-id zzxy_prd --expand-paths /products,/products/{productId} +b2c scapi schemas get product shopper-products v1 --expand-paths /products,/products/{productId} # expand specific schemas -b2c scapi schemas get product shopper-products v1 --tenant-id zzxy_prd --expand-schemas Product,ProductResult +b2c scapi schemas get product shopper-products v1 --expand-schemas Product,ProductResult # combine expansions -b2c scapi schemas get product shopper-products v1 --tenant-id zzxy_prd --expand-paths /products --expand-schemas Product +b2c scapi schemas get product shopper-products v1 --expand-paths /products --expand-schemas Product ``` ### Get Full Schema ```bash # get full schema without any collapsing -b2c scapi schemas get product shopper-products v1 --tenant-id zzxy_prd --expand-all +b2c scapi schemas get product shopper-products v1 --expand-all ``` ### List Available Paths/Schemas/Examples @@ -94,40 +100,41 @@ Discover what's available in a schema before expanding: ```bash # list all paths in the schema -b2c scapi schemas get product shopper-products v1 --tenant-id zzxy_prd --list-paths +b2c scapi schemas get product shopper-products v1 --list-paths # list all schema names -b2c scapi schemas get product shopper-products v1 --tenant-id zzxy_prd --list-schemas +b2c scapi schemas get product shopper-products v1 --list-schemas # list all examples -b2c scapi schemas get product shopper-products v1 --tenant-id zzxy_prd --list-examples +b2c scapi schemas get product shopper-products v1 --list-examples ``` ### Output Formats ```bash # output as YAML -b2c scapi schemas get product shopper-products v1 --tenant-id zzxy_prd --yaml +b2c scapi schemas get product shopper-products v1 --yaml # output wrapped JSON with metadata (apiFamily, apiName, apiVersion, schema) -b2c scapi schemas get product shopper-products v1 --tenant-id zzxy_prd --json +b2c scapi schemas get product shopper-products v1 --json ``` ### Custom Properties ```bash # include custom properties (default behavior) -b2c scapi schemas get product shopper-products v1 --tenant-id zzxy_prd +b2c scapi schemas get product shopper-products v1 # exclude custom properties -b2c scapi schemas get product shopper-products v1 --tenant-id zzxy_prd --no-expand-custom-properties +b2c scapi schemas get product shopper-products v1 --no-expand-custom-properties ``` -### Configuration +### Configuration Overrides + +The tenant ID and short code can be overridden via flags or environment variables: -The tenant ID and short code can be set via environment variables: -- `SFCC_TENANT_ID`: Tenant ID (e.g., `zzxy_prd`, not the organization ID) -- `SFCC_SHORTCODE`: SCAPI short code +- `--tenant-id` / `SFCC_TENANT_ID` / `tenantId` in dw.json +- `--short-code` / `SFCC_SHORTCODE` / `shortCode` in dw.json ### More Commands diff --git a/skills/b2c-cli/skills/b2c-slas/SKILL.md b/skills/b2c-cli/skills/b2c-slas/SKILL.md index 74128b7d..abc68c2f 100644 --- a/skills/b2c-cli/skills/b2c-slas/SKILL.md +++ b/skills/b2c-cli/skills/b2c-slas/SKILL.md @@ -11,6 +11,17 @@ Use the `b2c` CLI plugin to manage SLAS (Shopper Login and API Access Service) A > **Tip:** If `b2c` is not installed globally, use `npx @salesforce/b2c-cli` instead (e.g., `npx @salesforce/b2c-cli slas client list`). +## Configuration + +Values like `tenantId`, `shortCode`, `slasClientId`, and `slasClientSecret` resolve from `dw.json` / `SFCC_*` env vars / the active instance. Examples below show minimal usage; add flags only to override configured values. If a required value is missing, the CLI emits an actionable error pointing at the flag, env var, and config key. See the `b2c-config` skill for precedence details. + +Relevant overrides: + +- `--tenant-id` / `SFCC_TENANT_ID` / `tenantId` +- `--short-code` / `SFCC_SHORTCODE` / `shortCode` +- `--slas-client-id` / `SFCC_SLAS_CLIENT_ID` / `slasClientId` +- `--slas-client-secret` / `SFCC_SLAS_CLIENT_SECRET` / `slasClientSecret` + ## When to Use Common scenarios requiring SLAS client management: @@ -24,37 +35,40 @@ Common scenarios requiring SLAS client management: ### List SLAS Clients ```bash -# list all SLAS clients for a tenant -b2c slas client list --tenant-id abcd_123 +# list all SLAS clients for the configured tenant +b2c slas client list + +# JSON output +b2c slas client list --json -# list with JSON output -b2c slas client list --tenant-id abcd_123 --json +# target a different tenant than the active config +b2c slas client list --tenant-id abcd_123 ``` ### Get SLAS Client Details ```bash # get details for a specific SLAS client -b2c slas client get my-client-id --tenant-id abcd_123 +b2c slas client get my-client-id ``` ### Create SLAS Client ```bash # create a new SLAS client with default scopes (auto-generates UUID client ID) -b2c slas client create --tenant-id abcd_123 --channels RefArch --default-scopes --redirect-uri http://localhost:3000/callback +b2c slas client create --channels RefArch --default-scopes --redirect-uri http://localhost:3000/callback # create with a specific client ID and custom scopes -b2c slas client create my-client-id --tenant-id abcd_123 --channels RefArch --scopes sfcc.shopper-products,sfcc.shopper-search --redirect-uri http://localhost:3000/callback +b2c slas client create my-client-id --channels RefArch --scopes sfcc.shopper-products,sfcc.shopper-search --redirect-uri http://localhost:3000/callback # create a public client -b2c slas client create --tenant-id abcd_123 --channels RefArch --default-scopes --redirect-uri http://localhost:3000/callback --public +b2c slas client create --channels RefArch --default-scopes --redirect-uri http://localhost:3000/callback --public # create client without auto-creating tenant (if you manage tenants separately) -b2c slas client create --tenant-id abcd_123 --channels RefArch --default-scopes --redirect-uri http://localhost:3000/callback --no-create-tenant +b2c slas client create --channels RefArch --default-scopes --redirect-uri http://localhost:3000/callback --no-create-tenant # output as JSON (useful for capturing the generated secret) -b2c slas client create --tenant-id abcd_123 --channels RefArch --default-scopes --redirect-uri http://localhost:3000/callback --json +b2c slas client create --channels RefArch --default-scopes --redirect-uri http://localhost:3000/callback --json ``` Note: By default, the tenant is automatically created if it doesn't exist. @@ -69,7 +83,6 @@ When testing a Custom API that requires custom scopes: # Create a private client with custom scope for testing # Replace c_my_scope with your API's custom scope from schema.yaml b2c slas client create \ - --tenant-id zzpq_013 \ --channels RefArch \ --default-scopes \ --scopes "c_my_scope" \ @@ -83,62 +96,52 @@ b2c slas client create \ ### Get a Shopper Token -Use `b2c slas token` to obtain a shopper access token for API testing: +Use `b2c slas token` to obtain a shopper access token for API testing. The `--site-id` is specific to the request and must be provided per call. ```bash # Guest token with auto-discovery (finds first public SLAS client) -b2c slas token --tenant-id abcd_123 --site-id RefArch - -# Guest token with explicit client (public PKCE flow) -b2c slas token --slas-client-id my-client --tenant-id abcd_123 --short-code kv7kzm78 --site-id RefArch - -# Guest token with private client (client_credentials flow) -b2c slas token --slas-client-id my-client --slas-client-secret sk_xxx --tenant-id abcd_123 --short-code kv7kzm78 --site-id RefArch +b2c slas token --site-id RefArch # Registered customer token -b2c slas token --tenant-id abcd_123 --site-id RefArch --shopper-login user@example.com --shopper-password secret +b2c slas token --site-id RefArch --shopper-login user@example.com --shopper-password secret # JSON output (includes refresh token, expiry, usid, etc.) -b2c slas token --tenant-id abcd_123 --site-id RefArch --json +b2c slas token --site-id RefArch --json # Use token in a subsequent API call -TOKEN=$(b2c slas token --tenant-id abcd_123 --site-id RefArch) -curl -H "Authorization: Bearer $TOKEN" "https://kv7kzm78.api.commercecloud.salesforce.com/..." -``` +TOKEN=$(b2c slas token --site-id RefArch) +curl -H "Authorization: Bearer $TOKEN" "https://$SHORTCODE.api.commercecloud.salesforce.com/..." -The `--slas-client-id` and `--slas-client-secret` can also be set via `SFCC_SLAS_CLIENT_ID` and `SFCC_SLAS_CLIENT_SECRET` environment variables, or `slasClientId` and `slasClientSecret` in dw.json. +# Override the SLAS client explicitly (e.g., targeting a private client for client_credentials flow) +b2c slas token --site-id RefArch --slas-client-id my-client --slas-client-secret sk_xxx +``` ### Update SLAS Client ```bash # update the display name -b2c slas client update my-client-id --tenant-id abcd_123 --name "New Name" +b2c slas client update my-client-id --name "New Name" # rotate the client secret -b2c slas client update my-client-id --tenant-id abcd_123 --secret new-secret-value +b2c slas client update my-client-id --secret new-secret-value # add scopes (appends to existing by default) -b2c slas client update my-client-id --tenant-id abcd_123 --scopes sfcc.shopper-baskets +b2c slas client update my-client-id --scopes sfcc.shopper-baskets # replace scopes instead of appending -b2c slas client update my-client-id --tenant-id abcd_123 --scopes sfcc.shopper-baskets --replace +b2c slas client update my-client-id --scopes sfcc.shopper-baskets --replace # replace channels -b2c slas client update my-client-id --tenant-id abcd_123 --channels RefArch,SiteGenesis --replace +b2c slas client update my-client-id --channels RefArch,SiteGenesis --replace ``` ### Delete SLAS Client ```bash # delete a SLAS client -b2c slas client delete my-client-id --tenant-id abcd_123 +b2c slas client delete my-client-id ``` -### Configuration - -The tenant ID can be set via environment variable: -- `SFCC_TENANT_ID`: SLAS tenant ID (organization ID) - ### More Commands See `b2c slas --help` for a full list of available commands and options in the `slas` topic. diff --git a/skills/b2c-cli/skills/b2c-users-roles/SKILL.md b/skills/b2c-cli/skills/b2c-users-roles/SKILL.md index 6ccffb6f..137adabd 100644 --- a/skills/b2c-cli/skills/b2c-users-roles/SKILL.md +++ b/skills/b2c-cli/skills/b2c-users-roles/SKILL.md @@ -89,7 +89,10 @@ b2c am clients password my-client-id --current "oldPass" --new "newPass123" BM role commands operate on a specific Commerce Cloud instance (via `--server` or config). ```bash -# list BM roles on an instance +# list BM 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 (with user list)