@salesforce/sf-plugins-core

What is @salesforce/sf-plugins-core?

@salesforce/sf-plugins-core is a core library for building Salesforce CLI plugins. It provides a set of utilities and base classes to streamline the development of plugins for the Salesforce CLI, enabling developers to create commands, handle user input, manage configuration, and interact with Salesforce APIs.

What are @salesforce/sf-plugins-core's main functionalities?

Command Base Class

The Command Base Class feature allows developers to create new CLI commands by extending the SfCommand class. This provides a structured way to define command behavior and output.

const { SfCommand } = require('@salesforce/sf-plugins-core');

class MyCommand extends SfCommand {
  async run() {
    this.log('Hello, Salesforce CLI!');
  }
}

module.exports = MyCommand;

User Input Handling

User Input Handling feature allows developers to define and parse command-line flags and arguments using the Flags utility. This makes it easy to handle user input in a consistent manner.

const { SfCommand, Flags } = require('@salesforce/sf-plugins-core');

class MyCommand extends SfCommand {
  static flags = {
    name: Flags.string({ char: 'n', description: 'name to print' })
  };

  async run() {
    const { flags } = this.parse(MyCommand);
    this.log(`Hello, ${flags.name}!`);
  }
}

module.exports = MyCommand;

Configuration Management

Configuration Management feature provides utilities to load and manage configuration settings for the CLI. This helps in maintaining consistent configuration across different commands and plugins.

const { SfCommand, Config } = require('@salesforce/sf-plugins-core');

class MyCommand extends SfCommand {
  async run() {
    const config = await Config.load();
    this.log(`Current config: ${JSON.stringify(config)}`);
  }
}

module.exports = MyCommand;

Salesforce API Interaction

Salesforce API Interaction feature allows developers to easily create connections to Salesforce and perform API operations such as queries. This simplifies the process of interacting with Salesforce data from CLI commands.

const { SfCommand, Connection } = require('@salesforce/sf-plugins-core');

class MyCommand extends SfCommand {
  async run() {
    const conn = await Connection.create({ authInfo: this.authInfo });
    const result = await conn.query('SELECT Id, Name FROM Account');
    this.log(`Fetched ${result.records.length} accounts`);
  }
}

module.exports = MyCommand;

Other packages similar to @salesforce/sf-plugins-core

oclif

oclif is a framework for building command-line interfaces (CLIs) in Node.js. It provides a robust set of tools for creating commands, handling input, and managing plugins. Compared to @salesforce/sf-plugins-core, oclif is more general-purpose and not specifically tailored to Salesforce, but it offers similar functionality for building CLI applications.

commander

commander is a popular Node.js library for building command-line interfaces. It provides a simple and flexible way to define commands, options, and arguments. While it does not offer the same level of integration with Salesforce as @salesforce/sf-plugins-core, it is widely used for general CLI development.

yargs

yargs is another powerful library for building command-line tools in Node.js. It focuses on parsing command-line arguments and generating user-friendly interfaces. Like commander, yargs is not specific to Salesforce but provides a comprehensive set of features for CLI development.

README

Description

The @salesforce/sf-plugins-core provides utilities for writing sf plugins.

Docs: https://salesforcecli.github.io/sf-plugins-core

SfCommand Abstract Class

The SfCommand abstract class extends @oclif/core's Command class for examples of how to build a definition. ) class and adds useful extensions to ease the development of commands for use in the Salesforce Unified CLI.

• SfCommand takes a generic type that defines the success JSON result
• Enable the json flag support by default
• Provides functions that help place success messages, warnings and errors into the correct location in JSON results
• Enables additional help sections to the standard oclif command help output
• Provides access to the cli-ux cli actions. This avoids having to import that interface from cli-ux and manually handling the --json flag.
• Provides simple, stubbable prompts for confirmation and secrets

Flags

Flags is a convenience reference to @oclif/core#Flags

Specialty Flags

These flags can be imported into a command and used like any other flag. See code examples in the links

• orgApiVersionFlag
  • specifies a Salesforce API version.
  • reads from Config (if available)
  • validates version is still active
  • warns if version if deprecated
• requiredOrgFlag
  • accepts a username or alias
  • aware of configuration defaults
  • throws if org or default doesn't exist or can't be found
• optionalOrgFlag
  • accepts a username or alias
  • aware of configuration defaults
  • might be undefined if an org isn't found
• requiredHubFlag
  • accepts a username or alias
  • aware of configuration defaults
  • throws if org or default doesn't exist or can't be found
  • throws if an org is found but is not a dev hub
• durationFlag
  • specify a unit
  • optionally specify a min, max, and defaultValue
  • returns a Duration
  • can be undefined if you don't set the default
• salesforceIdFlag
  • validates that IDs are valid salesforce ID
  • optionally restrict to 15/18 char
  • optionally require it to be begin with a certain prefix

Unit Test Helpers

Want to verify SfCommand Ux behavior (warnings, tables, spinners, prompts)? Check out the functions in `stubUx``.

Changelog

11.3.0 (2024-08-09)

Bug Fixes

• correct method signature (df4b2b7)

Features

• flush intra-command warnings at the end (68cafb3)