feat: add --wait/--no-wait flag to job import command

Add --wait/--no-wait and --poll-interval flags to `b2c job import`.
Import waits for completion by default (preserving existing behavior);
use --no-wait to return immediately after the job starts.

Also fixes inaccurate flag documentation in b2c-job and
b2c-site-import-export skills.

Author: clavery

.changeset/job-import-wait-flag.md

@@ -0,0 +1,6 @@
+---
+'@salesforce/b2c-cli': patch
+'@salesforce/b2c-tooling-sdk': patch
+---
+
+Add `--wait` / `--no-wait` flag to `b2c job import` command. Import waits for completion by default (preserving existing behavior); use `--no-wait` to return immediately after the job starts. Also adds `--poll-interval` flag for controlling poll frequency.

packages/b2c-cli/src/commands/job/import.ts

@@ -39,6 +39,12 @@ export default class JobImport extends JobCommand<typeof JobImport> {
 
   static flags = {
     ...JobCommand.baseFlags,
+    wait: Flags.boolean({
+      char: 'w',
+      description: 'Wait for import job to complete',
+      default: true,
+      allowNo: true,
+    }),
     'keep-archive': Flags.boolean({
       char: 'k',
       description: 'Keep archive on instance after import',
@@ -53,6 +59,11 @@ export default class JobImport extends JobCommand<typeof JobImport> {
       char: 't',
       description: 'Timeout in seconds (default: no timeout)',
     }),
+    'poll-interval': Flags.integer({
+      description: 'Polling interval in seconds when using --wait',
+      default: 3,
+      dependsOn: ['wait'],
+    }),
     'show-log': Flags.boolean({
       description: 'Show job log on failure',
       default: true,
@@ -68,7 +79,14 @@ export default class JobImport extends JobCommand<typeof JobImport> {
     this.requireWebDavCredentials();
 
     const {target} = this.args;
-    const {'keep-archive': keepArchive, remote, timeout, 'show-log': showLog = true} = this.flags;
+    const {
+      wait,
+      'keep-archive': keepArchive,
+      remote,
+      timeout,
+      'poll-interval': pollInterval,
+      'show-log': showLog = true,
+    } = this.flags;
 
     const hostname = this.resolvedConfig.values.hostname!;
 
@@ -134,8 +152,10 @@ export default class JobImport extends JobCommand<typeof JobImport> {
 
       const result = await this.operations.siteArchiveImport(this.instance, importTarget, {
         keepArchive,
+        wait,
         waitOptions: {
           timeoutSeconds: timeout,
+          pollIntervalSeconds: pollInterval,
           onPoll: (info) => {
             if (!this.jsonEnabled()) {
               this.log(
@@ -149,13 +169,22 @@ export default class JobImport extends JobCommand<typeof JobImport> {
         },
       });
 
-      const durationSec = result.execution.duration ? (result.execution.duration / 1000).toFixed(1) : 'N/A';
-      this.log(
-        t('commands.job.import.completed', 'Import completed: {{status}} (duration: {{duration}}s)', {
-          status: result.execution.exit_status?.code || result.execution.execution_status,
-          duration: durationSec,
-        }),
-      );
+      if (wait) {
+        const durationSec = result.execution.duration ? (result.execution.duration / 1000).toFixed(1) : 'N/A';
+        this.log(
+          t('commands.job.import.completed', 'Import completed: {{status}} (duration: {{duration}}s)', {
+            status: result.execution.exit_status?.code || result.execution.execution_status,
+            duration: durationSec,
+          }),
+        );
+      } else {
+        this.log(
+          t('commands.job.import.started', 'Import job started: {{executionId}} (status: {{status}})', {
+            executionId: result.execution.id,
+            status: result.execution.execution_status,
+          }),
+        );
+      }
 
       if (result.archiveKept) {
         this.log(

packages/b2c-cli/test/commands/job/import.test.ts

@@ -93,6 +93,48 @@ describe('job import', () => {
     expect(result.execution.exit_status.code).to.equal('skipped');
   });
 
+  it('passes wait:false to siteArchiveImport when --no-wait is set', async () => {
+    const command: any = await createCommand({wait: false, json: true}, {target: './dir'});
+    stubCommon(command);
+
+    sinon.stub(command, 'runBeforeHooks').resolves({skip: false});
+    sinon.stub(command, 'runAfterHooks').resolves(void 0);
+
+    const importStub = sinon.stub().resolves({
+      execution: {id: 'exec-1', execution_status: 'running'} as any,
+      archiveFilename: 'import-123.zip',
+      archiveKept: true,
+    });
+    command.operations = {...command.operations, siteArchiveImport: importStub};
+
+    const result = await command.run();
+
+    expect(importStub.calledOnce).to.equal(true);
+    const options = importStub.getCall(0).args[2];
+    expect(options.wait).to.equal(false);
+    expect(result.execution.execution_status).to.equal('running');
+  });
+
+  it('passes wait:true to siteArchiveImport by default', async () => {
+    const command: any = await createCommand({wait: true, json: true}, {target: './dir'});
+    stubCommon(command);
+
+    sinon.stub(command, 'runBeforeHooks').resolves({skip: false});
+    sinon.stub(command, 'runAfterHooks').resolves(void 0);
+
+    const importStub = sinon.stub().resolves({
+      execution: {execution_status: 'finished', exit_status: {code: 'OK'}} as any,
+      archiveFilename: 'a.zip',
+      archiveKept: false,
+    });
+    command.operations = {...command.operations, siteArchiveImport: importStub};
+
+    await command.run();
+
+    const options = importStub.getCall(0).args[2];
+    expect(options.wait).to.equal(true);
+  });
+
   it('shows job log and errors on JobExecutionError when show-log is true', async () => {
     const command: any = await createCommand({json: true}, {target: './dir'});
     stubCommon(command);

packages/b2c-tooling-sdk/src/operations/jobs/site-archive.ts

@@ -25,6 +25,8 @@ const EXPORT_JOB_ID = 'sfcc-site-archive-export';
 export interface SiteArchiveImportOptions {
   /** Keep archive on instance after import (default: false) */
   keepArchive?: boolean;
+  /** Whether to wait for job completion (default: true) */
+  wait?: boolean;
   /** Wait options for job completion */
   waitOptions?: WaitForJobOptions;
 }
@@ -98,7 +100,7 @@ export async function siteArchiveImport(
   options: SiteArchiveImportOptions & {archiveName?: string} = {},
 ): Promise<SiteArchiveImportResult> {
   const logger = getLogger();
-  const {keepArchive = false, waitOptions, archiveName} = options;
+  const {keepArchive = false, wait = true, waitOptions, archiveName} = options;
 
   let zipFilename: string;
   let needsUpload = true;
@@ -196,32 +198,34 @@ export async function siteArchiveImport(
 
   logger.debug({jobId: IMPORT_JOB_ID, executionId: execution.id}, `Import job started: ${execution.id}`);
 
-  // Wait for completion
-  try {
-    execution = await waitForJob(instance, IMPORT_JOB_ID, execution.id!, waitOptions);
-  } catch (error) {
-    if (error instanceof JobExecutionError) {
-      // Try to get log file
-      try {
-        const log = await getJobLog(instance, error.execution);
-        logger.error({jobId: IMPORT_JOB_ID, logFile: error.execution.log_file_path, log}, `Job log:\n${log}`);
-      } catch {
-        logger.error({jobId: IMPORT_JOB_ID}, 'Could not retrieve job log');
+  if (wait) {
+    // Wait for completion
+    try {
+      execution = await waitForJob(instance, IMPORT_JOB_ID, execution.id!, waitOptions);
+    } catch (error) {
+      if (error instanceof JobExecutionError) {
+        // Try to get log file
+        try {
+          const log = await getJobLog(instance, error.execution);
+          logger.error({jobId: IMPORT_JOB_ID, logFile: error.execution.log_file_path, log}, `Job log:\n${log}`);
+        } catch {
+          logger.error({jobId: IMPORT_JOB_ID}, 'Could not retrieve job log');
+        }
       }
+      throw error;
     }
-    throw error;
-  }
 
-  // Clean up archive if not keeping
-  if (!keepArchive && needsUpload) {
-    await instance.webdav.delete(uploadPath);
-    logger.debug({path: uploadPath}, `Archive deleted: ${uploadPath}`);
+    // Clean up archive if not keeping
+    if (!keepArchive && needsUpload) {
+      await instance.webdav.delete(uploadPath);
+      logger.debug({path: uploadPath}, `Archive deleted: ${uploadPath}`);
+    }
   }
 
   return {
     execution,
     archiveFilename: zipFilename,
-    archiveKept: keepArchive,
+    archiveKept: wait ? keepArchive : true,
   };
 }
 

packages/b2c-tooling-sdk/test/operations/jobs/site-archive.test.ts

@@ -339,6 +339,53 @@ describe('operations/jobs/site-archive', () => {
       expect(paths).to.include(`${archiveRoot}/libraries/mylib/library.xml`);
     });
 
+    it('should return immediately without polling when wait is false', async () => {
+      const zipPath = path.join(tempDir, 'test.zip');
+      fs.writeFileSync(zipPath, Buffer.from('PK\x03\x04'));
+
+      let polled = false;
+      let deleteRequested = false;
+
+      server.use(
+        http.all(`${WEBDAV_BASE}/*`, async ({request}) => {
+          if (request.method === 'PUT') {
+            return new HttpResponse(null, {status: 201});
+          }
+          if (request.method === 'DELETE') {
+            deleteRequested = true;
+            return new HttpResponse(null, {status: 204});
+          }
+          return new HttpResponse(null, {status: 404});
+        }),
+        http.post(`${OCAPI_BASE}/jobs/sfcc-site-archive-import/executions`, () => {
+          return HttpResponse.json({
+            id: 'exec-nowait',
+            execution_status: 'running',
+          });
+        }),
+        http.get(`${OCAPI_BASE}/jobs/sfcc-site-archive-import/executions/exec-nowait`, () => {
+          polled = true;
+          return HttpResponse.json({
+            id: 'exec-nowait',
+            execution_status: 'finished',
+            exit_status: {code: 'OK'},
+            is_log_file_existing: false,
+          });
+        }),
+      );
+
+      const result = await siteArchiveImport(mockInstance, zipPath, {
+        wait: false,
+        waitOptions: FAST_WAIT_OPTIONS,
+      });
+
+      expect(result.execution.id).to.equal('exec-nowait');
+      expect(result.execution.execution_status).to.equal('running');
+      expect(result.archiveKept).to.be.true;
+      expect(polled).to.be.false;
+      expect(deleteRequested).to.be.false;
+    });
+
     it('should throw JobExecutionError when import fails', async () => {
       const zipPath = path.join(tempDir, 'test.zip');
       fs.writeFileSync(zipPath, Buffer.from('PK\x03\x04'));

skills/b2c-cli/skills/b2c-job/SKILL.md

@@ -38,25 +38,28 @@ Some system jobs (like search indexing) use non-standard request schemas. Use `-
 
 ```bash
 # run search index job for specific sites
-b2c job run sfcc-search-index-product-full-update --wait --body '{"site_scope":["RefArch","SiteGenesis"]}'
+b2c job run sfcc-search-index-product-full-update --wait --body '{"site_scope":{"named_sites":["RefArch","SiteGenesis"]}}'
 
 # run search index job for a single site
-b2c job run sfcc-search-index-product-full-update --wait --body '{"site_scope":["RefArch"]}'
+b2c job run sfcc-search-index-product-full-update --wait --body '{"site_scope":{"named_sites":["RefArch"]}}'
 ```
 
 Note: `--body` and `-P` are mutually exclusive.
 
 ### Import Site Archives
 
-The `job import` command automatically waits for the import job to complete before returning. It does not use the `--wait` option.
+The `job import` command waits for the import job to complete by default.
 
 ```bash
-# import a local directory as a site archive
+# import a local directory as a site archive (waits for completion by default)
 b2c job import ./my-site-data
 
 # import a local zip file
 b2c job import ./export.zip
 
+# import and return immediately without waiting for completion
+b2c job import ./my-site-data --no-wait
+
 # keep the archive on the instance after import
 b2c job import ./my-site-data --keep-archive
 
@@ -158,8 +161,8 @@ b2c job search --json
 ### Wait for Job Completion
 
 ```bash
-# wait for a specific job execution to complete
-b2c job wait <execution-id>
+# wait for a specific job execution to complete (requires both job ID and execution ID)
+b2c job wait <job-id> <execution-id>
 ```
 
 ### More Commands

skills/b2c-cli/skills/b2c-site-import-export/SKILL.md

@@ -14,11 +14,11 @@ Use the `b2c` CLI plugin to import and export site archives on Salesforce B2C Co
 ### Import Local Directory
 
 ```bash
-# Import a local directory as a site archive
+# Import a local directory as a site archive (waits for completion by default)
 b2c job import ./my-site-data
 
-# Import and wait for completion
-b2c job import ./my-site-data --wait
+# Import and return immediately without waiting
+b2c job import ./my-site-data --no-wait
 
 # Import a local zip file
 b2c job import ./export.zip
@@ -27,7 +27,7 @@ b2c job import ./export.zip
 b2c job import ./my-site-data --keep-archive
 
 # Show job log if the import fails
-b2c job import ./my-site-data --wait --show-log
+b2c job import ./my-site-data --show-log
 ```
 
 ### Import Remote Archive
@@ -40,11 +40,11 @@ b2c job import existing-archive.zip --remote
 ## Export Commands
 
 ```bash
-# Export site data
-b2c job export
+# Export global metadata (waits for completion by default)
+b2c job export --global-data meta_data
 
-# Export with specific configuration
-b2c job export --wait
+# Export a site with specific data units
+b2c job export --site RefArch --site-data content,site_preferences
 ```
 
 ## Common Workflows
@@ -85,7 +85,7 @@ my-import/
 
 3. Import:
 ```bash
-b2c job import ./my-import --wait
+b2c job import ./my-import
 ```
 
 ### Adding Site Preferences
@@ -134,7 +134,7 @@ my-import/
 
 4. Import:
 ```bash
-b2c job import ./my-import --wait
+b2c job import ./my-import
 ```
 
 ### Creating a Custom Object Type
@@ -175,7 +175,7 @@ b2c job import ./my-import --wait
 
 2. Import:
 ```bash
-b2c job import ./my-import --wait
+b2c job import ./my-import
 ```
 
 ### Importing Custom Object Data
@@ -227,16 +227,16 @@ site-archive/
 b2c job search
 
 # Wait for a specific job execution
-b2c job wait <execution-id>
+b2c job wait <job-id> <execution-id>
 
 # View job logs on failure
-b2c job import ./my-data --wait --show-log
+b2c job import ./my-data --show-log
 ```
 
 ### Best Practices
 
 1. **Test imports on sandbox first** before importing to staging/production
-2. **Use `--wait`** to ensure import completes before continuing
+2. Import waits for completion by default — use `--no-wait` only when you want to return immediately
 3. **Use `--show-log`** to debug failed imports
 4. **Keep archives organized** by feature or change type
 5. **Version control your metadata** XML files