Expose CLI API to execute commands

To allow integrating CLI for Microsoft 365 in other tools we should export CLI’s API for executing commands in the CLI’s npm package. This will allow other tools that want to use CLI get a direct access to the API and not need to rely on executing CLI as a child process and interact with it through stdout, stderr and exit codes. When you install CLI for M365 as a dependency in your Node.js project, you should be able to do import { executeCommandWithOutput } from '@pnp/cli-microsoft365 and use the executeCommandWithOutput function to execute the specified command with its arguments and capture its output.

After we add this, we should also add a new page about integrating CLI in other tools in our documentation.

[waldekmastykarz]

After looking at different options together with @manekinekko, we came to the following implementation:

const { executeCommand } = require('@pnp/cli-microsoft365');

executeCommand('status', { output: 'text' })
  .then(res => {
    if (res.stdout === 'Logged out') {
      return executeCommand('login', { output: 'text' }, {
        stdout: message => console.log(message)
      });
    }

    return Promise.resolve();
  })
  .then(_ => executeCommand('spo site list', { output: 'json' }))
  .then(res => {
    const sites = JSON.parse(res.stdout);

    if (sites.length === 0) {
      return Promise.reject('No sites found');
    }

    const siteUrl = sites[0].Url;
    return executeCommand('spo web get', { webUrl: siteUrl, output: 'json' });
  })
  .then(res => console.log(res.stdout))
  .catch(err => console.error(err));

We use current CLI’s implementation with Promises to return command output after the command finished its execution. If you need to get command output while the command is still running (such as login to get the device code), you can pass an optional listener attached to stdout (main output) or stderr (verbose, debug, and error output).

In an ideal world, we’d align more closely with Node’s design of non-blocking IO and use streams eg. executeCommand().on('stdout', ...).on('stderr', ...).on('end', ...) but right now this would mean a significant rewrite of CLI’s internals. We might consider this approach in the future. For now, we’ll stick with promises.

You can find the latest sample and instructions to test in the repo I shared earlier in this issue.

[zhenyasav]

yeah zod is probably going to help delete many lines and offer free types. “parse, don’t validate!” 😃