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