cli-command-development

CLI Command Development

This skill covers creating new CLI commands and topics for the B2C CLI.

Command Organization

Commands live in packages/b2c-cli/src/commands/. The directory structure maps directly to command names:

commands/
├── code/
│   ├── deploy.ts      → b2c code deploy
│   ├── activate.ts    → b2c code activate
│   └── list.ts        → b2c code list
├── sandbox/
│   ├── create.ts      → b2c sandbox create
│   └── list.ts        → b2c sandbox list
└── mrt/
    └── env/
        └── var/
            └── set.ts → b2c mrt env var set

Command Class Hierarchy

Choose the appropriate base class based on what your command needs:

BaseCommand (logging, JSON output, error handling)
  └─ OAuthCommand (OAuth authentication)
       ├─ InstanceCommand (B2C instance: hostname, code version)
       │   ├─ CartridgeCommand (cartridge path + filters)
       │   ├─ JobCommand (job execution helpers)
       │   └─ WebDavCommand (WebDAV root directory)
       ├─ MrtCommand (Managed Runtime API)
       └─ OdsCommand (On-Demand Sandbox API)

Import from @salesforce/b2c-tooling-sdk/cli:

import { InstanceCommand, CartridgeCommand, OdsCommand } from '@salesforce/b2c-tooling-sdk/cli';

Standard Command Template

/*
 * Copyright (c) 2025, Salesforce, Inc.
 * SPDX-License-Identifier: Apache-2
 * For full license text, see the license.txt file in the repo root
 */
import {Args, Flags} from '@oclif/core';
import {InstanceCommand} from '@salesforce/b2c-tooling-sdk/cli';
import {getApiErrorMessage} from '@salesforce/b2c-tooling-sdk';
import {t} from '../../i18n/index.js';

interface MyCommandResponse {
  success: boolean;
  data: SomeType[];
}

export default class MyCommand extends InstanceCommand<typeof MyCommand> {
  static description = t('commands.topic.mycommand.description', 'Human-readable description');

  static enableJsonFlag = true;

  static examples = [
    '<%= config.bin %> <%= command.id %> arg1',
    '<%= config.bin %> <%= command.id %> --flag value',
    '<%= config.bin %> <%= command.id %> --json',
  ];

  static args = {
    name: Args.string({
      description: 'Description of the argument',
      required: true,
    }),
  };

  static flags = {
    myFlag: Flags.string({
      char: 'm',
      description: 'Flag description',
      default: 'defaultValue',
    }),
    myBool: Flags.boolean({
      description: 'Boolean flag',
      default: false,
    }),
  };

  async run(): Promise<MyCommandResponse> {
    // Validation - call appropriate require* methods
    this.requireServer();

    // Access parsed args and flags
    const {name} = this.args;
    const {myFlag, myBool} = this.flags;

    this.log(t('commands.topic.mycommand.working', 'Working on {{name}}...', {name}));

    // Implementation
    const {data, error, response} = await this.instance.ocapi.GET('/some/endpoint');

    if (error) {
      this.error(t('commands.topic.mycommand.error', 'Failed: {{message}}', {
        message: getApiErrorMessage(error, response),
      }));
    }

    const result: MyCommandResponse = {
      success: true,
      data,
    };

    // JSON mode returns the object directly (oclif handles serialization)
    if (this.jsonEnabled()) {
      return result;
    }

    // Human-readable output
    this.log('Success!');
    return result;
  }
}