Magnolia CLI v5

This page describes the Magnolia CLI v5, its core components, and how to install it.

Plugin-based CLI

Magnolia CLI in version v5 is a plugin-based system. The purpose of this architecture is to offer developers enhanced flexibility, control, customization of commands by creating a plugin, and definition of their own project templates.

  • The CLI itself provides the core functionality and oversees the operation of the plugins. It uses a configuration file called mgnl.config.js, where you can configure the logger and the plugins.

  • The plugins specified in this file are loaded by the CLI. To meet the requirements of your project, you can modify the file to use it with your own plugin collection.

Available plugins

For a list of all plugins, see the Plugins.

Pre-installed plugins

Several of the plugins are pre-installed:

The add-plugin

The CLI also comes with the add-plugin command, which installs and registers a new plugin within your project.

Rather than a plugin, it’s more appropriate to view the add-plugin as a command, because it’s always available, even if a local mgnl.config.js exists.

Installing CLI

Prerequisites

Node.js

The Magnolia CLI tool requires Node.js. To check the version of your node.js installation, run the following command in a shell:

node -v

Node.js provides two branches, LTS (recommended for long-term support) and Current (providing the latest features).

Make sure you are running the latest version of the LTS branch. You can get it from Node.js downloads. It may also be installed via package managers.

Java

Java is only required if you want to use the Start plugin, which starts Magnolia.

For Java installation details, see Get Java.

Installing

We recommend you use the Jumpstart plugin or install the Magnolia CLI locally at project level. This approach allows each project to:

  • maintain its unique configuration within the mgnl.config.js file,

  • have separate plugins per project, and

  • to manage different versions of the CLI and the plugins more effectively.

Through the jumpstart plugin

This following command prompts you to choose a project template, automatically installs the CLI locally at the project level, and sets up the required files (package.json and mgnl.config.js) for you.

npx @magnolia/cli@latest jumpstart

Locally

To install the latest production version locally at the project level, do the following:

  1. Initialize the project if it’s not already set up:

    npm init -y

  2. Install the Magnolia CLI package:

    npm install @magnolia/cli

  3. Add the following script to package.json:

    {
  ...
  "scripts": {
    ...
    "mgnl": "node node_modules/@magnolia/cli"
  }
}

  4. In package.json, set the type property to module:

    {
  ...
  "type": "module"
}

  5. Create the mgnl.config.js file, where you can configure your plugins:

    export default {
  plugins: [],
  logger: {
    filename: "./mgnl.error.log",
    fileLevel: "warn",
    consoleLevel: "debug"
  }
};

Globally

To install the latest production version globally, run the following command:

sudo npm install @magnolia/cli -g (1)
1 The sudo part of the command may be required on Linux or macOS, depending on your permissions and the Node.js installation location.

Which versions are available?

To display a list of released versions of Magnolia CLI, enter the following command in a shell:

npm view @magnolia/cli versions

Besides a version list, the following command shows additional information about the Magnolia CLI package:

npm view @magnolia/cli

Testing the installation

To verify that the CLI has been successfully installed and to learn what it offers, use the following flags based on the type of installation.

Locally

Prerequisite configuration

The CLI is installed in the project folder and the following is in the package.json file:

{
  "scripts": {
    "mgnl": "node node_modules/@magnolia/cli"
  }
}
Help
npm run mgnl -- -h

Windows users using PowerShell must enclose the two consecutive hyphens (--) in quotes:

npm run mgnl "--" ...
Version
npm run mgnl -- -V

Windows users using PowerShell must enclose the two consecutive hyphens (--) in quotes:

npm run mgnl "--" ...

Globally

Help
mgnl -h
Version
mgnl -V

Updating

Locally

To update the CLI installed locally, run the following npm command in your project directory.

npm update @magnolia/cli

Globally

To update the CLI installed globally, run the following npm command:

sudo npm update @magnolia/cli -g (1)
1 The sudo part of the command may be required on Linux or macOS, depending on your permissions and the Node.js installation location.

Migrating from v4 to v5

This section describes how to migrate an existing project from Magnolia CLI v4 to CLI v5. The procedure applies to all v4 projects, regardless of their rendering type.

A key change is that CLI v5 is installed at the project level instead of being installed globally. This makes the CLI more modular. Each project can have its own specific CLI version and configuration.

Migration steps

  1. Initializing package.json in the project root.

    Navigate to the project root and create the package.json file if it doesn’t exist there yet. Use the following command to initialize the file and automatically set "type": "module":

    npm init -y && sed -i '' 's/^{/{\n  "type": "module",/' package.json

    The command initializes the project with default values, adds "type": "module" to the package.json file, and ensures compatibility with the ES module syntax in NodeJS.

    You may need to add "type": "module" to the package.json file manually if the npm init -y command doesn’t work as expected.

  2. Installing CLI v5 locally.

    Install Magnolia CLI v5 at the project level:

    npm install @magnolia/cli

    This installs CLI v5 into the project’s node_modules directory.

  3. Adding a start script.

    To simplify running the CLI, add the mgnl script to package.json. The script allows you to execute the CLI with just npm run mgnl:

    "scripts": {
  "mgnl": "node node_modules/@magnolia/cli"
}

  4. Creating the configuration file.

    CLI v5 requires a configuration file (called mgnl.config.js) in the project root. Create this file manually or use:

    touch mgnl.config.js

    Then, add the following content for basic logging and plugin configuration:

    export default {
  logger: {
    filename: "./mgnl.error.log",
    fileLevel: "debug",
    consoleLevel: "info"
  },
  plugins: []
};

  5. Running the CLI.

    With everything set up, run the CLI using:

    npm run mgnl

Adding plugins

To expand CLI’s capabilities, see the available plugins and add them as needed.

Example:

npm run mgnl -- add-plugin @magnolia/cli-start-plugin

Windows users using PowerShell must enclose the two consecutive hyphens (--) in quotes:

npm run mgnl "--" ...

This command adds the Start plugin to your CLI setup, making the npm run mgnl -- start command available for starting up the local Magnolia instance.

To list all registered commands, execute:

npm run mgnl

You’re now ready to use Magnolia CLI v5 locally in your project!

Feedback

DX Core

×

Location

This widget lets you know where you are on the docs site.

You are currently perusing through the Magnolia CLI docs.

Main doc sections

DX Core Headless PaaS Legacy Cloud Incubator modules