Content Type Plugin

The content type plugin includes commands to inspect, compare, and visualize content types in a Contentstack stack directly from the CLI. Use it to:

• Audit schema changes before deploying to production.
• Compare content models across versions or stacks.
• Generate visual documentation of your content architecture.

If you are upgrading from v1, see Upgrading from v1 for the flags that changed.

These commands only read your stack's content types. They don't write, update, or delete any content in your stack.

Find your starting point based on what you are doing.

• Contentstack CLI v2 installed: See Install the Contentstack CLI. This provides the csdx command used throughout this doc.
• Plugin installed: See Installation. This adds the content-type:* commands to your CLI.
• Authentication: A saved management token alias or a stack API key. See Authentication. If using a management token, its role must grant Content Type: Read permission.
• Region configured, if your stack is not in North America: Set your region before running any stack commands.
  1

  csdx config:set:region

  This routes requests to the correct data center for your stack.

1. Install the plugin:
   1

   csdx plugins:install contentstack-cli-content-type

2. Verify:
   1

   csdx plugins

List all content types in a stack.

Syntax

csdx content-type:list [FLAGS]

Flags

Note: Pass either --stack-api-key or --alias, not both. See Authentication for the full enforcement table.

Output

Displays a table of all content types with their title, UID, and last modified date.

Examples

List all content types, sorted by title:

csdx content-type:list -a my-token-alias

List sorted by last modified:

csdx content-type:list -a my-token-alias --order modified

Using stack API key directly:

csdx content-type:list -k <stack-api-key>

Display the full schema details of a specific content type.

Syntax

csdx content-type:details --content-type <uid> [FLAGS]

Flags

Output

A structured table of the content type schema with columns for field title, UID, data type, and path (dot-notation path through nested structures). Use --no-path to hide the path column for a more compact view.

Examples

View full details for a content type:

csdx content-type:details -a my-token-alias --content-type home_page

Hide the path column:

csdx content-type:details -a my-token-alias --content-type home_page --no-path

Using stack API key:

csdx content-type:details -k <stack-api-key> --content-type blog_post

Display recent audit log changes to a specific content type.

Syntax

csdx content-type:audit --content-type <uid> [FLAGS]

Flags

Output

A table of audit log entries showing the action, the user who made the change, and the timestamp.

Examples

View audit log for a content type:

csdx content-type:audit -a my-token-alias --content-type home_page

Using stack API key:

csdx content-type:audit -k <stack-api-key> --content-type blog_post

Compare two versions of the same content type within a stack.

Syntax

csdx content-type:compare --content-type <uid> [FLAGS]

Flags

Note: Provide --left and --right together. If omitted, the latest two versions are compared automatically.

Output

A diff table showing fields that were added, removed, or changed between the two versions.

Examples

Auto-compare latest two versions:

csdx content-type:compare -a my-token-alias --content-type home_page

Compare specific versions:

csdx content-type:compare -a my-token-alias --content-type home_page --left 5 --right 4

Compare the same content type across two different stacks.

Syntax

csdx content-type:compare-remote --origin-stack <key> --remote-stack <key> --content-type <uid>

Flags

Note: See the Authentication Exception for how this command authenticates.

Output

A diff table showing field-level differences between the same content type on two stacks.

Examples

csdx content-type:compare-remote \
  --origin-stack <origin-stack-api-key> \
  --remote-stack <remote-stack-api-key> \
  --content-type home_page

Generate a visual diagram of all content types in a stack.

Syntax

csdx content-type:diagram --output <path> [FLAGS]

Flags

Output

Creates a file at the specified --output path. The file is either:

• SVG (default): a rendered visual graph, viewable in any browser or SVG viewer.
• DOT: a file in the DOT language, read by Graphviz, an open-source graph-visualization tool. Render it manually with dot -Tpng content-model.dot -o content-model.png.

The CLI always prints an absolute path here, regardless of whether you pass --output a relative or absolute path. On success, it prints something like:

Created Graph: /Users/you/project/content-model.svg

Examples

Generate SVG diagram:

csdx content-type:diagram -a my-token-alias --output ./content-model.svg

Landscape orientation:

csdx content-type:diagram -a my-token-alias --output ./content-model.svg --direction landscape

DOT file for further processing:

csdx content-type:diagram -a my-token-alias --output ./content-model.dot --type dot

Most commands support a management token alias or a stack API key. Whether --stack-api-key and --alias are mutually exclusive depends on the command. Pass only one flag regardless.

Option 1: Management Token Alias (Recommended)

csdx auth:tokens:add -a my-token-alias -k <stack-api-key> --management --token <management-token>

Then use -a my-token-alias in any command that accepts --alias.

Option 2: Stack API Key

csdx content-type:list -k <stack-api-key>

content-type:compare-remote does not accept --alias or --stack-api-key. It authenticates by taking both stack API keys directly, via --origin-stack (the origin/authenticating stack) and --remote-stack (the stack to compare against). Every other command in this doc that mentions this exception links back to this section rather than restating it.

Who changed blog_post and when:

csdx content-type:audit -a my-token-alias --content-type blog_post

What exactly changed in the last update:

csdx content-type:compare -a my-token-alias --content-type blog_post

csdx content-type:compare-remote \
  --origin-stack <staging-key> \
  --remote-stack <production-key> \
  --content-type home_page

#!/bin/bash
set -euo pipefail

# Generate a landscape diagram and open it
csdx content-type:diagram \
  -a production-token \
  --output ./docs/content-model.svg \
  --direction landscape

open ./docs/content-model.svg

set -euo pipefail stops the script if content-type:diagram fails, so open never runs against a diagram that was not created.

v2 removes the deprecated flags and all command-specific short flags from v1. Only -k (--stack-api-key) and -a (--alias) remain as short flags. Replace each removed flag with its long form.

Note: content-type:compare-remote is the one exception to the retained short flags above. See Authentication Exception.

Root Cause: You have no active CLI login session. Every command authenticates using the auth token that auth:login creates. This applies even when you pass --stack-api-key (-k). The stack API key sets the target stack. It does not replace the auth token.

Resolution:

1. Log in: csdx auth:login
2. Re-run your command.

For more detail, see CLI Authentication.

Root Cause: The alias you passed with -a points to a delivery token, a token scoped for reading published content only. These commands require a management token, which grants access to manage stack schema and data.

Resolution:

1. List your saved tokens and their type: csdx auth:tokens
2. If you do not have a management token, add one as shown in Authentication.
3. Pass the management token alias with -a.

See Add a Management Token.

Root Cause: You ran a command without --alias (-a) and without --stack-api-key (-k). Every command except content-type:compare-remote needs one of them.

Resolution: Add either -a <alias> or -k <stack-api-key>. For content-type:compare-remote, pass --origin-stack and --remote-stack instead. See Authentication.

This covers messages that start with Error: and name an authentication or permission problem. An error occurred. with no further text is the fallback the CLI shows when it cannot read a message off the failure, and the same root causes apply.

Root Causes:

• The stack API key or the management token behind the alias is wrong.
• The token lacks Content Type: Read permission.
• Your configured region does not match the stack's region, so the key is valid but the request reaches the wrong data center.

Resolution:

1. Verify the alias is saved and points to the right stack: csdx auth:tokens
2. Confirm the token has Content Type: Read permission in the Contentstack UI.
3. Check your region: csdx config:get:region. If it does not match the stack, reset it with csdx config:set:region.

See Configure Regions in the CLI.

Applies to content-type:details, content-type:audit, content-type:compare, and content-type:compare-remote.

Root Causes:

• The --content-type UID is misspelled or does not exist in the target stack.
• (content-type:compare) The version you passed to --left or --right does not exist for that content type.

Resolution:

1. List the valid UIDs in the stack: csdx content-type:list -a my-token-alias
2. Check the available versions of a content type: csdx content-type:audit -a my-token-alias --content-type <uid>
3. Re-run with a valid UID and, for compare, valid version numbers.

See content-type:list and content-type:audit for the commands used above.

Root Cause: --origin-stack and --remote-stack hold the same API key.

Resolution: Provide two different stack API keys. This message is a warning, so the command still runs and produces an empty diff. See content-type:compare-remote.

Root Causes:

• --left and --right are set to the same version number.
• You omitted both flags and the content type has only one version. The command defaults to comparing version 1 against itself and prints this warning.

Resolution:

• If two or more versions exist, pass different --left and --right values. Check the version history first with csdx content-type:audit -a my-token-alias --content-type <uid>.
• If only one version exists, there is nothing to compare yet. Save a change to the content type to create a second version first.

See content-type:compare and content-type:audit.

Root Causes:

• You lack write permission on the target directory.
• --output points at an existing directory instead of a file.
• A parent path segment is a file, not a folder.
• The disk is full.
• --output is blank or only whitespace. The command reports Please provide an output path.
• --output contains characters your filesystem does not allow.

Resolution:

1. Use an absolute path to a writable directory.
2. Name a file, not a directory, in --output.
3. Confirm the target has free disk space.
4. Remove any characters your operating system does not allow in file paths.

The CLI creates missing parent directories automatically. The --type value and the file extension are independent: --type dot with --output content-model.svg writes DOT content into a file named .svg. Match the extension to the type yourself. See content-type:diagram for the full flag reference.

Root Cause: v2 removed a v1 short flag (for example -s, -c, -l, -r, -o, -d, -t, or -p) or a deprecated flag (--stack, --token-alias) that a script still passes.

Resolution: Replace the flag with its v2 long form. See Upgrading from v1 for the full mapping.

• These commands compare and diagram schema only. They do not diff entry-level content or data records.
• content-type:diagram writes a local SVG or DOT file. It is never uploaded or synced back to the stack.
• content-type:compare needs at least two saved versions of a content type. With only one version, it compares the version against itself and returns an empty diff. See content-type:compare for the single-version case.

• Content Type Plugin (v1): the v1 command reference, useful if you still run v1 or need the old flag names while upgrading.
• Regex Validate Plugin (v2): scan your content types and global fields for regex patterns vulnerable to catastrophic backtracking.
• Audit Plugin: a related Contentstack plugin for reviewing audit log activity across your stack.
• CLI Authentication: Add Management Token: create and save the management token alias these commands use.
• Configure Regions in the CLI: set your region if your stack is not in North America.
• About Content Types: conceptual background on how content types and their fields are structured.