sfcc-metadata-cli

A companion CLI tool to b2c-tools for creating SFCC B2C migrations.

Features

• Create migrations with timestamp-based naming for unique, sortable names
• Generate custom object definitions with interactive prompts
• Add site preferences with automatic group detection
• Add organization preferences for instance-wide settings
• Extend system objects with custom attributes
• Create service definitions with credentials, profiles, and service configurations
• Create job definitions with step type suggestions from cartridges and native SFCC steps

Installation

npm install sfcc-metadata-cli --save-dev

Usage

# Using npx
npx sfcc-metadata-cli <command>

# Or add scripts to your package.json

package.json Scripts (Recommended)

Add these scripts to your project's package.json:

{
  "scripts": {
    "migration:create": "sfcc-metadata-cli create",
    "migration:custom-object": "sfcc-metadata-cli custom-object",
    "migration:site-preference": "sfcc-metadata-cli site-preference",
    "migration:org-preference": "sfcc-metadata-cli org-preference",
    "migration:system-object": "sfcc-metadata-cli system-object",
    "migration:service": "sfcc-metadata-cli service",
    "migration:job": "sfcc-metadata-cli job"
  }
}

Then run:

npm run migration:create
npm run migration:custom-object
npm run migration:site-preference
npm run migration:org-preference
npm run migration:system-object
npm run migration:service
npm run migration:job

Commands

Create Migration

Creates a new migration folder with timestamp-based naming: YYYYMMDD_HHMMSS_description

# Interactive mode
npx sfcc-metadata-cli create

# With description
npx sfcc-metadata-cli create "add order status field"
# Creates: 20251231_143052_add_order_status_field

# Short format (date + sequence)
npx sfcc-metadata-cli create --short "fix shipping"
# Creates: 20251231_01_fix_shipping

Custom Object Definition

Creates a custom object type definition in the meta/custom-objecttype-definitions.xml file.

# Interactive mode
npx sfcc-metadata-cli custom-object

# Example: Create a custom object for caching
npx sfcc-metadata-cli custom-object \
  --type-id CacheConfig \
  --display-name "Cache Configuration" \
  --key-id cacheKey \
  --storage-scope site

Site Preference

Creates a site preference attribute in the meta/system-objecttype-extensions.xml file.

# Interactive mode
npx sfcc-metadata-cli site-preference

# Example: Add a boolean preference
npx sfcc-metadata-cli site-preference \
  --attribute-id enableFeatureX \
  --type boolean \
  --default-value false \
  --group "Custom Configs"

Organization Preference

Creates an organization preference attribute (instance-wide settings) in the meta/system-objecttype-extensions.xml file.

# Interactive mode
npx sfcc-metadata-cli org-preference

# Example: Add an organization-level preference
npx sfcc-metadata-cli org-preference \
  --attribute-id globalApiKey \
  --type string \
  --group "Global Settings"

System Object Extension

Extends system objects (Order, Product, Customer, etc.) with custom attributes.

# Interactive mode
npx sfcc-metadata-cli system-object

# Example: Add a custom attribute to Order
npx sfcc-metadata-cli system-object \
  --object-type Order \
  --attribute-id customField \
  --type string \
  --group Order_Custom

Service Definition

Creates service definitions including credentials, profiles, and services in the services.xml file.

# Interactive mode
npx migration-helper service

# Example: Create an HTTP service
npx sfcc-metadata-cli service \
  --service-id MyAPI \
  --url "https://api.example.com" \
  --service-type HTTP \
  --timeout 30000

# Example: Create an FTP service with authentication
npx sfcc-metadata-cli service \
  --service-id MyFTP \
  --url "ftp://files.example.com" \
  --service-type FTP \
  --user-id ftpuser

Job Definition

Creates job definitions in the jobs.xml file with support for native SFCC steps and custom step types discovered from cartridges.

# Interactive mode (recommended - includes step type suggestions)
npx sfcc-metadata-cli job

# With cartridges directory for custom step discovery
npx sfcc-metadata-cli job --cartridges-dir ./cartridges

# Example: Create a job with specific options
npx sfcc-metadata-cli job \
  --job-id MyDailyJob \
  --description "Daily cleanup job" \
  --site-id RefArch

The job command automatically discovers custom step types from steptypes.json files in your cartridges and provides 69+ native SFCC step types for selection.

Common Options

Option	Alias	Description
--migrations-dir	-m	Path to migrations directory (default: ./migrations)
--interactive	-i	Enable/disable interactive mode
--help	-h	Show help
--version	-v	Show version number

Command Aliases

Command	Aliases
create	new, init
custom-object	co, customobject
site-preference	sp, sitepref, preference
org-preference	op, orgpref, org-pref
system-object	so, sysobj, extend
service	svc, srv
job	j

Migration Naming Convention

New Format (Recommended)

Migrations use timestamp-based naming for guaranteed uniqueness and natural sorting:

Format	Example	Description
YYYYMMDD_HHMMSS	20251231_143052	Full timestamp
YYYYMMDD_HHMMSS_desc	20251231_143052_add_order_fields	With description
YYYYMMDD_NN_desc	20251231_01_fix_shipping	Short format (--short flag)

Benefits:

• ✅ No conflicts - timestamp ensures uniqueness
• ✅ Self-documenting - description in the name
• ✅ Natural sorting - alphabetical order = chronological order
• ✅ Unlimited migrations per day

Legacy Format

Old migrations using YY.MM.N format are still supported and will sort before new migrations.

Supported Attribute Types

Type	Description
string	Single-line text
text	Multi-line text
html	HTML content
int	Integer number
double	Decimal number
boolean	True/False
date	Date only
datetime	Date and time
enum-of-string	Single/multi-select dropdown
enum-of-int	Integer enumeration
set-of-string	Set of strings
image	Image reference
password	Encrypted password

Examples

Create a Complete Migration

# 1. Create the migration folder
npx sfcc-metadata-cli create

# 2. Add a custom object
npx sfcc-metadata-cli custom-object

# 3. Add a site preference
npx sfcc-metadata-cli site-preference

# 4. Add a service definition
npx sfcc-metadata-cli service

# 5. Add a job definition
npx sfcc-metadata-cli job

# 6. Preview the migration
npm run migrate

# 7. Apply the migration
npm run migrate:apply

Integration with b2c-tools

After creating migrations with this tool, use b2c-tools to apply them:

# Preview migrations
node build/b2c-tools.js import migrate --dry-run

# Apply migrations
node build/b2c-tools.js import migrate

Release Process (for maintainers)

To publish a new version, use npm version which automatically:

1. Updates package.json version
2. Creates a git commit
3. Creates a git tag

# Patch release (1.0.0 -> 1.0.1)
npm version patch

# Minor release (1.0.0 -> 1.1.0)
npm version minor

# Major release (1.0.0 -> 2.0.0)
npm version major

# Then push with tags
git push && git push --tags

The CI will automatically publish to npm when the tag is pushed.

License

AGPL-3.0-or-later