Creating Custom CLI Plugins for Contentstack

npm install -g @contentstack/cli

my-plugin/
├── src/
│   └── commands/
│       └── mycommand.ts
├── test/
│   └── commands/
│       └── mycommand.test.ts
├── .eslintrc.js
├── package.json
├── tsconfig.json
├── README.md
└── oclif.manifest.json

npx oclif generate myplugin
cd myplugin

{
  "name": "myplugin",
  "version": "1.0.0",
  "oclif": {
    "commands": "./lib/commands",
    "bin": "csdx"
  },
  "dependencies": {
    "@contentstack/cli-command": "~2.0.0",
    "@contentstack/cli-utilities": "~2.0.0",
    "@oclif/core": "^4.11.14"
  }
}

cd

npx oclif generate command myplugin:do

npm run build

npx oclif manifest

cd

csdx myplugin:do --help

# Production mode (compiled JS from lib/)
node bin/run.js myplugin:do

# Development mode (TypeScript via ts-node, no build step needed)
node bin/dev.js myplugin:do

import { Command } from '@contentstack/cli-command'
import { Args, flags } from '@contentstack/cli-utilities'

export default class MyCommand extends Command {
  static description = 'Does something cool with Contentstack'

  // Positional arguments — import Args from @contentstack/cli-utilities
  static args = {
    environment: Args.string({
      description: 'Environment name',
      required: true,
    }),
  }

  static flags = {
    'stack-api-key': flags.string({
      char: 's',
      description: 'Stack API key',
      required: true,
    }),
  }

  async run() {
    const { args: cmdArgs, flags: cmdFlags } = await this.parse(MyCommand)
    // All base Command class properties are available automatically:
    this.log(`Stack: ${cmdFlags['stack-api-key']}, Env: ${cmdArgs.environment}`)
    this.log(`CMA: ${this.cmaAPIUrl}, Region: ${this.region.name}`)
  }
}

import { expect } from 'chai'
import { describe, it, afterEach } from 'mocha'
import { stub, restore } from 'sinon'
import MyCommand from '../../../src/commands/myplugin/do'

describe('myplugin:do', () => {
  afterEach(() => restore())

  it('runs with required flag', async () => {
    const runStub = stub(MyCommand.prototype, 'run').resolves()
    await MyCommand.run(['--stack-api-key', 'dummy_key'])
    expect(runStub.calledOnce).to.be.true
  })
})

npm test

csdx plugins:update

csdx plugins:reset

cd

this.log('Message')               // Print a message
this.error('Error message')       // Print an error and exit
this.warn('Warning message')      // Print a warning
this.exit(0)                      // Exit with code
this.config.bin                   // CLI binary name ('csdx')
this.config.version               // CLI version

npm install @contentstack/cli-utilities

import { cliux } from '@contentstack/cli-utilities'

// Print messages
cliux.print('Message')
cliux.print('Info', { color: 'cyan' })           // cyan = info style
cliux.print('Warning', { color: 'yellow' })      // yellow = warning style
cliux.print('Bold text', { bold: true })
cliux.success('Done!')                           // green
cliux.error('Something failed')                  // red

// Note: cliux.info() and cliux.warning() do NOT exist — use cliux.print() with color

// Spinner — cliux.loader() is a TOGGLE: first call starts, second call stops
cliux.loader('Processing...')   // start
// ... do work ...
cliux.loader()                  // stop — never forget this or the spinner hangs

// loaderV2 — returns an Ora instance for more control
const spinner = cliux.loaderV2('Fetching...')  // start, returns Ora
// ... do work ...
cliux.loaderV2('Done', spinner)                // set text and stop

// Table output — value = data key, alias = display header
cliux.table(
  [
    { value: 'title', alias: 'Title' },
    { value: 'uid',   alias: 'UID' },
  ],
  entries.map((e: any) => ({ title: e.title, uid: e.uid })),
)

// Progress bar — returns a cli-progress SingleBar
const bar = cliux.progress({ format: 'Writing |{bar}| {value}/{total}' })
bar.start(total, 0)
bar.increment()
bar.stop()

// Prompts
const answer = await cliux.inquire({ type: 'input', name: 'value', message: 'Enter value:' })
const confirmed = await cliux.confirm('Are you sure?')

import { CLIError } from '@contentstack/cli-utilities'

if (!isAuthenticated()) {
  throw new CLIError('Please login first: csdx auth:login')
}

import { Args, flags } from '@contentstack/cli-utilities'

static args = {
  environment: Args.string({ description: 'Environment name', required: true }),
  uid: Args.string({ description: 'Entry UID' }),
}

async run() {
  const { args: cmdArgs } = await this.parse(MyCommand)
  this.log(cmdArgs.environment)
}

import { configHandler } from '@contentstack/cli-utilities'

const email  = configHandler.get('email')
const region = configHandler.get('region')    // { name, cma, cda, uiHost, ... }
const token  = configHandler.get('authtoken')

configHandler.set('myKey', 'value')

import { isAuthenticated, isManagementTokenValid } from '@contentstack/cli-utilities'

// Check if user is logged in (reads authtoken/oauthAccessToken from config)
if (!isAuthenticated()) {
  throw new CLIError('Please login first: csdx auth:login')
}

// Validate a stored management token before using it in a long operation
const { token } = this.getToken(alias)
const result = await isManagementTokenValid(stackApiKey, token)
if (result.valid !== true) {
  throw new CLIError(`Token invalid: ${result.message}`)
}

import { managementSDKClient } from '@contentstack/cli-utilities'

// Always use this.cmaHost from the base Command class — it's already region-aware
const client = await managementSDKClient({ host: this.cmaHost })
const stack  = client.stack({ api_key: cmdFlags['stack-api-key'] })
const result = await stack.contentType('blog_post').entry().query().find()

import { HttpClient, configHandler } from '@contentstack/cli-utilities'

const httpClient = new HttpClient({
  headers: {
    api_key:   cmdFlags['stack-api-key'],
    authtoken: configHandler.get('authtoken'),
  },
})

const response = await httpClient.get(`${this.cmaAPIUrl}/v3/stacks`)
const stack = response?.data?.stack

import { FsUtility } from '@contentstack/cli-utilities'

const fsUtil = new FsUtility({
  basePath:            './exports/entries',
  moduleName:          'entries',
  fileExt:             'json',
  createDirIfNotExist: true,
})

// Write entries in chunks (auto-creates UUID-named chunk files + index)
for (const entry of entries) {
  fsUtil.writeIntoFile([entry] as any, { keyName: 'uid', mapKeyVal: true })
}

import { CLIProgressManager } from '@contentstack/cli-utilities'

// createSimple(moduleName, total) — auto-starts on construction
const manager = CLIProgressManager.createSimple('entries', entries.length)

for (const entry of entries) {
  try {
    await processEntry(entry)
    manager.tick(true, entry.uid)           // success
  } catch (err: any) {
    manager.tick(false, entry.uid, err.message)  // failure
  }
}

// complete() stops the bar and triggers summary callbacks
manager.complete(manager.getFailureCount() === 0)

import { CLIProgressManager } from '@contentstack/cli-utilities'

// Initialize a global summary before creating any managers
CLIProgressManager.initializeGlobalSummary('export', 'main', 'EXPORT CONTENT')

const entriesManager    = CLIProgressManager.createSimple('entries', entries.length)
const assetsManager     = CLIProgressManager.createSimple('assets', assets.length)

for (const entry of entries) {
  entriesManager.tick(true, entry.uid)
}
entriesManager.complete(true)

for (const asset of assets) {
  assetsManager.tick(true, asset.uid)
}
assetsManager.complete(true)

// Print final success/failure counts for all modules
CLIProgressManager.printGlobalSummary()

const hasFailed = CLIProgressManager.hasFailures()  // true if any module had failures
CLIProgressManager.printGlobalSummary()             // print all module counts
CLIProgressManager.clearGlobalSummary()             // reset for a new run

import { readContentTypeSchemas, readGlobalFieldSchemas } from '@contentstack/cli-utilities'

// Read all CT schema JSON files from a directory
const contentTypes = readContentTypeSchemas('./exports/content_types')

// Read all global field schema files (excludes schema.json, __master.json, etc.)
const globalFields = readGlobalFieldSchemas('./exports/global_fields')

import { loadChalk, getChalk } from '@contentstack/cli-utilities'

// During CLI init / command setup — loads and caches chalk
await loadChalk()

// After loadChalk() has been called — get the cached instance
const chalk = getChalk()
cliux.print(chalk.bold.cyan('Bold cyan text'))

import {
  formatError,
  validatePath,
  sanitizePath,
  pathValidator,
  redactObject,
  generateUid,
  generateShortUid,
  formatDate,
  formatTime,
  isManagementTokenValid,
  getAuthenticationMethod,
  validateUids,
  validateFileName,
  escapeRegExp,
} from '@contentstack/cli-utilities'

// Format Contentstack API errors into a clean message string
try { /* API call */ } catch (error) {
  throw new CLIError(formatError(error))
}

// Path validation — rejects paths with special chars (*,$,%,#,<>,{},!,&,?)
if (!validatePath(cmdFlags.output)) throw new CLIError('Invalid path')

// Path sanitization — strips directory traversal (../) and normalises slashes
const safe = sanitizePath(path.resolve(cmdFlags.output))

// Path normalization — resolves against cwd and strips traversal
const normalized = pathValidator('./relative/path')

// Redact sensitive keys before logging
// Strips: authtoken, token, api_key, management token, delivery token, password, secret, email
const safePayload = redactObject({ apiKey: 'bltXXX', authtoken: 'csXXX', email: '[email protected]', data: 'ok' })
// => { apiKey: '[REDACTED]', authtoken: '[REDACTED]', email: '[REDACTED]', data: 'ok' }

// UUID generation
const uid      = generateUid()       // UUID v4
const shortUid = generateShortUid()  // short UUID

// Date/time formatting (produces YYYYMMDD and HHMMSS strings)
const now  = new Date()
const date = formatDate(now)   // '20260813'
const time = formatTime(now)   // '183916'

// Auth method detection
const method = getAuthenticationMethod()  // 'OAuth' | 'Basic Auth' | ''

// UID and filename validation
validateUids('blt123abc')      // true/false — alphanumeric only
validateFileName('export.json') // true/false — alphanumeric, dash, underscore, dot
escapeRegExp('a.b*c')          // 'a\\.b\\*c'

import { log, handleAndLogError, getLogPath, getSessionLogPath } from '@contentstack/cli-utilities'

const logPath     = getLogPath()        // base log path for the current run
const sessionPath = getSessionLogPath() // session-specific log file path

log.info('Info message')
log.success('Success message')
log.warn('Warning message')
log.debug('Debug message', { context: 'extra data' })
log.logError({
  type:    'API_ERROR',
  message: 'Failed to fetch entries',
  error:   error,
  context: { stackApiKey: 'bltXXX' },
})

try {
  // your code
} catch (error) {
  handleAndLogError(error, { command: 'myplugin:do' }, 'Custom error message')
}

csdx config:set:log --path /path/to/logs
# or
export CS_CLI_LOG_PATH=/path/to/logs

import { Command } from '@contentstack/cli-command'
import {
  Args,
  flags,
  cliux,
  CLIError,
  isAuthenticated,
  managementSDKClient,
  redactObject,
  generateUid,
  formatDate,
  formatTime,
  configHandler,
} from '@contentstack/cli-utilities'

export default class MyCommand extends Command {
  static description = 'Fetch and display entries from a content type'

  static examples = ['csdx myplugin:do blog_post --stack-api-key

Warning: @contentstack/myplugin is a linked ESM module and cannot be auto-transpiled.