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:

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.

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:

    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:

  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:

  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:

  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:

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

  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:

    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:

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