Contentful CLI

4.0.0 verified Thu Apr 23 auth: no javascript

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.

Common errors

error Error: Node.js version 18.x.x is not supported. Please upgrade to Node.js 22 or higher. ↓

cause Attempting to run `contentful-cli` v4.0.0 or higher with an unsupported Node.js version.

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.

error command not found: contentful ↓

cause The Contentful CLI executable is not in your system's PATH, or the global installation failed/is not recognized.

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.

error Unable to connect to Contentful through your Proxy? ↓

cause Connectivity issues when using a corporate or custom proxy server, potentially due to TLS inspection or incorrect proxy handling.

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.

error Error: Access to space '<SPACE_ID>' failed. Check if you have access to it and if your token has the right permissions. ↓

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.

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.

Warnings

breaking 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. ↓

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.

gotcha 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. ↓

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`.

gotcha 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. ↓

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.

gotcha 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. ↓

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`.

Install

npm install contentful-cli

yarn add contentful-cli

pnpm add contentful-cli

Imports

contentful
wrong
```
import { contentful } from 'contentful-cli'
```
correct
```
npm install -g contentful-cli
```
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.
Login/Auth
wrong
```
contentful auth --token <YOUR_TOKEN>
```
correct
```
contentful login
```
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>`.
Configuration
wrong
```
contentful config set host=api.eu.contentful.com
```
correct
```
contentful config add --host api.eu.contentful.com
```
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.

Quickstart

Demonstrates global installation, logging into Contentful via OAuth, listing spaces, exporting a space, and accessing command-specific help.

# Install the Contentful CLI globally
npm install -g contentful-cli

# Log in to your Contentful account (this will open a browser for OAuth)
contentful login

# List all available spaces for your account
contentful space list

# Export a space to a JSON file
# Replace <SPACE_ID> with your actual Space ID and <FILE_NAME> with your desired output file name
# You can find your Space ID in the Contentful web app URL or via 'contentful space list'
# Example: contentful space export --space-id 'your_space_id' --output 'exported-space.json'
contentful space export --space-id <YOUR_SPACE_ID> --output exported-space.json

# Get help for a specific command
contentful migration --help