Merge pull request #2659 from contentstack/v2-dev

DX | 27-07-2026 | Release | CLI Beta

Author: cs-raj

.talismanrc

@@ -1,4 +1,6 @@
 fileignoreconfig:
   - filename: pnpm-lock.yaml
-    checksum: 64ca5ee7000d70e76ba367e3cacc2158e5cd33e41c7844fb6af79837a9469bb6
+    checksum: 117b66122d3f3043f48724ff9755ec2d4a9dff3c156ceedef753df3014cafee6
+  - filename: packages/contentstack/src/hooks/init/opt-in-plugin-guide.ts
+    checksum: 2b079a93988e2439a03c401f75695fcdbfeb138a75c84707e4bc892536680e9f
 version: '1.0'

MIGRATION.md

@@ -189,6 +189,45 @@ csdx cm:entries:publish --content-types blog --environments prod --locales en-us
 csdx cm:stacks:bulk-entries --operation publish --content-types blog --environments prod --locales en-us -k blt123
 ```
 
+### 7. 🚀 Launch Plugin Now Opt-In
+
+**What Changed:**
+- The `launch` plugin (`@contentstack/cli-launch`) is no longer bundled with the CLI
+- All `launch:*` commands now require installing the plugin explicitly before use
+- Brings `launch` in line with the opt-in, modular plugin model used elsewhere in 2.x
+
+> ⚠️ **This is a change relative to the 2.x beta — not only relative to 1.x.** `@contentstack/cli-launch` was bundled throughout the 1.x releases **and** the entire 2.x beta period, so `launch:*` worked out of the box for beta users too. Starting with 2.x GA it becomes opt-in, so beta users who rely on `launch:*` are also affected when they upgrade.
+
+**Before (1.x.x and 2.x.x-beta):**
+- `launch:*` commands were bundled with the CLI and available by default after installation
+
+**After (2.x.x GA):**
+- `launch:*` commands are provided by a separate, opt-in plugin that must be installed explicitly
+- Running any `launch:*` command without the plugin installed fails with a `command not found` error where it previously worked out of the box
+
+**Affected commands:** `launch`, `launch:deployments`, `launch:environments`, `launch:functions`, `launch:logs`, `launch:open`, `launch:rollback`
+
+**Installation Methods:**
+
+
+**Option 1: Using CLI Plugin Manager**
+```bash
+csdx plugins:install @contentstack/cli-launch
+```
+
+**Option 2: Using npm**
+```bash
+npm install -g @contentstack/cli-launch
+```
+
+**Usage:**
+After installation, launch commands will be available through the CLI:
+```bash
+csdx launch --help
+```
+
+**Migration Action:** If you use any `launch:*` command, install the `@contentstack/cli-launch` plugin before (or immediately after) upgrading to 2.x GA to avoid `command not found` errors. This applies to 2.x beta users as well, since `launch` was bundled during the beta.
+
 ## Troubleshooting
 
 ### Common Issues
@@ -209,6 +248,11 @@ csdx cm:stacks:bulk-entries --operation publish --content-types blog --environme
 - The 2.x.x-beta version should be faster due to TypeScript modules
 - If you are experiencing issues, switch to console log mode for debugging
 
+**5. `launch:*` command not found:**
+- In 2.x GA, `launch` is an opt-in plugin and is no longer bundled (it was bundled in 1.x and during the 2.x beta)
+- Install it with `csdx plugins:install @contentstack/cli-launch`, then re-run your `launch:*` command
+- Verify it is installed with `csdx plugins`
+
 ### Getting Help
 
 **Documentation:**

packages/contentstack-auth/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@contentstack/cli-auth",
   "description": "Contentstack CLI plugin for authentication activities",
-  "version": "2.0.0-beta.16",
+  "version": "2.0.0-beta.17",
   "author": "Contentstack",
   "bugs": "https://github.com/contentstack/cli/issues",
   "scripts": {
@@ -15,8 +15,8 @@
     "lint": "eslint src/**/*.ts"
   },
   "dependencies": {
-    "@contentstack/cli-command": "~2.0.0-beta.10",
-    "@contentstack/cli-utilities": "~2.0.0-beta.11",
+    "@contentstack/cli-command": "~2.0.0-beta.11",
+    "@contentstack/cli-utilities": "~2.0.0-beta.12",
     "@oclif/core": "^4.11.4",
     "otplib": "^12.0.1"
   },

packages/contentstack-command/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@contentstack/cli-command",
   "description": "Contentstack CLI plugin for configuration",
-  "version": "2.0.0-beta.10",
+  "version": "2.0.0-beta.11",
   "author": "Contentstack",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",
@@ -14,7 +14,7 @@
     "lint": "eslint src/**/*.ts"
   },
   "dependencies": {
-    "@contentstack/cli-utilities": "~2.0.0-beta.11",
+    "@contentstack/cli-utilities": "~2.0.0-beta.12",
     "contentstack": "^3.27.0",
     "@oclif/core": "^4.11.4"
   },
@@ -66,4 +66,4 @@
     "url": "git+https://github.com/contentstack/cli.git",
     "directory": "packages/contentstack-command"
   }
-}
+}

packages/contentstack-command/src/index.ts

@@ -14,7 +14,7 @@ abstract class ContentstackCommand extends Command {
 
   get context() {
     // @ts-ignore
-    return this.config.context || {};
+    return this.config.context || this.config.options?.context || {};
   }
 
   get email() {

packages/contentstack-config/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@contentstack/cli-config",
   "description": "Contentstack CLI plugin for configuration",
-  "version": "2.0.0-beta.14",
+  "version": "2.0.0-beta.15",
   "author": "Contentstack",
   "scripts": {
     "build": "pnpm compile && oclif manifest && oclif readme",
@@ -14,8 +14,8 @@
     "lint": "eslint src/**/*.ts"
   },
   "dependencies": {
-    "@contentstack/cli-command": "~2.0.0-beta.10",
-    "@contentstack/cli-utilities": "~2.0.0-beta.11",
+    "@contentstack/cli-command": "~2.0.0-beta.11",
+    "@contentstack/cli-utilities": "~2.0.0-beta.12",
     "@contentstack/utils": "~1.9.1",
     "@oclif/core": "^4.11.4"
   },
@@ -95,4 +95,4 @@
     "url": "git+https://github.com/contentstack/cli.git",
     "directory": "packages/contentstack-config"
   }
-}
+}

packages/contentstack-config/src/commands/config/set/region.ts

@@ -48,6 +48,9 @@ export default class RegionSetCommand extends BaseCommand<typeof RegionSetComman
     'cs-assets': _flags.string({
       description: 'Custom host to set for Contentstack Assets API',
     }),
+    'auth-api': _flags.string({
+      description: 'Custom host to set for Auth API',
+    }),
   };
   static examples = [
     '$ csdx config:set:region',
@@ -82,6 +85,7 @@ export default class RegionSetCommand extends BaseCommand<typeof RegionSetComman
     let launchHubUrl = regionSetFlags['launch'];
     let composableStudioUrl = regionSetFlags['studio'];
     let csAssetsUrl = regionSetFlags['cs-assets'];
+    let authUrl = regionSetFlags['auth-api'];
     let selectedRegion = args.region;
     if (!(cda && cma && uiHost && name) && !selectedRegion) {
       selectedRegion = await interactive.askRegions();
@@ -115,6 +119,9 @@ export default class RegionSetCommand extends BaseCommand<typeof RegionSetComman
         if (!csAssetsUrl) {
           csAssetsUrl = this.transformUrl(cma, 'am-api');
         }
+        if (!authUrl) {
+          authUrl = this.transformUrl(cma, 'auth-api');
+        }
         let customRegion: Region = {
           cda,
           cma,
@@ -125,6 +132,17 @@ export default class RegionSetCommand extends BaseCommand<typeof RegionSetComman
           launchHubUrl,
           composableStudioUrl,
           csAssetsUrl,
+          endpoints: {
+            contentManagement: cma,
+            contentDelivery: cda,
+            application: uiHost,
+            developerHub: developerHubUrl,
+            launch: launchHubUrl,
+            personalizeManagement: personalizeUrl,
+            composableStudio: composableStudioUrl,
+            assetManagement: csAssetsUrl,
+            auth: authUrl,
+          },
         };
         customRegion = regionHandler.setCustomRegion(customRegion);
         await authHandler.setConfigData('logout'); //Todo: Handle this logout flow well through logout command call
@@ -137,6 +155,7 @@ export default class RegionSetCommand extends BaseCommand<typeof RegionSetComman
         cliux.success(`Launch URL: ${customRegion.launchHubUrl}`);
         cliux.success(`Studio URL: ${customRegion.composableStudioUrl}`);
         cliux.success(`Contentstack Assets URL: ${customRegion.csAssetsUrl}`);
+        cliux.success(`Auth API URL: ${customRegion.endpoints?.auth}`);
       } catch (error) {
         handleAndLogError(error, { ...this.contextDetails, module: 'config-set-region' });
       }

packages/contentstack-config/src/interfaces/index.ts

@@ -20,6 +20,7 @@ export interface Region {
   launchHubUrl: string;
   composableStudioUrl: string;
   csAssetsUrl?: string;
+  endpoints?: Record<string, string>;
 }
 
 export interface Limit {

packages/contentstack-config/src/utils/region-handler.ts

@@ -1,5 +1,4 @@
-import { configHandler } from '@contentstack/cli-utilities';
-import { getContentstackEndpoint } from '@contentstack/utils';
+import { configHandler, resolveCanonicalEndpoints, buildRegionFromEndpoints } from '@contentstack/cli-utilities';
 import { Region, RegionsMap } from '../interfaces';
 
 function validURL(str) {
@@ -23,28 +22,10 @@ function validURL(str) {
  * @returns {object} Region object with all necessary URLs
  */
 function getRegionObject(regionKey: string): Region {
-  try {
-    // getContentstackEndpoint handles all aliases defined in regions.json
-    const endpoints = getContentstackEndpoint(regionKey) as any;
-
-    if (typeof endpoints === 'string') {
-      throw new Error('Invalid endpoint response');
-    }
-
-    return {
-      name: regionKey,
-      cma: endpoints.contentManagement,
-      cda: endpoints.contentDelivery,
-      uiHost: endpoints.application,
-      developerHubUrl: endpoints.developerHub,
-      launchHubUrl: endpoints.launch,
-      personalizeUrl: endpoints.personalizeManagement,
-      composableStudioUrl: endpoints.composableStudio,
-      csAssetsUrl: endpoints.assetManagement,
-    };
-  } catch {
-    return null;
-  }
+  // resolveCanonicalEndpoints handles all aliases defined in regions.json
+  const endpoints = resolveCanonicalEndpoints(regionKey);
+  if (!endpoints) return null;
+  return buildRegionFromEndpoints(regionKey, endpoints) as Region;
 }
 
 /**
@@ -147,19 +128,23 @@ class UserConfig {
    * @returns { object } JSON object with only valid keys for region
    */
   sanitizeRegionObject(regionObject) {
-    const sanitizedRegion = {
-      cma: regionObject.cma,
-      cda: regionObject.cda,
-      uiHost: regionObject.uiHost,
-      name: regionObject.name,
-      developerHubUrl: regionObject['developerHubUrl'],
-      personalizeUrl: regionObject['personalizeUrl'],
-      launchHubUrl: regionObject['launchHubUrl'],
-      composableStudioUrl: regionObject['composableStudioUrl'],
-      csAssetsUrl: regionObject['csAssetsUrl'],
+    // endpoints is the single source of truth — every friendly field (cma, cda, ...,
+    // auth, csAssetsUrl) is derived from it below via buildRegionFromEndpoints, same
+    // as named regions. Falls back to synthesizing endpoints from the individual raw
+    // fields when the caller didn't supply one directly.
+    const endpoints = regionObject['endpoints'] ?? {
+      contentManagement: regionObject.cma,
+      contentDelivery: regionObject.cda,
+      application: regionObject.uiHost,
+      developerHub: regionObject['developerHubUrl'],
+      launch: regionObject['launchHubUrl'],
+      personalizeManagement: regionObject['personalizeUrl'],
+      composableStudio: regionObject['composableStudioUrl'],
+      assetManagement: regionObject['csAssetsUrl'],
+      auth: regionObject['authUrl'],
     };
 
-    return sanitizedRegion;
+    return buildRegionFromEndpoints(regionObject.name, endpoints);
   }
 }
 

packages/contentstack-config/test/unit/commands/region.test.ts

@@ -313,7 +313,87 @@ describe('Region command', function () {
       csAssetsUrl: 'https://custom-asset-management.com',
     };
     const result = UserConfig.setCustomRegion(customRegion);
-    expect(result).to.deep.equal(customRegion);
+    expect(result.cma).to.equal(customRegion.cma);
+    expect(result.cda).to.equal(customRegion.cda);
+    expect(result.uiHost).to.equal(customRegion.uiHost);
+    expect(result.name).to.equal(customRegion.name);
+    expect(result.developerHubUrl).to.equal(customRegion.developerHubUrl);
+    expect(result.personalizeUrl).to.equal(customRegion.personalizeUrl);
+    expect(result.launchHubUrl).to.equal(customRegion.launchHubUrl);
+    expect(result.composableStudioUrl).to.equal(customRegion.composableStudioUrl);
+  });
+
+  it('should include a matching endpoints object for a custom region without an auth host', function () {
+    const customRegion = {
+      cma: 'https://custom-cma.com',
+      cda: 'https://custom-cda.com',
+      uiHost: 'https://custom-ui.com',
+      name: 'Custom Region',
+      developerHubUrl: 'https://custom-developer-hub.com',
+      personalizeUrl: 'https://custom-personalize.com',
+      launchHubUrl: 'https://custom-launch.com',
+      composableStudioUrl: 'https://custom-composable-studio.com',
+    };
+    const result = UserConfig.setCustomRegion(customRegion);
+    expect(result.endpoints).to.deep.equal({
+      contentManagement: customRegion.cma,
+      contentDelivery: customRegion.cda,
+      application: customRegion.uiHost,
+      developerHub: customRegion.developerHubUrl,
+      launch: customRegion.launchHubUrl,
+      personalizeManagement: customRegion.personalizeUrl,
+      composableStudio: customRegion.composableStudioUrl,
+      assetManagement: undefined,
+      auth: undefined,
+    });
+  });
+
+  it('should preserve an explicitly supplied endpoints object for a custom region', function () {
+    const endpoints = {
+      contentManagement: 'https://custom-cma.com',
+      contentDelivery: 'https://custom-cda.com',
+      application: 'https://custom-ui.com',
+      auth: 'https://custom-auth.com',
+    };
+    const customRegion = {
+      cma: 'https://custom-cma.com',
+      cda: 'https://custom-cda.com',
+      uiHost: 'https://custom-ui.com',
+      name: 'Custom Region',
+      endpoints,
+    };
+    const result = UserConfig.setCustomRegion(customRegion);
+    expect(result.cma).to.equal(endpoints.contentManagement);
+    expect(result.cda).to.equal(endpoints.contentDelivery);
+    expect(result.uiHost).to.equal(endpoints.application);
+    expect(result.endpoints).to.deep.equal(endpoints);
+  });
+
+  it('should not fall back to a stale legacy authUrl input once endpoints.auth is supplied', function () {
+    // endpoints is the single source of truth: a stale/mismatched top-level
+    // authUrl on the raw input is never used — only endpoints.auth matters.
+    const customRegion = {
+      cma: 'https://custom-cma.com',
+      cda: 'https://custom-cda.com',
+      uiHost: 'https://custom-ui.com',
+      name: 'Custom Region',
+      authUrl: 'https://stale-auth.com',
+      endpoints: {
+        contentManagement: 'https://custom-cma.com',
+        contentDelivery: 'https://custom-cda.com',
+        application: 'https://custom-ui.com',
+        auth: 'https://correct-auth.com',
+      },
+    };
+    const result = UserConfig.setCustomRegion(customRegion);
+    expect(result.endpoints.auth).to.equal('https://correct-auth.com');
+  });
+
+  it('should include the full endpoints passthrough (incl. auth) for named regions', function () {
+    const result = UserConfig.setRegion('NA');
+    expect(result.endpoints).to.be.an('object');
+    expect(result.endpoints.auth).to.equal('https://auth-api.contentstack.com');
+    expect(result.endpoints.contentManagement).to.equal(result.cma);
   });
 
   it('should sanitize region object to only include valid properties', function () {