Contentful CLI for coding agents

When a coding agent needs to inspect content in Contentful, it can use the official Contentful CLI to export a space environment to a local JSON file. A space is where Contentful keeps a project's content, and an environment inside it holds the content model and content. The agent can inspect the file without changing the Contentful environment.

The CLI also supports imports and migrations, which can change remote content or its structure. When you only need to analyze the content, export it and keep the file on your machine. The CLI repository documents its commands, and Contentful’s import and export guide covers the JSON transfer format.

Install and authenticate

Contentful’s installation page lists Homebrew and npm among other options. The npm package needs a Node.js LTS release. Install it globally with npm:

npm install -g contentful-cli

Then start the CLI’s documented login flow:

contentful login

contentful login opens a browser, where you sign in and authorize the CLI. The CLI then stores a Content Management API token in ~/.contentfulrc.json. On a machine without a browser, you can create a personal management token in the Contentful web app and pass it with contentful login --management-token. Keep credentials out of the agent prompt. An agent with shell access may be able to read that file, so treat ~/.contentfulrc.json as a secret too. contentful logout removes the stored token.

Export an environment

For read-only inspection, export an environment so an agent can examine its content types and entries. A content type defines the fields used by a kind of content, such as an article or product.

Replace the two placeholder values with the Contentful space ID and environment ID you want to inspect:

contentful space export \
  --space-id "YOUR_SPACE_ID" \
  --environment-id "YOUR_ENVIRONMENT_ID" \
  --content-file "./contentful-export.json"

The command contacts Contentful to read the selected environment, then writes the export to contentful-export.json on the machine running the CLI. The --content-file option sets the name of the local output file. Without --environment-id, the export uses the master environment. The export is JSON, which lets an agent inspect the records without making another Contentful request.

By default, the export leaves out draft and archived entries. Add --include-drafts or --include-archived when the agent should see them. Asset files are not downloaded unless you pass --download-assets.

The command does not edit the remote environment. However, the export can contain real content, so treat the file as sensitive and avoid committing it to a repository unless its contents are safe to share. The file holds more than entries. The export format in Contentful's guide also has sections for webhooks and roles, among others.

Give the agent a bounded task

After the export finishes, ask the agent to work only with the local file. For example:

Inspect contentful-export.json. Summarize the content types and count the entries for each type. Flag entries whose required fields appear empty. Do not run Contentful commands or modify any files.

The export only reads data from Contentful over the network, and the agent analyzes the resulting local file. The prompt does not need a token or other credential.

The CLI also includes import and migration commands. Those commands can write to Contentful, so keep them separate from an inspection task and confirm their documented arguments before using them. The CLI repository lists the available command groups and options.