Integrate Your Plugin With the doctor Command

Salesforce CLI includes the doctor command that you can run if you’re having issues with the CLI. The command inspects your CLI installation and environment, runs diagnostic tests, provides suggestions, and writes the data to a local diagnostic file. See the Salesforce CLI Command Reference and Setup Guide for more information about the doctor command.

To help your users troubleshoot problems with your plugin, you can integrate it into the doctor command so it runs your custom diagnostic tests. You can add custom information to both the Running all diagnostics and Suggestions sections and to the JSON results file. For example:

1$ sf doctor
2=== Running all diagnostics
3
4pass - salesforcedx plugin isn’t installed
5pass - you don't have any linked plugins
6warn - [@salesforce/plugin-deploy-retrieve] sourceApiVersion matches apiVersion
7pass - [@salesforce/plugin-trust] can ping: https://registry.npmjs.org
8pass - [@salesforce/plugin-trust] can ping: https://registry.yarnpkg.com
9pass - [@salesforce/plugin-trust] can ping: https://registry.npmjs.org/
10pass - using latest or latest-rc CLI version
11pass - can access: https://test.salesforce.com
12pass - can access: https://appexchange.salesforce.com/services/data
13pass - can access: https://developer.salesforce.com/media/salesforce-cli/sf/channels/stable/sf-win32-x64-buildmanifest
14fail - [@salesforce/plugin-auth] CLI supports v2 crypto
15
16Wrote doctor diagnosis to: /Users/juliet.shackell/sfdx/dev-repos/cli.wiki/1721077460991-diagnosis.json
17
18=== Suggestions
19
20  * Check https://github.com/forcedotcom/cli/issues for CLI issues posted by the community.
21  * Check http://status.salesforce.com for general Salesforce availability and performance.
22  * Neither sourceApiVersion nor apiVersion are defined. The commands that deploy and retrieve source use the max apiVersion of the target org in this case. The issue isn't a problem, as long as it's the behavior you actually want.
23  * using npm registry https://registry.npmjs.org/ from npm config
24  * Your current installation of Salesforce CLI, including all the plugins you've linked and installed, doesn't yet support v2 crypto. All plugins and libraries must use at least version 6.7.0 of `@salesforce/core` to support v2 crypto. You're generally still able to successfully authenticate with your current CLI installation, but not if you generate a v2 crypto key.

Why Write Plugin-Specific Diagnostic Tests 

The main reason is to provide your users a quick and potential fix to an issue, and thus provide a better experience. Because you have a deep understanding of your plugin, you can likely predict potential problems your customers will run into. With the diagnostic tests, you can inspect their CLI and plugin configuration and suggest immediate actions if your users run into these predicted issues. If the suggestions don’t fix the problem, the doctor gathers the required information that users attach to GitHub issues or provide to Salesforce Customer Support.

Writing diagnostic tests isn’t a replacement for good command error handling. Rather, it’s a way to educate and clarify command usage within a complex system.

Examples of diagnostic tests include checking for:

  • An environment variable that changes the behavior of your plugin or a library that your plugin uses.
  • A setting within a project that changes plugin behavior.
  • Required dependencies (outside of NPM) that are missing or out of date.
  • A system that is required by your plugin that is unavailable.
  • Anything that your customers regularly need clarification on that the commands can’t handle directly.

How to Integrate Your Plugin Into the Doctor 

See the diagnostic test in the deploy and retrieve plugin for a real-life example. Also see the source code for the doctor command.

  1. Define a hook in the oclif section of your plugin’s package.json with this pattern, where <plugin-name> is the name property in your package.json file:

    1"sf-doctor-<plugin-name>": "./path/to/compiled/hook/handler"

    For example, the plugin-deploy-retrieve diagnostic hook is defined with this JSON snippet. The Typescript source file and directory for the hook handler is src/hooks/diagnostics.ts:

    1"oclif": {
2...
3  "hooks": {
4    "sf-doctor-@salesforce/plugin-deploy-retrieve": "./lib/hooks/diagnostics"
5  }
6}

  2. If you coded your plugin in TypeScript, add a devDependencies entry in package.json that points to @salesforce/plugin-info, which contains the required SfDoctor type. Use the latest version of plugin-info. For example:

    1"devDependencies": {
2  "@salesforce/plugin-info": "^3.3.18"
3}

  3. In the hook handler source file (src/hooks/diagnostics.ts in our example), define and export a hook function that runs after the doctor command is executed. Here’s a basic Typescript example that includes one diagnostic test called test1:

    1// Import the SfDoctor interface from plugin-info and Lifecycle class from  @salesforce/core
2import { SfDoctor } from "@salesforce/plugin-info";
3import { Lifecycle } from "@salesforce/core";
4
5// Define the shape of the hook function
6type HookFunction = (options: { doctor: SfDoctor }) => Promise<[void]>;
7
8// export the function
9export const hook: HookFunction = async (options) => {
10  return Promise.all([test1(options.doctor)]);
11};
12
13const test1 = async (doctor: SfDoctor): Promise<void> => {
14  // Add your code for "test1" here
15};

  4. Code the hook function to return the result of all your plugin’s diagnostic tests using Promise.all([test1(), test2(), test3()]);.

  5. Use doctor.addPluginData() in your diagnostic tests to add JSON data to the full doctor diagnostics report. This JSON data appears in the pluginSpecificData section of the JSON report. For example, this code in the hook handler:

    1const pluginName = 'my-plugin';
2const prop1 = 'firstValue';
3const prop2 = 'secondValue';
4
5...
6
7  doctor.addPluginData(pluginName, {
8    prop1,
9    prop2,
10  });

    Results in this JSON snippet in the full doctor diagnostic report:

    1"pluginSpecificData": {
2    "my-plugin": [
3      {
4        "prop1": "firstValue",
5        "prop2": "secondValue"
6     }
7    ]
8  },

  6. Use the global singleton Lifecycle class in your diagnostic tests to include the test name and status to the beginning section of the doctor command output. For example:

    1Lifecycle.getInstance().emit("Doctor:diagnostic", { testName, status });

    You must name the event Doctor:diagnostic and the payload must have this shape: { testName: string, status: string }, where status is one of 'pass' | 'fail' | 'warn' | 'unknown'

  7. Use the doctor.addSuggestion() method in your diagnostic tests to add suggestions, based on the test results, to the last part of the doctor output. For example:

    1doctor.addSuggestion(
2  "The environment variable ENV_VARIABLE is set, which can affect the behavior of the XX commands. Are you sure you want to set this env variable?",
3);

  8. Diagnostic tests can reference the command run by the doctor and all generated command output from the doctor diagnostics. For example:

    1// Get the command string run by the doctor.
2  const commandName = doctor.getDiagnosis().commandName;
3  if (commandName?.includes('project:deploy:start') {
4    /* run a test specific to that command */
5  }
6
7  // Parse the debug.log generated by the doctor.
8  // The code must wait for the command to execute and logs to be written.
9  const debugLog = doctor.getDiagnosis().logFilePaths;
10  if (debugLog?.length) {
11 // Get the log file path, read it, look for specific output, add suggestions.
12  }

Overview of Salesforce CLI Plugins
Salesforce CLI Release Notes
Get Started Developing Salesforce CLI Plugins
Design Principles and Guidelines
Code Your Plugin
Debug Your Plugin
Write Useful Messages
Test Your Plugin
Maintain Your Plugin
Integrate Your Plugin With the Doctor Command
Migrate Plugins Built for sfdx to sf