@optimizely/cms-cli

@optimizely/cms-cli

The official command-line tool for Optimizely CMS that enables code-first content modeling. Sync your TypeScript content type definitions to Optimizely CMS, allowing you to manage content models alongside your code with full version control.

Features

• ContentTypes-to-CMS sync - Push your TypeScript definitions to Optimizely CMS
• Code-first workflow - Define content types in your preferred IDE with IntelliSense
• Version control - Manage content types alongside your application code
• Simple CLI commands - Intuitive interface for common tasks
• Seamless integration - Works perfectly with @optimizely/cms-sdk

Installation

Install as a development dependency:

npm install -D @optimizely/cms-cli

Or using other package managers:

# pnpm
pnpm add -D @optimizely/cms-cli

# yarn
yarn add -D @optimizely/cms-cli

Tip: You can also use npx @optimizely/cms-cli to run commands without installing the package.

Quick Start

1. Configure your environment

Create a .env file in your project root with your CMS credentials:

OPTIMIZELY_CMS_URL=https://your-cms-instance.com
OPTIMIZELY_CMS_CLIENT_ID=your-client-id
OPTIMIZELY_CMS_CLIENT_SECRET=your-client-secret

2. Define your content types

Create TypeScript definitions for your content models:

import { contentType } from '@optimizely/cms-sdk';

export const ArticlePage = contentType({
  key: 'Article',
  displayName: 'Article page',
  baseType: '_page',
  properties: {
    title: {
      displayName: 'Title',
      type: 'string',
    },
    subtitle: {
      type: 'string',
      displayName: 'Subtitle',
    },
    body: {
      displayName: 'body ',
      type: 'richText',
    },
  },
});

3. Sync to CMS

Run the CLI to push your definitions to Optimizely CMS:

# If installed as a dependency
pnpm exec optimizely-cms-cli config push ./optimizely.config.mjs

# Or using npx without installation
npx @optimizely/cms-cli config push ./optimizely.config.mjs

Commands

All commands can be run using either the installed CLI or via npx @optimizely/cms-cli.

Configuration Management

Sync your TypeScript content type definitions with Optimizely CMS:

# Push content types to CMS (reads ./optimizely.config.mjs from project root by default)
optimizely-cms-cli config push
# or: npx @optimizely/cms-cli config push

# Push with custom config file path
optimizely-cms-cli config push ./path/to/custom-config.mjs

# Force update (may result in data loss)
optimizely-cms-cli config push --force

# Pull content types from CMS and generate TypeScript files (prompts for options)
optimizely-cms-cli config pull

# With output directory specified
optimizely-cms-cli config pull --output ./src/content-types

# Group generated files by content type base type (page/, component/, section/, etc.)
optimizely-cms-cli config pull --output ./src/types --group

# Output raw JSON manifest (useful for piping/processing)
optimizely-cms-cli config pull --json

# Save raw JSON manifest to file (automatically detects redirection)
optimizely-cms-cli config pull > manifest.json

# Or explicitly specify JSON output
optimizely-cms-cli config pull --json > manifest.json

# Pipe JSON output to other commands (automatically detects piping)
optimizely-cms-cli config pull | jq .contentTypes
optimizely-cms-cli config pull | grep -i "Article"

# Include read-only system content types
optimizely-cms-cli config pull --include-read-only

Note: The command automatically detects when output is piped or redirected and outputs JSON without prompting. You can also explicitly use --json to force JSON output. The --output flag works in all environments, including CI/non-TTY contexts.

Note: Use --include-read-only to pull all content types including system-generated read-only types. By default, only user-editable content types are pulled. This flag is useful for:

• PaaS environments where content types may be created from C# or .NET applications

• Auditing or understanding the full CMS content type schema

• Generating TypeScript types for content types in CMS managed by other systems like CMP

Note that read-only types cannot be modified via the CLI or CMS REST API.

Note: When using --group:

• Display templates are co-located with their content types in the same file
• Orphaned display templates (without a matching content type) are placed in the displayTemplates/ directory

See File Organization below for detailed examples.

Authentication

Verify your CMS credentials are correctly configured:

# Test your credentials from environment variables
optimizely-cms-cli login

# Show detailed authentication output
optimizely-cms-cli login --verbose

Content Type Operations

Manage individual content types:

# Delete a specific content type
optimizely-cms-cli content delete ArticlePage

# Delete with custom host
optimizely-cms-cli content delete ProductPage --host https://example.com

Dangerous Operations

⚠️ Use with extreme caution - these commands are destructive:

# Delete ALL user-defined content types (interactive confirmation required)
optimizely-cms-cli danger delete-all-content-types

Get Help

# Show all available commands
optimizely-cms-cli --help

# Show help for a specific command
optimizely-cms-cli config push --help

# Show help for a topic
optimizely-cms-cli config --help

File Organization

Pull Command Output Structure

When pulling content types from CMS, the CLI generates TypeScript files with different organization strategies:

Without --group flag (default)

src/content-types/
├── ArticlePage.ts
├── ProductPage.ts
├── HeroComponent.ts
└── display-templates/
    ├── ArticleDisplayTemplate.ts
    └── HeroDisplayTemplate.ts

With --group flag

Organizes files by content type base type (_page, _component, _section, etc.) and co-locates display templates with their content types:

src/types/
├── page/
│   ├── ArticlePage.ts      # Contains ArticlePageCT + ArticleDisplayTemplateDT
│   └── ProductPage.ts       # Contains ProductPageCT + ProductDisplayTemplateDT
├── component/
│   ├── HeroComponent.ts     # Contains HeroComponentCT + HeroDisplayTemplateDT
│   └── Teaser.ts            # Contains TeaserCT + TeaserDisplayTemplateDT
├── section/
│   └── ContentSection.ts    # Contains ContentSectionCT + ContentSectionDisplayTemplateDT
└── displayTemplates/        # Only created if orphaned templates exist
    └── LegacyTemplate.ts    # Display templates with no matching content type

Example co-located file (page/ArticlePage.ts):

import { contentType, displayTemplate } from '@optimizely/cms-sdk';

/**
 * Article Page
 */
export const ArticlePageCT = contentType({
  key: 'ArticlePage',
  baseType: '_page',
  properties: {
    /* ... */
  },
});

/**
 * Article Display Template
 */
export const ArticleDisplayTemplateDT = displayTemplate({
  key: 'ArticleDisplayTemplate',
  contentType: 'ArticlePage',
  isDefault: true,
});

Benefits of grouping:

• Better organization by content type category
• Related display templates are co-located with their content types
• Fewer files to manage
• Clear visibility of orphaned templates that may need attention

Documentation

For comprehensive guides and best practices:

Getting Started

• Installation - Set up your development environment
• Setup - Configure the SDK and CLI
• Modelling - Define your content types with TypeScript

Workflow Guides

• Create Content - Add content in Optimizely CMS after syncing types
• Fetching Content - Use the SDK to retrieve typed content

Best Practices

This CLI tool works best when used alongside the @optimizely/cms-sdk for a complete type-safe development experience:

# Install both packages
npm install @optimizely/cms-sdk
npm install -D @optimizely/cms-cli

The typical workflow:

• Define content types in TypeScript
• Use the CLI to sync definitions to CMS
• Create content in Optimizely CMS
• Fetch and render content with the SDK

For complete setup instructions, see the main repository README.

Support

• Community Slack - Join the Optimizely Community Slack
• GitHub Issues - Report bugs or request features on GitHub

License

Apache License 2.0

Built by the Optimizely CMS Team | Documentation | GitHub