Do this with AI
Install the dx-cli skill from Contentstack agent skills. Then ask your agent:
List the csdx plugins installed on my machine, mark which ones ship with CLI 2.x and which I added, and show the command to export only my content types.
New to this? Set up your AI workbench first.
Every csdx command is a plugin
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.
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 pluginWhat 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-fieldstsgen 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.jsPoint --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 pageThe 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.