Add sfcc-ci migration guide, command aliases, and env var compatibility

Add migration guide at docs/guide/sfcc-ci-migration.md covering authentication
changes, command mapping tables, environment variable compatibility, and CI/CD
migration patterns.

Add hidden command aliases for sfcc-ci backward compatibility (client:auth,
code:deploy, code:list, code:activate, code:delete, job:run, etc.).

Add environment variable fallbacks for sfcc-ci names (SFCC_OAUTH_CLIENT_ID,
SFCC_OAUTH_CLIENT_SECRET, SFCC_LOGIN_URL) in both CLI flags and SDK env source.

Author: clavery

.changeset/sfcc-ci-migration-guide.md

@@ -0,0 +1,7 @@
+---
+'@salesforce/b2c-dx-docs': patch
+'@salesforce/b2c-tooling-sdk': patch
+'@salesforce/b2c-cli': patch
+---
+
+Added sfcc-ci migration guide with command mappings and CI/CD migration instructions. Added backward-compatible sfcc-ci command aliases (`client:auth`, `code:deploy`, `code:list`, `code:activate`, `job:run`, etc.) and environment variable aliases (`SFCC_OAUTH_CLIENT_ID`, `SFCC_OAUTH_CLIENT_SECRET`, `SFCC_LOGIN_URL`).

docs/.vitepress/config.mts

@@ -43,6 +43,7 @@ const guidesSidebar = [
     items: [
       {text: 'Authentication Setup', link: '/guide/authentication'},
       {text: 'CI/CD with GitHub Actions', link: '/guide/ci-cd'},
+      {text: 'sfcc-ci Migration', link: '/guide/sfcc-ci-migration'},
       {text: 'Account Manager', link: '/guide/account-manager'},
       {text: 'Analytics Reports (CIP/CCAC)', link: '/guide/analytics-reports-cip-ccac'},
       {text: 'IDE Integration', link: '/guide/ide-integration'},

docs/guide/sfcc-ci-migration.md

@@ -0,0 +1,215 @@
+---
+description: Migrate from sfcc-ci to @salesforce/b2c-cli with command mappings, environment variable compatibility, and CI/CD pipeline updates.
+---
+
+# Migrating from sfcc-ci
+
+[sfcc-ci](https://github.com/SalesforceCommerceCloud/sfcc-ci) is deprecated. The `@salesforce/b2c-cli` package is its replacement, providing the same core capabilities plus additional features.
+
+If you haven't installed the B2C CLI yet, see the [Installation guide](./installation).
+
+## Authentication
+
+The biggest change from sfcc-ci is how authentication works by default.
+
+**sfcc-ci** uses **stateful auth** — you run `sfcc-ci client:auth` once to store a token, then all subsequent commands use it automatically.
+
+**b2c-cli** defaults to **stateless auth** — credentials are provided per-command via environment variables or flags. This is more explicit and works better in CI/CD pipelines where each step is independent.
+
+### Stateful Auth (sfcc-ci Compatible)
+
+For users who prefer the sfcc-ci workflow, the B2C CLI includes a compatibility layer that mirrors the stateful auth pattern:
+
+| sfcc-ci | b2c-cli |
+|---------|---------|
+| `sfcc-ci client:auth <id> <secret>` | `b2c auth client --client-id <id> --client-secret <secret>` |
+| `sfcc-ci client:auth:renew` | `b2c auth client renew` |
+| `sfcc-ci client:auth:token` | `b2c auth client token` |
+| `sfcc-ci auth:login [client]` | `b2c auth login [client]` |
+| `sfcc-ci auth:logout` | `b2c auth logout` |
+
+The colon-separated forms (`client:auth`, `client:auth:renew`, `client:auth:token`, `auth:login`, `auth:logout`) are also accepted as aliases.
+
+After authenticating, subsequent commands automatically use the stored token when it is valid. See [Auth Commands](/cli/auth) for full details.
+
+### Stateless Auth (Recommended for CI/CD)
+
+For automation and CI/CD, set credentials as environment variables and the CLI uses them directly — no separate auth step needed:
+
+```bash
+export SFCC_CLIENT_ID=my-client-id
+export SFCC_CLIENT_SECRET=my-secret
+
+# Commands authenticate automatically
+b2c code list
+b2c sandbox list
+```
+
+See [Authentication Setup](./authentication) for the full guide including Account Manager configuration, OCAPI permissions, and WebDAV access.
+
+::: tip
+Use **stateless auth** (environment variables) for CI/CD pipelines and **stateful auth** (`b2c auth client` or `b2c auth login`) for local development.
+:::
+
+## Command Mapping
+
+The B2C CLI uses space-separated commands instead of colons (e.g., `code deploy` instead of `code:deploy`). For the most commonly used commands, colon-separated aliases are also accepted for backward compatibility.
+
+### Code Management
+
+| sfcc-ci | b2c-cli | Notes |
+|---------|---------|-------|
+| `sfcc-ci code:list` | `b2c code list` | Also accepts `code:list` |
+| `sfcc-ci code:deploy <archive>` | `b2c code deploy` | Deploys from local cartridge source; also accepts `code:deploy` |
+| `sfcc-ci code:activate <version>` | `b2c code activate <version>` | Also accepts `code:activate` |
+| `sfcc-ci code:delete` | `b2c code delete` | Also accepts `code:delete` |
+
+### Instance / Data
+
+| sfcc-ci | b2c-cli | Notes |
+|---------|---------|-------|
+| `sfcc-ci instance:upload <file>` | `b2c webdav put <file> <remote-path>` | See [WebDAV commands](/cli/webdav) |
+| `sfcc-ci instance:import <archive>` | `b2c content import <archive>` | Or `b2c job run sfcc-site-archive-import` |
+| `sfcc-ci instance:export` | `b2c content export` | See [Content commands](/cli/content) |
+
+### Jobs
+
+| sfcc-ci | b2c-cli | Notes |
+|---------|---------|-------|
+| `sfcc-ci job:run <id>` | `b2c job run <id>` | Also accepts `job:run`; supports `--wait` and `--timeout` |
+| `sfcc-ci job:status <id> <exec>` | `b2c job wait <id> --execution-id <exec>` | |
+
+### Sandbox
+
+Sandbox commands map directly, with spaces replacing colons:
+
+| sfcc-ci | b2c-cli |
+|---------|---------|
+| `sfcc-ci sandbox:list` | `b2c sandbox list` |
+| `sfcc-ci sandbox:create` | `b2c sandbox create` |
+| `sfcc-ci sandbox:get` | `b2c sandbox get` |
+| `sfcc-ci sandbox:delete` | `b2c sandbox delete` |
+| `sfcc-ci sandbox:start` | `b2c sandbox start` |
+| `sfcc-ci sandbox:stop` | `b2c sandbox stop` |
+| `sfcc-ci sandbox:restart` | `b2c sandbox restart` |
+| `sfcc-ci sandbox:reset` | `b2c sandbox reset` |
+| `sfcc-ci sandbox:alias:list` | `b2c sandbox alias list` |
+| `sfcc-ci sandbox:alias:add` | `b2c sandbox alias create` |
+| `sfcc-ci sandbox:alias:delete` | `b2c sandbox alias delete` |
+
+### SLAS
+
+| sfcc-ci | b2c-cli |
+|---------|---------|
+| `sfcc-ci slas:client:add` | `b2c slas client create` |
+| `sfcc-ci slas:client:get` | `b2c slas client get` |
+| `sfcc-ci slas:client:list` | `b2c slas client list` |
+| `sfcc-ci slas:client:delete` | `b2c slas client delete` |
+
+### User / Org / Role (Account Manager)
+
+Account Manager operations are under the `am` topic:
+
+| sfcc-ci | b2c-cli |
+|---------|---------|
+| `sfcc-ci user:list` | `b2c am users list` |
+| `sfcc-ci user:create` | `b2c am users create` |
+| `sfcc-ci user:delete` | `b2c am users delete` |
+| `sfcc-ci org:list` | `b2c am orgs list` |
+| `sfcc-ci role:list` | `b2c am roles list` |
+| `sfcc-ci role:grant` | `b2c am roles grant` |
+| `sfcc-ci role:revoke` | `b2c am roles revoke` |
+
+## Environment Variables
+
+Most sfcc-ci environment variables are supported directly or through backward-compatible aliases. Existing CI/CD configurations using these variables will continue to work.
+
+| sfcc-ci | b2c-cli | Status |
+|---------|---------|--------|
+| `SFCC_OAUTH_CLIENT_ID` | `SFCC_CLIENT_ID` | Both accepted |
+| `SFCC_OAUTH_CLIENT_SECRET` | `SFCC_CLIENT_SECRET` | Both accepted |
+| `SFCC_LOGIN_URL` | `SFCC_ACCOUNT_MANAGER_HOST` | Both accepted |
+| `SFCC_OAUTH_USER_NAME` | `SFCC_OAUTH_USER_NAME` | Same |
+| `SFCC_OAUTH_USER_PASSWORD` | `SFCC_OAUTH_USER_PASSWORD` | Same |
+| `SFCC_SANDBOX_API_HOST` | `SFCC_SANDBOX_API_HOST` | Same |
+| `SFCC_SCAPI_SHORTCODE` | `SFCC_SHORTCODE` | Renamed |
+| `SFCC_SCAPI_TENANTID` | `SFCC_TENANT_ID` | Renamed |
+
+The B2C CLI also introduces new environment variables not present in sfcc-ci:
+
+| Variable | Purpose |
+|----------|---------|
+| `SFCC_SERVER` | B2C instance hostname |
+| `SFCC_USERNAME` | WebDAV / Basic auth username |
+| `SFCC_PASSWORD` | WebDAV / Basic auth password |
+| `SFCC_CODE_VERSION` | Code version for deployments |
+| `SFCC_AUTH_METHODS` | Auth method priority (comma-separated) |
+
+See the [Configuration guide](./configuration) for the complete list of environment variables and configuration sources.
+
+## Configuration
+
+The `dw.json` configuration file is fully supported. Fields are normalized to camelCase (e.g., `client-id` in the file becomes `clientId` internally), but both kebab-case and camelCase are accepted.
+
+The B2C CLI adds a layered configuration system with a clear priority order:
+
+1. CLI flags (highest priority)
+2. Environment variables (`SFCC_*`)
+3. `dw.json` in the current directory
+4. Instance configuration (`b2c setup instance`)
+5. Defaults (lowest priority)
+
+Instance management uses `b2c setup instance create` instead of `sfcc-ci instance:add`. See the [Configuration guide](./configuration) for details.
+
+## CI/CD Migration
+
+### Before (sfcc-ci)
+
+sfcc-ci CI/CD pipelines typically authenticate first, then run commands:
+
+```bash
+# Authenticate (stores token)
+sfcc-ci client:auth $SFCC_OAUTH_CLIENT_ID $SFCC_OAUTH_CLIENT_SECRET
+
+# Deploy code
+sfcc-ci code:deploy build/code.zip -i $INSTANCE
+sfcc-ci code:activate v1 -i $INSTANCE
+```
+
+### After (b2c-cli — stateless)
+
+With the B2C CLI, set environment variables and run commands directly:
+
+```bash
+# No separate auth step — credentials are used automatically
+export SFCC_CLIENT_ID=$SFCC_OAUTH_CLIENT_ID
+export SFCC_CLIENT_SECRET=$SFCC_OAUTH_CLIENT_SECRET
+export SFCC_SERVER=$INSTANCE
+
+b2c code deploy
+b2c code activate v1
+```
+
+### After (b2c-cli — stateful, sfcc-ci compatible)
+
+If you prefer minimal changes to your existing pipeline scripts:
+
+```bash
+# Same pattern as sfcc-ci
+b2c auth client --client-id $SFCC_OAUTH_CLIENT_ID --client-secret $SFCC_OAUTH_CLIENT_SECRET
+
+b2c code deploy
+b2c code activate v1 --server $INSTANCE
+```
+
+### GitHub Actions
+
+The B2C CLI provides official GitHub Actions that handle installation, credential configuration, and caching automatically. See the [CI/CD with GitHub Actions](./ci-cd) guide for complete examples and action reference.
+
+## Next Steps
+
+- [Installation](./installation) — install the B2C CLI
+- [Authentication Setup](./authentication) — configure API clients, OCAPI, and WebDAV
+- [Configuration](./configuration) — environment variables, dw.json, and instance management
+- [CI/CD with GitHub Actions](./ci-cd) — official GitHub Actions for automation
+- [CLI Reference](/cli/) — browse all available commands

packages/b2c-cli/src/commands/auth/client/index.ts

@@ -21,6 +21,8 @@ import {t} from '../../../i18n/index.js';
  * Use --renew to enable automatic token renewal for later use with `auth client renew`.
  */
 export default class AuthClient extends BaseCommand<typeof AuthClient> {
+  static hiddenAliases = ['client:auth'];
+
   static description = t('commands.auth.client.description', 'Authenticate an API client and save session');
 
   static examples = [
@@ -34,16 +36,19 @@ export default class AuthClient extends BaseCommand<typeof AuthClient> {
     'client-id': Flags.string({
       description: 'Client ID for OAuth',
       env: 'SFCC_CLIENT_ID',
+      default: async () => process.env.SFCC_OAUTH_CLIENT_ID || undefined,
       helpGroup: 'AUTH',
     }),
     'client-secret': Flags.string({
       description: 'Client secret for OAuth',
       env: 'SFCC_CLIENT_SECRET',
+      default: async () => process.env.SFCC_OAUTH_CLIENT_SECRET || undefined,
       helpGroup: 'AUTH',
     }),
     'account-manager-host': Flags.string({
       description: `Account Manager hostname for OAuth (default: ${DEFAULT_ACCOUNT_MANAGER_HOST})`,
       env: 'SFCC_ACCOUNT_MANAGER_HOST',
+      default: async () => process.env.SFCC_LOGIN_URL || undefined,
       helpGroup: 'AUTH',
     }),
     'auth-scope': Flags.string({

packages/b2c-cli/src/commands/auth/client/renew.ts

@@ -19,6 +19,8 @@ import {t} from '../../../i18n/index.js';
  * to client_credentials grant using the stored base64-encoded client:secret.
  */
 export default class AuthClientRenew extends BaseCommand<typeof AuthClientRenew> {
+  static hiddenAliases = ['client:auth:renew'];
+
   static description = t('commands.auth.client.renew.description', 'Renew the client authentication token');
 
   static examples = ['<%= config.bin %> <%= command.id %>'];
@@ -27,6 +29,7 @@ export default class AuthClientRenew extends BaseCommand<typeof AuthClientRenew>
     'account-manager-host': Flags.string({
       description: `Account Manager hostname for OAuth (default: ${DEFAULT_ACCOUNT_MANAGER_HOST})`,
       env: 'SFCC_ACCOUNT_MANAGER_HOST',
+      default: async () => process.env.SFCC_LOGIN_URL || undefined,
       helpGroup: 'AUTH',
     }),
   };

packages/b2c-cli/src/commands/auth/client/token.ts

@@ -25,6 +25,8 @@ interface AuthClientTokenOutput {
  * Mirrors sfcc-ci `client:auth:token` command behavior.
  */
 export default class AuthClientToken extends BaseCommand<typeof AuthClientToken> {
+  static hiddenAliases = ['client:auth:token'];
+
   static description = t(
     'commands.auth.client.token.description',
     'Return the current authentication token (stateful)',

packages/b2c-cli/src/commands/auth/login.ts

@@ -15,6 +15,8 @@ import {t, withDocs} from '../../i18n/index.js';
  * until it expires or you run auth:logout.
  */
 export default class AuthLogin extends BaseCommand<typeof AuthLogin> {
+  static hiddenAliases = ['auth:login'];
+
   static args = {
     clientId: Args.string({
       description: 'Client ID for OAuth (falls back to SFCC_CLIENT_ID env var)',
@@ -33,6 +35,7 @@ export default class AuthLogin extends BaseCommand<typeof AuthLogin> {
     'account-manager-host': Flags.string({
       description: `Account Manager hostname for OAuth (default: ${DEFAULT_ACCOUNT_MANAGER_HOST})`,
       env: 'SFCC_ACCOUNT_MANAGER_HOST',
+      default: async () => process.env.SFCC_LOGIN_URL || undefined,
       helpGroup: 'AUTH',
     }),
     'auth-scope': Flags.string({

packages/b2c-cli/src/commands/auth/logout.ts

@@ -13,6 +13,8 @@ import {t, withDocs} from '../../i18n/index.js';
  * (client credentials or implicit) when configured.
  */
 export default class AuthLogout extends BaseCommand<typeof AuthLogout> {
+  static hiddenAliases = ['auth:logout'];
+
   static description = withDocs(
     t('commands.auth.logout.description', 'Clear stored session (stateful auth)'),
     '/cli/auth.html#b2c-auth-logout',

packages/b2c-cli/src/commands/code/activate.ts

@@ -9,6 +9,8 @@ import {activateCodeVersion, reloadCodeVersion} from '@salesforce/b2c-tooling-sd
 import {t, withDocs} from '../../i18n/index.js';
 
 export default class CodeActivate extends InstanceCommand<typeof CodeActivate> {
+  static hiddenAliases = ['code:activate'];
+
   static args = {
     codeVersion: Args.string({
       description: 'Code version ID to activate',

packages/b2c-cli/src/commands/code/delete.ts

@@ -27,6 +27,8 @@ async function confirm(message: string): Promise<boolean> {
 }
 
 export default class CodeDelete extends InstanceCommand<typeof CodeDelete> {
+  static hiddenAliases = ['code:delete'];
+
   static args = {
     codeVersion: Args.string({
       description: 'Code version ID to delete',