Skip to main content
Contentstack MCP profile hub is in general availability!

Every csdx command is a plugin

•
7 min read

The Contentstack CLI does almost nothing on its own. csdx is a small core built on oclif, and every command you run, from auth:login to cm:stacks:export, comes from a plugin. Some plugins ship inside the CLI, some you install when you need them, and some you write yourself.

I like this setup a lot. Each plugin ships on its own schedule, and the official commands are built the same way you would build your own, so nothing stops you from adding the command your team is missing. In this post I walk through how plugins load in CLI 2.x, which ones are bundled, what changed from 1.x, and five recipes I use.

The short version

  • csdx plugins lists the plugins you installed or linked. csdx plugins --core adds the bundled ones.

  • csdx plugins:install <npm-package> adds a plugin, csdx plugins:uninstall <name> removes it.

  • csdx plugins:link <path> wires a local folder into the CLI while you develop a plugin.

  • The CLI's own package.json decides what is bundled. Everything else is one install away.

How csdx finds its commands

oclif plugins are npm packages with an oclif section in their package.json that points at a folder of compiled commands. The @contentstack/cli package lists the plugins it bundles in its own oclif.plugins array. When you run a command, oclif loads that list, then the plugins you installed, then the plugins you linked, and resolves the command ID against all of them.

DiagramMermaid

Linked plugins win. If you link a local plugin that defines a command the CLI already has, your version runs instead. That is great for testing a fix to an official plugin, and it is also the first thing to check when a command suddenly behaves differently on one machine.

The plugin management commands come from @oclif/plugin-plugins, which is itself bundled:

csdx plugins                      # user-installed and linked plugins
csdx plugins --core               # include the bundled plugins
csdx plugins:install contentstack-cli-tsgen
csdx plugins:inspect contentstack-cli-tsgen
csdx plugins:update
csdx plugins:uninstall contentstack-cli-tsgen
csdx plugins:link ./my-plugin
csdx plugins:reset                # remove every user-installed and linked plugin

What ships bundled in 2.x

This is the bundled set in @contentstack/cli 2.0.2, next to what each plugin is for:

Plugin package

Main commands

What it is for

@contentstack/cli-auth

auth:login, auth:logout, auth:tokens:add

Session login and saved token aliases

@contentstack/cli-config

config:set:region, config:set:base-branch

Region, proxy, rate limit and branch defaults

@contentstack/cli-cm-export

cm:stacks:export

Export a stack to disk

@contentstack/cli-cm-import

cm:stacks:import

Import an export into a stack

@contentstack/cli-cm-import-setup

cm:stacks:import-setup

Prepare UID mappings before an import

@contentstack/cli-cm-clone

cm:stacks:clone

Export and import in one step

@contentstack/cli-cm-seed

cm:stacks:seed

Seed a stack from a GitHub repo

@contentstack/cli-cm-bootstrap

cm:bootstrap

Start a starter app with a seeded stack

@contentstack/cli-cm-export-to-csv

cm:export-to-csv

Export entries or users to CSV

@contentstack/cli-migration

cm:stacks:migration

Run content model migration scripts

@contentstack/cli-cm-branches

cm:branches:diff, cm:branches:merge

Create, compare and merge branches

@contentstack/cli-audit

cm:stacks:audit, cm:stacks:audit:fix

Find and fix broken references in an export

@contentstack/cli-bulk-operations

cm:stacks:bulk-entries, cm:stacks:bulk-assets, cm:stacks:bulk-taxonomies

Bulk publish and unpublish

What you install yourself

These official plugins are opt-in. Install them with csdx plugins:install <package>:

Plugin package

Commands

What it is for

@contentstack/cli-launch

launch, launch:deployments, launch:logs and more

Deploy and manage Launch projects

@contentstack/apps-cli

app:create, app:deploy, app:install

Developer Hub apps

contentstack-cli-tsgen

tsgen

TypeScript types from your content types

contentstack-cli-content-type

content-type:list, content-type:compare, content-type:diagram

Inspect, compare and draw content types

@contentstack/cli-cm-migrate-rte

cm:entries:migrate-html-rte

Move HTML RTE content to JSON RTE

@contentstack/cli-cm-export-query

cm:stacks:export-query

Export only what a query matches

@contentstack/cli-cm-regex-validate

cm:stacks:validate-regex

Check regex validations in your content types

@contentstack/cli-external-migrate

migrate:create, migrate:export, migrate:import

Migrate from another CMS, starting with Contentful

What changed from 1.x

If you are coming from CLI 1.x, these are the changes that show up in daily use:

  • Bulk publish became bulk operations. The old cm:bulk-publish commands are gone. The bundled bulk-operations plugin replaces them with cm:stacks:bulk-entries, cm:stacks:bulk-assets and cm:stacks:bulk-taxonomies, each driven by an --operation flag. Taxonomies are new territory for bulk publishing, and the commands support --dry-run, --retry-failed and --revert from a log folder.

  • Launch and migrate-rte are opt-in. Both used to ship with the CLI. If you run csdx launch without the plugin, the CLI tells you it is now opt-in and prints the install command instead of a "command not found" error.

  • tsgen moved in with the other official plugins. contentstack-cli-tsgen 5.x is developed alongside the rest and requires CLI 2.x. If you still have tsgen 4 installed, run csdx plugins:update or reinstall it.

  • Launch has its own version line. The CLI and most plugins are on 2.x, while @contentstack/cli-launch continues on 1.x. That is fine: the version numbers of plugins are independent of the core.

  • Node.js 22 is the minimum. @contentstack/cli 2.x declares node >= 22.

Five recipes

All recipes assume you ran csdx config:set:region and csdx auth:login. Where a command takes -a, that is a management token alias you saved with csdx auth:tokens:add.

Typed models with tsgen

Generate TypeScript interfaces from your content types so your front end breaks at compile time instead of in production:

csdx plugins:install contentstack-cli-tsgen
csdx auth:tokens:add --delivery -a my-delivery-token
csdx tsgen -a my-delivery-token --output ./types/contentstack.d.ts --include-system-fields

tsgen reads the schema with a delivery token alias, not a management token. Add --api-type graphql if your app queries GraphQL. This site does exactly this and keeps the generated file in the repo.

Compare and merge branches

Before you merge a branch, look at what changed in the content model:

csdx cm:branches:diff -k <stack-api-key> --base-branch main --compare-branch feature-nav --module content-types --format detailed-text
csdx cm:branches:merge -k <stack-api-key> --base-branch main --compare-branch feature-nav --comment "New navigation model"

The merge creates a revert branch by default, so you have a way back. For the full workflow with aliases, read Safe content model changes with branches and aliases.

Migration scripts

Content model changes belong in code. A migration script is a JavaScript module that receives a migration object:

// migrations/01-add-summary.js
module.exports = ({ migration }) => {
  const article = migration.editContentType('article');
  article.createField('summary').display_name('Summary').data_type('text').mandatory(false);
};
csdx cm:stacks:migration -a my-management-token --branch feature-nav --file-path ./migrations/01-add-summary.js

Point --file-path at a folder and add --multiple to run every script in it. Run migrations against a branch first, then merge.

Audit an export before you import it

cm:stacks:import already runs an audit fix unless you pass --skip-audit. I still run the audit on its own first, because it gives me a report to read before anything touches the target stack:

csdx cm:stacks:export -a source-token -d ./export
csdx cm:stacks:audit -d ./export --report-path ./audit --modules content-types entries
csdx cm:stacks:audit:fix -d ./export --report-path ./audit --copy-dir

--copy-dir writes the fixes to a copy, so your original export stays untouched. Then import the fixed copy.

Draw and compare content types

The content-type plugin answers "what does this stack look like" faster than clicking through the UI:

csdx plugins:install contentstack-cli-content-type
csdx content-type:list -a my-management-token --order modified
csdx content-type:diagram -a my-management-token --output content-model.svg --direction landscape
csdx content-type:compare-remote --origin-stack <api-key-a> --remote-stack <api-key-b> --content-type page

The diagram is an SVG of every content type and its references. compare-remote is the quickest way I know to see why the same content type behaves differently in two stacks. --type dot gives you a Graphviz file instead, if you want to style it yourself.

Write your own

The official plugins have no special access. They extend the same Command class from @contentstack/cli-command, get the region and session from the CLI, and call the Management API through the same client wrapper in @contentstack/cli-utilities. Anything you can script against Contentstack, you can turn into a csdx command your team installs with one line.

That is why I like this architecture so much. If a task comes up twice, make it a command. Start with Write your own csdx plugin, which builds a read-only csdx stack:health command from scaffold to npm publish.

Frequently asked questions

  • How do I see which csdx plugins are installed?

    Run csdx plugins to list the plugins you installed or linked yourself, and csdx plugins --core to include the ones bundled with the CLI.

  • Why does csdx launch say it is an opt-in plugin?

    In CLI 2.x the Launch plugin no longer ships with the CLI. Install it with csdx plugins:install @contentstack/cli-launch and the launch commands come back.

  • What replaced cm:bulk-publish in CLI 2.x?

    The bulk-operations plugin, which ships bundled. It adds cm:stacks:bulk-entries, cm:stacks:bulk-assets and cm:stacks:bulk-taxonomies, each taking an --operation flag such as publish or unpublish.

  • Can a linked plugin override a built-in command?

    Yes. A plugin linked with csdx plugins:link takes priority over a user-installed or core plugin with the same command, which is handy for local development.