{"id":17555,"library":"contentful-cli","title":"Contentful CLI","description":"The Contentful CLI (Command Line Interface) tool allows developers to interact with Contentful features directly from their terminal. It supports managing spaces (listing, creating, deleting), exporting and importing content, executing and generating migration scripts using the Contentful Migration DSL, seeding spaces with example data, and managing extensions. The current stable version is `4.0.0`. The project maintains an active release cadence, with minor and patch versions frequently released, often monthly or bi-monthly, addressing bugs and adding new features like organization security checks. Its key differentiators include deep integration with Contentful's content management and delivery APIs, robust migration capabilities, and recently, features for assessing organization security posture. It is a critical tool for automating content workflows and managing Contentful projects programmatically.","status":"active","version":"4.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/contentful/contentful-cli","tags":["javascript"],"install":[{"cmd":"npm install contentful-cli","lang":"bash","label":"npm"},{"cmd":"yarn add contentful-cli","lang":"bash","label":"yarn"},{"cmd":"pnpm add contentful-cli","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Runtime environment, specifically Node.js >=22 is required since v4.0.0.","package":"node","optional":false},{"reason":"Internal dependency for interacting with the Contentful Management API; bumped to v12 in CLI v4.0.0.","package":"contentful-management","optional":false},{"reason":"Internal dependency for exporting Contentful spaces; bumped to v8 in CLI v4.0.0.","package":"contentful-export","optional":false},{"reason":"Internal dependency for batch operations; bumped to v11 in CLI v4.0.0.","package":"contentful-batch-libs","optional":false}],"imports":[{"note":"This package is a global CLI tool, not a library to be imported into other JavaScript/TypeScript projects directly. It is invoked via the `contentful` command in the terminal after global installation.","wrong":"import { contentful } from 'contentful-cli'","symbol":"contentful","correct":"npm install -g contentful-cli"},{"note":"The primary way to authenticate is via `contentful login`, which uses OAuth. Manual token configuration is less common for initial setup but possible for CI/CD with `contentful config add --management-token <TOKEN>`.","wrong":"contentful auth --token <YOUR_TOKEN>","symbol":"Login/Auth","correct":"contentful login"},{"note":"Configuration settings are managed via the `contentful config add` command, which persists settings to a `.contentfulrc.json` file. Direct file editing is also possible but not recommended for programmatic changes.","wrong":"contentful config set host=api.eu.contentful.com","symbol":"Configuration","correct":"contentful config add --host api.eu.contentful.com"}],"quickstart":{"code":"# Install the Contentful CLI globally\nnpm install -g contentful-cli\n\n# Log in to your Contentful account (this will open a browser for OAuth)\ncontentful login\n\n# List all available spaces for your account\ncontentful space list\n\n# Export a space to a JSON file\n# Replace <SPACE_ID> with your actual Space ID and <FILE_NAME> with your desired output file name\n# You can find your Space ID in the Contentful web app URL or via 'contentful space list'\n# Example: contentful space export --space-id 'your_space_id' --output 'exported-space.json'\ncontentful space export --space-id <YOUR_SPACE_ID> --output exported-space.json\n\n# Get help for a specific command\ncontentful migration --help","lang":"bash","description":"Demonstrates global installation, logging into Contentful via OAuth, listing spaces, exporting a space, and accessing command-specific help."},"warnings":[{"fix":"Upgrade your Node.js runtime to version 22 or newer (e.g., using nvm: `nvm install 22 && nvm use 22`). If you rely on internal API details of Contentful libraries, review their changelogs for breaking changes in v12, v11, and v8 respectively.","message":"Version 4.0.0 introduces a breaking change by requiring Node.js version 22 or higher. Older Node.js versions are no longer supported. This release also updates internal dependencies to `contentful-management` v12, `contentful-batch-libs` v11, and `contentful-export` v8, which may introduce further breaking changes within those libraries' APIs.","severity":"breaking","affected_versions":">=4.0.0"},{"fix":"Ensure your proxy settings are correctly ordered. For environment variables, set `https_proxy` if applicable. For `.contentfulrc.json`, use `contentful config add --proxy user:auth@host:port`. If encountering connection problems with a proxy, try `contentful config add --raw-proxy`.","message":"When using the CLI with a proxy, there's a specific order of precedence for configuration. Environment variables (`https_proxy`, `http_proxy`) override settings in `.contentfulrc.json`, and `https_proxy` takes precedence over `http_proxy`. Incorrect precedence or misconfiguration can lead to connectivity issues.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Configure the CLI for EU usage by running `contentful config add --host api.eu.contentful.com --host-delivery cdn.eu.contentful.com`. This will persist the EU host configuration for all subsequent commands.","message":"For users operating in the Contentful EU region, the CLI by default connects to the global Contentful API endpoints. Failing to configure EU-specific hosts will result in attempting to authenticate and manage resources in the wrong region.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"After installation, try opening a new terminal window or tab. If the issue persists, verify your npm/yarn global installation directory is included in your system's PATH environment variable. You can often find the global installation path with `npm root -g`.","message":"After global installation with `npm install -g contentful-cli` or `yarn global add contentful-cli`, the `contentful` command might not be immediately available in your shell's PATH, especially on some operating systems or if your shell's cache is not updated.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-23T00:00:00.000Z","next_check":"2026-07-22T00:00:00.000Z","problems":[{"fix":"Upgrade your Node.js installation to version 22 or newer. Use a tool like `nvm` (Node Version Manager) for easy switching: `nvm install 22 && nvm use 22`.","cause":"Attempting to run `contentful-cli` v4.0.0 or higher with an unsupported Node.js version.","error":"Error: Node.js version 18.x.x is not supported. Please upgrade to Node.js 22 or higher."},{"fix":"Ensure you have installed the CLI globally (`npm install -g contentful-cli` or `yarn global add contentful-cli`). Restart your terminal or shell. Check if your global npm packages directory is in your system's PATH.","cause":"The Contentful CLI executable is not in your system's PATH, or the global installation failed/is not recognized.","error":"command not found: contentful"},{"fix":"Try setting `rawProxy: true` in your `.contentfulrc.json` file via the command: `contentful config add --raw-proxy`. This might help with certain proxy configurations.","cause":"Connectivity issues when using a corporate or custom proxy server, potentially due to TLS inspection or incorrect proxy handling.","error":"Unable to connect to Contentful through your Proxy?"},{"fix":"Verify the provided Space ID is correct. Re-authenticate using `contentful login`. If using a management token, ensure it is still valid and has the necessary CMA permissions (e.g., `space.manage`). If it's an API key, ensure it's a Management API key, not a Delivery API key.","cause":"The authenticated user either does not have sufficient permissions for the specified Contentful space, or the space ID is incorrect, or the authentication token is invalid/expired.","error":"Error: Access to space '<SPACE_ID>' failed. Check if you have access to it and if your token has the right permissions."}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}