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

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

Usage

`bash


Using npx

npx sfcc-metadata-cli

Or add scripts to your package.json

`

$3

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

`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:

`bash
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
`

$3

#### Create Migration

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

`bash


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.

`bash


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.

`bash


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.

`bash


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.

`bash


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.

`bash


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.

`bash


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.

$3

| 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 |

$3

| 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

$3

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

$3

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

$3

`bash


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:

`bash


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

`bash


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