Contentstack LogoContentstack Logo

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.

Scope of Limitations

Core CLI Limitations

Node.js Version Requirements

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:

Related Commands:

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

Version Information: All CLI versions

Operating System Support

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

Authentication Module Limitations

Management Token Expiration

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

MFA Support Limitations

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

Organization Switching

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

Export Module Limitations

Version History

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

Payload Size Limits

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

API Request Timing

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

Unsupported Modules

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

Import Module Limitations

Version History

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

Workflow Users

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

Payload Size Limits

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

API Request Timing

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

Unsupported Modules

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

Was this article helpful?

More articles in "Miscellaneous"

Bootstrap Starter Apps

Learn more

CLI FAQs

Learn more
^