Anypoint CLI Command Library

1.6.8 · active · verified Wed Apr 22

The `@mulesoft/anypoint-cli-command` package provides the foundational `Core` class for developing custom commands within the Anypoint CLI version 4 and later ecosystem. It extends `@oclif/core`, inheriting its robust command-line interface framework while adding Anypoint-specific functionalities. Developers leverage this library to gain convenient access to common CLI parameters, a standardized logging mechanism, output formatting utilities, and support for Anypoint platform features like scratch orgs. The current stable version, 1.6.8, is closely aligned with the Anypoint CLI's development cycle, receiving updates as part of the broader toolset's evolution. Its key differentiator is the deep integration with Anypoint platform concepts, streamlining the creation of purpose-built Anypoint CLI extensions.

Common errors

```
Error: You are attempting to use a command library that requires Anypoint CLI v4.0.0 or later. Your current version is X.
```
cause Attempting to use a command built with this library with an older version of Anypoint CLI.

fix Upgrade your Anypoint CLI to version 4.0.0 or later: `npm update -g @mulesoft/anypoint-cli-v4` or reinstall with the latest version.
```
TypeError: Class extends value undefined is not a constructor or null
```
cause The base `Core` class from `@mulesoft/anypoint-cli-command` or `Command` from `@oclif/core` was not properly imported or installed.

fix Ensure both `@mulesoft/anypoint-cli-command` and `@oclif/core` are installed in your project: `npm install @mulesoft/anypoint-cli-command @oclif/core` and that imports are correct.
```
Error: Cannot find module '@mulesoft/anypoint-cli-command' or its corresponding type declarations.
```
cause The package `@mulesoft/anypoint-cli-command` is not installed or the TypeScript configuration is incorrect.

fix Install the package: `npm install @mulesoft/anypoint-cli-command` (and `@oclif/core`). If using TypeScript, ensure `tsconfig.json` includes `"moduleResolution": "node"` or appropriate settings.

Warnings

breaking This library is strictly compatible only with Anypoint CLI version 4.0.0 or later. Using it with older versions of Anypoint CLI will lead to runtime errors.
Fix: Ensure your installed Anypoint CLI version is 4.0.0 or higher by running `anypoint-cli-v4 --version` and updating if necessary.
gotcha The documentation references an internal Confluence link ('How to develop a plug-in'). This resource is not publicly accessible and may be outdated, leading to dead links or inaccessible information for external developers.
Fix: Rely on the public GitHub repository's README for essential usage information or consult external oclif documentation if specific Anypoint CLI library docs are missing.
gotcha This package requires Node.js version 16.0.0 or higher. Running it with older Node.js versions may cause unexpected behavior or failures due to modern JavaScript syntax and API usage.
Fix: Update your Node.js environment to version 16.0.0 or later using a tool like nvm or your preferred package manager.
gotcha The `Core` class extends `@oclif/core`. Developers must be familiar with oclif's command structure, flag definitions, and parsing mechanisms to effectively use this library.
Fix: Consult the official `@oclif/core` documentation for best practices and advanced usage, as this package primarily adds Anypoint-specific wrappers.

Install

npm install anypoint-cli-command npm
yarn add anypoint-cli-command yarn
pnpm add anypoint-cli-command pnpm

Imports

Core

wrong:

const { Core } = require('@mulesoft/anypoint-cli-command');

correct:

import { Core } from '@mulesoft/anypoint-cli-command';

Primarily used as an ES module for extending base CLI commands. Node.js >=16.0.0 is required.

Command
```
import { Command } from '@oclif/core';
```
While extending 'Core' from this package, you will frequently need to import 'Command' and 'Flags' directly from '@oclif/core' for defining your CLI's structure and arguments.
Flags
```
import { Flags } from '@oclif/core';
```
Flags are part of the underlying oclif framework and are essential for defining command-line arguments and options for commands built with this library.

Quickstart

Demonstrates creating a new CLI command by extending the `Core` class, parsing flags, and using the built-in logger.

import { Command, Flags } from '@oclif/core';
import { Core } from '@mulesoft/anypoint-cli-command';

interface MyCommandFlags {
  name: string;
  force: boolean;
}

export default class MyHelloCommand extends Core<typeof MyHelloCommand> {
  static description = 'Say hello to a specified name using Anypoint CLI command base.';

  static examples = [
    '<%= config.bin %> <%= command.id %> --name Alice',
    '<%= config.bin %> <%= command.id %> -f'
  ];

  static flags = {
    name: Flags.string({ char: 'n', description: 'Name to greet.', required: false }),
    force: Flags.boolean({ char: 'f', description: 'Force a greeting even if no name is provided.', default: false }),
  };

  public async run(): Promise<void> {
    const { flags } = await this.parse(MyHelloCommand);
    const { name, force } = flags;

    if (force) {
      this.log('Forcing greeting operation...');
    }

    if (name) {
      this.log(`Hello, ${name} from your Anypoint CLI Command!`);
    } else if (force) {
      this.log('Hello, anonymous user (forced greeting)!');
    } else {
      this.error('Please provide a name or use the --force flag.');
    }

    this.logger.info(`MyHelloCommand executed with name: ${name ?? 'N/A'}, force: ${force}`);
    this.exit(0);
  }
}

view raw JSON →