CLI Limitations

This document outlines the core limitations of the Contentstack CLI across various functional areas, including compatibility, authentication, export/import behaviors, and system requirements. Each limitation is clearly explained with its corresponding impact and actionable workarounds to help you troubleshoot or plan your CLI usage more effectively.

• Core CLI Limitations
  Node.js compatibility and supported operating systems.
• Authentication Module Limitations
  Covers MFA handling, management token behavior, and organization switching.
• Export Module Limitations
  Highlights restrictions related to version history, API rate limits, and unsupported modules during export.
• Import Module Limitations
  Includes limitations in importing workflows, historical data, and payload handling.

Limitation: The CLI requires Node.js version 18.0.0 or higher (recommended: 20.x or 22.x).

Impact: The CLI does not support Node.js versions below 18.0.0.

Workaround:

• Install a supported Node.js version (20.0.0 or higher; till 22.x).
• Use nvm for version management:
  
  nvm install 20
  nvm use 20

Related Commands:

• node --version
• npm install -g @contentstack/cli@latest

Version Information: All CLI versions

Limitation: The CLI is tested and officially supported on the following operating systems:

• macOS (latest versions)
• Linux (Ubuntu, Debian, CentOS)
• Windows (10, 11)

Impact: Other operating systems may function, but they are not officially supported.

Workaround:

• Use Docker on unsupported operating systems.
• Use a supported operating system for production environments.

Related Commands:

• csdx --version

Version Information: All CLI versions

Limitation: Management tokens do not expire automatically but can be manually revoked.

Impact: Tokens remain valid until manually revoked, which poses a potential security risk if not rotated.

Workaround:

• Rotate tokens regularly (every 90 days is recommended).
• Monitor token usage.
• Revoke unused tokens.

Related Commands:

• csdx auth:tokens
• csdx auth:tokens:remove

Version Information: All CLI versions

Limitation: MFA requires manual code entry or the use of an OAuth flow.

Impact: MFA-enabled accounts cannot be fully automated without the CONTENTSTACK_MFA_SECRET.

Workaround:

• Use OAuth for SSO accounts by running: csdx auth:login --oauth
• Set the CONTENTSTACK_MFA_SECRET environment variable to enable automatic OTP generation.
• Use Management Tokens to bypass MFA after they are added.

Related Commands:

• csdx auth:login
• csdx auth:login --oauth

Version Information: All CLI versions

Limitation: The CLI does not include a built-in organization switcher.

Impact: You must log out and log back in or use different token aliases to switch between organizations.

Workaround:

• Use different management token aliases for each organization.
• Log out and log back in to switch between organizations.

Related Commands:

• csdx auth:logout
• csdx auth:login
• csdx auth:tokens:add --management

Version Information: All CLI versions

Limitation: Only the latest version of published entries and assets is exported.

Impact: Historical versions are not preserved during export.

Workaround:

• Export creates new versions in the destination stack.
• Historical versions cannot be restored.

Related Commands:

• csdx cm:stacks:export

Version Information: All versions

Limitation: The default maxContentLength and maxBodyLength values are 100 MB.

Impact: Large exports fail if they exceed the payload size limit.

Workaround:

• Update the configuration file with the following values:
  {
    "maxContentLength": 200000000,
    "maxBodyLength": 200000000
  }

• Process exports in smaller batches.
• Export specific modules.

Related Commands:

• csdx cm:stacks:export --config

Limitation: Export operations may encounter concurrency issues.

Impact: Large exports may fail or be throttled.

Workaround:

• Add the delayMs parameter to the configuration file (for example, delayMs: 1000 for 1-second delays).
• Export in smaller batches using the --module flag.
• Configure rate limits using the csdx config:set:rate-limit command.

Related Commands:

• csdx cm:stacks:export --config
• csdx config:set:rate-limit

Limitation: The following modules cannot be exported:

• Users
• Releases

Impact: User data and release information cannot be migrated via CLI.

Workaround:

• Users must be manually added to the destination stack.
• Releases must be recreated manually.

Related Commands:

• csdx cm:stacks:export

Version Information: All versions

Limitation: Only the latest version of published entries and assets is imported.

Impact: Historical versions are not restored during import.

Workaround:

• Import creates new versions in the destination stack.
• Historical versions cannot be restored.

Related Commands:

• csdx cm:stacks:import

Version Information: All versions

Limitation: When importing workflows, admins and workflow stage users are not included in the migration.

Impact: Workflow configurations are imported, but user assignments are lost.

Workaround:

• Manually reassign workflow users after import.
• Update workflow stages with the correct users.

Related Commands:

• csdx cm:stacks:import --module workflows

Limitation: The default maxContentLength and maxBodyLength values are 100 MB.

Impact: Large imports fail if they exceed the payload size limit.

Workaround:

• Update the configuration file with the following values:
  {
    "maxContentLength": 200000000,
    "maxBodyLength": 200000000
  }

• Process imports in smaller batches.
• Export or import specific modules.

Related Commands:

• csdx cm:stacks:import --config

Limitation: Import operations may encounter concurrency issues.

Impact: Large imports may fail or be throttled.

Workaround:

• Add the delayMs parameter to the configuration file (for example, delayMs: 1000 for 1-second delays).
• Import in smaller batches using the --module flag.
• Configure rate limits using the csdx config:set:rate-limit command.

Related Commands:

• csdx cm:stacks:import --config
• csdx config:set:rate-limit

Limitation: The following modules cannot be imported:

• Users
• Releases

Impact: User data and release information cannot be migrated via the CLI.

Workaround:

• Users must be manually added to the destination stack.
• Releases must be recreated manually.

Related Commands:

• csdx cm:stacks:import

Version Information: All versions