Skip to content

cap.md

Latest commit

 

History

History
347 lines (234 loc) · 9.6 KB

cap.md

File metadata and controls

347 lines (234 loc) · 9.6 KB
description Commands for validating, packaging, installing, uninstalling, and listing Commerce App Packages (CAPs) and commerce features.

Commerce App (CAP) Commands

Commands for managing Commerce App Packages (CAPs) — the standard format for distributing B2C Commerce integrations — and listing commerce features installed on an instance.

Overview

A Commerce App Package bundles cartridges, IMPEX data, and Storefront Next extensions into a single installable unit. See the Commerce Apps guide for full workflow details.

The cap list and cap tasks commands work with the broader commerce feature state system, which tracks all installed features including ISV apps, native apps, native features, and custom features.

Authentication

Install, uninstall, list, and tasks commands require OAuth authentication with OCAPI permissions and WebDAV access.

Required OCAPI Permissions

Configure these resources in Business Manager under Administration > Site Development > Open Commerce API Settings:

Resource Methods Commands
/jobs/*/executions POST cap install, cap uninstall, cap list, cap tasks
/jobs/*/executions/* GET cap install, cap uninstall, cap list, cap tasks
/sites GET cap list (when no --site-id specified)

WebDAV Access

The cap install command uploads the CAP zip to WebDAV (Impex/commerce-apps/) before triggering the install job. The cap list, cap tasks, and cap uninstall commands download site archive exports via WebDAV.

b2c cap validate

Validate the structure and manifest of a Commerce App Package (CAP).

Usage

b2c cap validate PATH

Arguments

Argument Description
PATH Path to a CAP directory or .zip file

Flags

Flag Description
--json Output result as JSON

Validation Checks

Errors (blocking — must fix before install):

  • commerce-app.json must exist and be valid JSON
  • Manifest must include id, name, version, domain fields
  • version must be a valid semver string
  • app-configuration/tasksList.json must exist as a valid JSON array
  • Each task must have taskNumber, name, description, link
  • At least one of cartridges/, storefront-next/, or impex/ must be present
  • No pipeline/ directories in cartridges
  • No *.ds pipeline descriptor files
  • Site cartridges (cartridges/site_cartridges/) must not contain controllers/
  • README.md must exist

Warnings (advisory):

  • icons/icon.png is recommended for marketplace listing
  • impex/uninstall/ is recommended for clean removal

Examples

# Validate a local CAP directory
b2c cap validate ./commerce-avalara-tax-app-v0.2.5

# Validate a zipped CAP
b2c cap validate ./commerce-avalara-tax-app-v0.2.5.zip

# Machine-readable output
b2c cap validate ./commerce-avalara-tax-app-v0.2.5 --json

b2c cap package

Package a Commerce App directory into a distributable .zip file.

Usage

b2c cap package PATH [--output PATH]

Arguments

Argument Description
PATH Path to the CAP source directory

Flags

Flag Short Description
--output PATH -o Output path (directory or .zip filename). Defaults to current directory.
--json Output result as JSON

Examples

# Package to current directory
b2c cap package ./commerce-avalara-tax-app-v0.2.5

# Package to a specific output directory
b2c cap package ./commerce-avalara-tax-app-v0.2.5 --output ./dist

# Package with explicit zip filename
b2c cap package ./commerce-avalara-tax-app-v0.2.5 --output ./dist/my-app.zip

b2c cap install

Install a Commerce App Package on a B2C Commerce instance.

Usage

b2c cap install PATH --site-id SITE_ID

Arguments

Argument Description
PATH Path to a CAP directory or .zip file

Flags

Flag Short Description
--site-id SITE_ID -s Required. Site ID to install the app on
--clean-archive Delete the uploaded zip from the instance after install
--timeout SECONDS -t Timeout in seconds (default: no timeout)
--skip-validate Skip CAP structure validation before install
--json Output result as JSON

Install Process

  1. Validates the CAP structure (unless --skip-validate)
  2. Packages the directory into a zip if a directory is provided
  3. Uploads the zip to WebDAV at Impex/commerce-apps/{id}-v{version}.zip
  4. Executes the sfcc-install-commerce-app system job
  5. Waits for job completion
  6. Archive is kept on the instance by default (use --clean-archive to remove)

Examples

# Install from a local directory
b2c cap install ./commerce-avalara-tax-app-v0.2.5 --site-id RefArch

# Install from a zip
b2c cap install ./commerce-avalara-tax-app-v0.2.5.zip --site-id RefArch

# Install without running validation first
b2c cap install ./commerce-avalara-tax-app-v0.2.5 --site-id RefArch --skip-validate

# Remove the uploaded archive after install
b2c cap install ./commerce-avalara-tax-app-v0.2.5 --site-id RefArch --clean-archive

b2c cap uninstall

Uninstall a Commerce App from a B2C Commerce instance. Looks up the app's domain automatically from the commerce feature state.

Usage

b2c cap uninstall APP_NAME --site-id SITE_ID

Arguments

Argument Description
APP_NAME App ID to uninstall (from commerce-app.json "id" field, e.g. avalara-tax)

Flags

Flag Short Description
--site-id SITE_ID -s Required. Site ID to uninstall the app from
--timeout SECONDS -t Timeout in seconds (default: no timeout)
--json Output result as JSON

Examples

# Uninstall Avalara Tax from a site
b2c cap uninstall avalara-tax --site-id RefArch

b2c cap list

List commerce features installed on a B2C Commerce instance. Exports the commerce_feature_states data unit from each site and parses the results.

Usage

b2c cap list [--site-id SITE_IDS]

Flags

Flag Short Description
--site-id SITE_IDS -s Site IDs to query (comma-separated). If omitted, queries all sites.
--timeout SECONDS -t Timeout in seconds (default: no timeout)
--local -l List locally detected Commerce App Packages (no instance required)
--json Output result as JSON

Table Columns

Column Description
Site ID Site the feature is installed on (includes Sites- prefix)
Name Feature name (e.g. avalara-tax)
Type ISV_APP, NATIVE_APP, NATIVE_FEATURE, or CUSTOM_FEATURE
Source CUSTOM (uploaded via WebDAV) or REGISTRY (from App Registry)
Install Status e.g. INSTALLED
Config Status e.g. NOT_CONFIGURED, CONFIGURED
Version Feature version if available
Installed At Installation timestamp

JSON Output

With --json, returns the full feature state including configTasks (parsed JSON array of configuration steps) and installationMetadata (parsed JSON with job details, cartridge mappings, and IMPEX uninstall data).

Examples

# List all installed features across all sites
b2c cap list

# List features for specific sites
b2c cap list --site-id RefArch,SiteGenesis

# Machine-readable output with full details
b2c cap list --json

# List locally detected CAP directories
b2c cap list --local

b2c cap tasks

List configuration tasks for an installed Commerce App, with clickable links to Business Manager pages.

Usage

b2c cap tasks APP_NAME --site-id SITE_ID

Arguments

Argument Description
APP_NAME Commerce App feature name (e.g. avalara-tax)

Flags

Flag Short Description
--site-id SITE_ID -s Required. Site ID to query
--timeout SECONDS -t Timeout in seconds (default: no timeout)
--json Output result as JSON

Examples

# Show configuration tasks for an installed app
b2c cap tasks avalara-tax --site-id RefArch

# Get tasks as JSON (includes full feature state)
b2c cap tasks avalara-tax --site-id RefArch --json

b2c cap pull

Pull installed Commerce App source packages from a B2C Commerce instance. By default, pulls all registry-sourced apps. Optionally specify a single app by name.

Useful for deploying cartridges to a code version or working with Storefront Next extensions locally.

Usage

b2c cap pull [APP_NAME] [--site-id SITE_ID] [--output DIR]

Arguments

Argument Description
APP_NAME (optional) Commerce App feature name to pull (e.g. avalara-tax). If omitted, pulls all registry apps.

Flags

Flag Short Description
--site-id SITE_ID -s Site ID to query for installed apps. If omitted, queries all sites.
--output DIR -o Output directory (default: ./commerce-apps)
--timeout SECONDS -t Timeout in seconds (default: no timeout)
--json Output result as JSON

Examples

# Pull all registry apps to ./commerce-apps
b2c cap pull

# Pull a specific app by name
b2c cap pull avalara-tax

# Pull to a custom output directory
b2c cap pull --output ./my-apps

# Pull apps installed on a specific site
b2c cap pull --site-id RefArch