feat(cap): add list, tasks, and pull commands with improved UX

- cap list: export and parse commerce_feature_states for installed features
- cap tasks: show config tasks with clickable BM links
- cap pull: download and extract app source packages from instance or GitHub
- Standardize --site-id flag across all cap commands (--site as alias)
- cap uninstall: auto-resolve domain from feature state (drop --domain)
- cap install: keep archive by default, upload to Impex/commerce-apps/
- Fix sites API select query (*) -> (**) and null XML parse handling
- Remove stub fixture fallback from list operation
- Export all CAP operations and types from SDK main index
- Update CLI docs, skill, and add changeset

Author: clavery

.changeset/cap-support-commands.md

@@ -0,0 +1,14 @@
+---
+'@salesforce/b2c-cli': minor
+'@salesforce/b2c-tooling-sdk': minor
+'@salesforce/b2c-dx-docs': patch
+---
+
+Add `cap list`, `cap tasks`, and `cap pull` commands for managing installed Commerce Apps
+
+- `cap list` exports and parses `commerce_feature_states` to show installed features with type, source, status, and version
+- `cap tasks` displays configuration tasks for an installed app with clickable Business Manager links
+- `cap pull` downloads and extracts installed app source packages for cartridge deployment or Storefront Next development
+- Standardize all cap commands to use `--site-id` flag (with `--site` as alias)
+- `cap uninstall` no longer requires `--domain` — looks it up automatically from the feature state
+- `cap install` now keeps the archive on the instance by default (use `--clean-archive` to remove)

docs/cli/cap.md

@@ -1,31 +1,34 @@
 ---
-description: Commands for validating, packaging, installing, and uninstalling Commerce App Packages (CAPs).
+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.
+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](/guide/commerce-apps) 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 and uninstall commands require OAuth authentication with OCAPI permissions and WebDAV access.
+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` |
-| `/jobs/*/executions/*` | GET | `cap install`, `cap uninstall` |
+| `/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 (`Temp/`) before triggering the install job.
+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.
 
 ---
 
@@ -119,7 +122,7 @@ b2c cap package ./commerce-avalara-tax-app-v0.2.5
 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-tax-app.zip
+b2c cap package ./commerce-avalara-tax-app-v0.2.5 --output ./dist/my-app.zip
 ```
 
 ---
@@ -131,7 +134,7 @@ Install a Commerce App Package on a B2C Commerce instance.
 ### Usage
 
 ```bash
-b2c cap install PATH --site SITE_ID
+b2c cap install PATH --site-id SITE_ID
 ```
 
 ### Arguments
@@ -144,8 +147,8 @@ b2c cap install PATH --site SITE_ID
 
 | Flag | Short | Description |
 |------|-------|-------------|
-| `--site SITE_ID` | `-s` | **Required.** Site ID to install the app on |
-| `--keep-archive` | `-k` | Keep the uploaded zip on the instance after install |
+| `--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 |
@@ -154,37 +157,37 @@ b2c cap install PATH --site SITE_ID
 
 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 `Temp/{id}-v{version}.zip`
+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. Removes the uploaded zip (unless `--keep-archive`)
+6. Archive is kept on the instance by default (use `--clean-archive` to remove)
 
 ### Examples
 
 ```bash
 # Install from a local directory
-b2c cap install ./commerce-avalara-tax-app-v0.2.5 --site RefArch
+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 RefArch
+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 RefArch --skip-validate
+b2c cap install ./commerce-avalara-tax-app-v0.2.5 --site-id RefArch --skip-validate
 
-# Keep the uploaded archive for debugging
-b2c cap install ./commerce-avalara-tax-app-v0.2.5 --site RefArch --keep-archive
+# 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.
+Uninstall a Commerce App from a B2C Commerce instance. Looks up the app's domain automatically from the commerce feature state.
 
 ### Usage
 
 ```bash
-b2c cap uninstall APP_NAME --domain DOMAIN --site SITE_ID
+b2c cap uninstall APP_NAME --site-id SITE_ID
 ```
 
 ### Arguments
@@ -197,20 +200,148 @@ b2c cap uninstall APP_NAME --domain DOMAIN --site SITE_ID
 
 | Flag | Short | Description |
 |------|-------|-------------|
-| `--domain DOMAIN` | `-d` | **Required.** Commerce app domain (e.g. `tax`, `shipping`, `fraud`) |
-| `--site SITE_ID` | `-s` | **Required.** Site ID to uninstall the app from |
+| `--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
 
 ```bash
 # Uninstall Avalara Tax from a site
-b2c cap uninstall avalara-tax --domain tax --site RefArch
+b2c cap uninstall avalara-tax --site-id RefArch
 ```
 
 ---
 
 ## b2c cap list
 
-> **Not yet implemented.** Listing installed Commerce Apps will be available in a future release.
+List commerce features installed on a B2C Commerce instance. Exports the `commerce_feature_states` data unit from each site and parses the results.
+
+### Usage
+
+```bash
+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
+
+```bash
+# 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
+
+```bash
+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
+
+```bash
+# 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
+
+```bash
+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
+
+```bash
+# 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
+```

packages/b2c-cli/src/commands/cap/install.ts

@@ -36,14 +36,14 @@ export default class CapInstall extends JobCommand<typeof CapInstall> {
 
   static flags = {
     ...JobCommand.baseFlags,
-    site: Flags.string({
+    'site-id': Flags.string({
       char: 's',
       description: 'Site ID to install the Commerce App on',
       required: true,
+      aliases: ['site'],
     }),
-    'keep-archive': Flags.boolean({
-      char: 'k',
-      description: 'Keep the uploaded zip on the instance after install',
+    'clean-archive': Flags.boolean({
+      description: 'Delete the uploaded zip from the instance after install',
       default: false,
     }),
     timeout: Flags.integer({
@@ -66,7 +66,7 @@ export default class CapInstall extends JobCommand<typeof CapInstall> {
     this.requireWebDavCredentials();
 
     const {path} = this.args;
-    const {site, 'keep-archive': keepArchive, timeout, 'skip-validate': skipValidate} = this.flags;
+    const {'site-id': site, 'clean-archive': cleanArchive, timeout, 'skip-validate': skipValidate} = this.flags;
     const hostname = this.resolvedConfig.values.hostname!;
 
     // Validate first unless skipped
@@ -117,16 +117,15 @@ export default class CapInstall extends JobCommand<typeof CapInstall> {
     try {
       const result = await this.operations.commerceAppInstall(this.instance, path, {
         siteId: site,
-        keepArchive,
+        keepArchive: !cleanArchive,
         waitOptions: {
-          timeout: timeout ? timeout * 1000 : undefined,
-          onProgress: (exec, elapsed) => {
+          timeoutSeconds: timeout || undefined,
+          onPoll: (info) => {
             if (!this.jsonEnabled()) {
-              const elapsedSec = Math.floor(elapsed / 1000);
               this.log(
                 t('commands.cap.install.progress', '  Status: {{status}} ({{elapsed}}s elapsed)', {
-                  status: exec.execution_status,
-                  elapsed: elapsedSec.toString(),
+                  status: info.status,
+                  elapsed: Math.floor(info.elapsedSeconds).toString(),
                 }),
               );
             }