cli-bulk-operations

> Contentstack CLI plugin for performing bulk operations on your content.

Features

- Perform bulk operations on Contentstack content
- Built with TypeScript for type safety
- Comprehensive test coverage
- Code quality enforced with ESLint and Prettier
- Automated CI/CD workflows

Usage

``sh-session
$ npm install -g @contentstack/cli-bulk-operations
$ csdx COMMAND
running command...
$ csdx (--version|-v)
@contentstack/cli-bulk-operations/1.0.0-beta darwin-arm64 node-v22.14.0
$ csdx --help [COMMAND]
USAGE
$ csdx COMMAND
...
`


Commands


* csdx cm:stacks:bulk-assets
* csdx cm:stacks:bulk-entries

csdx cm:stacks:bulk-assets

Bulk operations for assets (publish/unpublish/cross-publish)

`
USAGE
$ csdx cm:stacks:bulk-assets [-a ] [-k ] [--operation publish|unpublish] [--environments ...]
[--locales ...] [--source-env ] [--source-alias ] [--publish-mode bulk|single] [--branch
] [-c ] [-y] [--retry-failed ] [--revert ] [--bulk-operation-file ] [--folder-uid
]

FLAGS
-a, --alias= Alias (name) of the management token. You must use either the --alias flag or the
--stack-api-key flag.
-c, --config= (optional) The path of the optional configuration JSON file containing all the
options for a single run. Refer to the configure command to create a configuration
file.
-k, --stack-api-key= API key of the source stack. You must use either the --stack-api-key flag or the
--alias flag.
-y, --yes Set it to true to process the command with the current configuration.
--branch= [default: main] The name of the branch where you want to perform the bulk publish
operation. If you don't mention the branch name, then by default the content from
main branch will be published.
--bulk-operation-file= [default: bulk-operation] (optional) Folder path to store operation logs. Creates
separate files for success and failed operations. Default: bulk-operation
--environments=... The name of the environment(s) on which entries/assets will be published. In case
of multiple environments, specify their names separated by spaces.
--folder-uid= (optional) The UID of the Assets' folder from which the assets need to be
published. The default value is cs_root.
--locales=... Locales in which entries/assets will be published, e.g., en-us. In the case of
multiple locales, specify the codes separated by spaces.
--operation= Operation to perform (publish/unpublish)

--publish-mode= [default: bulk] Publish mode: bulk (uses Bulk Publish API) or single (individual
API calls)

--retry-failed= (optional) Use this option to retry publishing the failed entries/assets from the
logfile. Specify the name of the logfile that lists failed publish calls. If this
option is used, it will override all other flags.
--revert= (optional) Revert publish operations from a log folder. Specify the folder path
containing success logs. Works similar to retry-failed.
--source-alias= Alias name for source environment delivery token (required for cross-publish). Add
delivery token using: csdx auth:tokens:add
--source-env= Source environment for cross-publish

DESCRIPTION
Bulk operations for assets (publish/unpublish/cross-publish)

EXAMPLES
$ csdx cm:stacks:bulk-assets --operation publish --environments dev,staging --locales en-us -k blt123

$ csdx cm:stacks:bulk-assets --operation unpublish --environments prod --locales en-us -a myAlias

$ csdx cm:stacks:bulk-assets --operation publish --folder-uid cs_root --environments prod --locales en-us -k blt123

$ csdx cm:stacks:bulk-assets --operation publish --environments prod --locales en-us --publish-mode bulk -k blt123

$ csdx cm:stacks:bulk-assets --operation publish --source-env production --source-alias prod-delivery --environments staging,dev --locales en-us -a myAlias

$ csdx cm:stacks:bulk-assets --retry-failed ./bulk-operation -a myAlias

$ csdx cm:stacks:bulk-assets --revert ./bulk-operation -a myAlias
`

_See code: src/commands/cm/stacks/bulk-assets.ts_

csdx cm:stacks:bulk-entries

Bulk operations for entries (publish/unpublish/cross-publish)

`
USAGE
$ csdx cm:stacks:bulk-entries [-a ] [-k ] [--operation publish|unpublish] [--environments ...]
[--locales ...] [--source-env ] [--source-alias ] [--publish-mode bulk|single] [--branch
] [-c ] [-y] [--retry-failed ] [--revert ] [--bulk-operation-file ]
[--content-types ...] [--filter draft|modified|non-localized|unpublished] [--include-variants] [--api-version
]

FLAGS
-a, --alias= Alias (name) of the management token. You must use either the --alias flag or the
--stack-api-key flag.
-c, --config= (optional) The path of the optional configuration JSON file containing all the
options for a single run. Refer to the configure command to create a configuration
file.
-k, --stack-api-key= API key of the source stack. You must use either the --stack-api-key flag or the
--alias flag.
-y, --yes Set it to true to process the command with the current configuration.
--api-version= [default: 3.2] API version to be used. Values [Default: 3, Nested Reference
Publishing: 3.2].
--branch= [default: main] The name of the branch where you want to perform the bulk publish
operation. If you don't mention the branch name, then by default the content from
main branch will be published.
--bulk-operation-file= [default: bulk-operation] (optional) Folder path to store operation logs. Creates
separate files for success and failed operations. Default: bulk-operation
--content-types=... Content type UIDs to perform operation on. If not provided, operates on all content
types.
--environments=... The name of the environment(s) on which entries/assets will be published. In case
of multiple environments, specify their names separated by spaces.
--filter= Filter entries by status

--include-variants Include variant entries in operation
--locales=... Locales in which entries/assets will be published, e.g., en-us. In the case of
multiple locales, specify the codes separated by spaces.
--operation= Operation to perform (publish/unpublish)

--publish-mode= [default: bulk] Publish mode: bulk (uses Bulk Publish API) or single (individual
API calls)

--retry-failed= (optional) Use this option to retry publishing the failed entries/assets from the
logfile. Specify the name of the logfile that lists failed publish calls. If this
option is used, it will override all other flags.
--revert= (optional) Revert publish operations from a log folder. Specify the folder path
containing success logs. Works similar to retry-failed.
--source-alias= Alias name for source environment delivery token (required for cross-publish). Add
delivery token using: csdx auth:tokens:add
--source-env= Source environment for cross-publish

DESCRIPTION
Bulk operations for entries (publish/unpublish/cross-publish)

EXAMPLES
$ csdx cm:stacks:bulk-entries --operation publish --environments dev --locales en-us -k blt123

$ csdx cm:stacks:bulk-entries --operation publish --content-types blog,article --environments dev --locales en-us -k blt123

$ csdx cm:stacks:bulk-entries --operation unpublish --content-types blog --environments prod --locales en-us -a myAlias

$ csdx cm:stacks:bulk-entries --operation publish --content-types blog --source-env production --source-alias prod-delivery --environments staging --locales en-us -a myAlias

$ csdx cm:stacks:bulk-entries --operation publish --content-types blog --environments prod --locales en-us --publish-mode bulk -k blt123

$ csdx cm:stacks:bulk-entries --operation publish --content-types blog --environments prod --locales en-us --filter modified -k blt123

$ csdx cm:stacks:bulk-entries --operation publish --content-types blog --environments prod --locales en-us --include-variants -k blt123

$ csdx cm:stacks:bulk-entries --retry-failed ./bulk-operation

$ csdx cm:stacks:bulk-entries --revert ./bulk-operation
`

_See code: src/commands/cm/stacks/bulk-entries.ts_


Requirements

- Node.js >= 22
- Contentstack account with API credentials

Development

$3

`bash


Clone the repository

git clone https://github.com/contentstack/cli-bulk-operations.git
cd cli-bulk-operations

Install dependencies

npm install

Build the project

npm run build
`

$3

- npm run build - Build the TypeScript project
- npm run lint - Run ESLint checks
- npm run lint:fix - Fix ESLint issues automatically
- npm run format - Format code with Prettier
- npm run format:check - Check code formatting
- npm test - Run tests
- npm run test:coverage - Run tests with coverage
- npm run clean - Clean build artifacts




Testing

This project uses Mocha for testing with comprehensive coverage reporting.

`bash


Run all tests

npm test

Run tests with coverage

npm run test:coverage

Run tests with detailed coverage report

npm run test:coverage:report
`

Code Quality

$3

The project uses ESLint with TypeScript-specific rules:

`bash
npm run lint
`

$3

Code formatting is handled by Prettier:

`bash
npm run format
`

$3

Husky is configured to run checks before commits and pushes:

- Pre-commit: Runs lint-staged to check and format staged files
- Pre-push: Runs linting and tests to ensure code quality

CI/CD

$3

1. PR Checks (pr-checks.yml): Runs on pull requests
- Lint checks
- Test execution with coverage
- Build verification

2. Test (test.yml): Runs on pushes and PRs
- Tests across multiple Node.js versions (18, 20, 22)
- Coverage reporting to Codecov

3. Release (release.yml`): Runs on main branch
- Automated npm publishing
- GitHub release creation
- Semantic versioning

Changelog

See CHANGELOG.md for release history.