README.md

Magnolia CLI

Magnolia CLI version 5 is a plugin-based system.

The purpose of this architecture is to offer developers enhanced flexibility, control, customization of commands, and definition of their own project templates.

Installation

You can install the CLI manually or by using a Jumpstart Plugin, which will prompt you to choose a project template and automatically installs the CLI at project level and sets up the required files (package.json and mgnl.config.js) for you.

Using Jumpstart Plugin

1. Run the Jumpstart Plugin:

   npx @magnolia/cli jumpstart

Manually

While both global and local installations of Magnolia CLI are possible, it is recommended to install the CLI locally at the project level. Which allows each project to maintain its unique configuration within a mgnl.config.js file and to have separate plugins per project.

Local installation

1. Install the Magnolia CLI:

   npm install @magnolia/cli

2. Add the following script to package.json:

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

   so you can use following command:

   npm run mgnl

   or you can run it directly with node:

   node node_modules/@magnolia/cli

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

   {
     "type": "module"
   }

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

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

Global installation

1. Install the Magnolia CLI:

   sudo npm install @magnolia/cli -g 

Installing a plugin

For a list of available plugins, please refer to CLI Documentation

Using add-plugin

The add-plugin command is a included in the CLI. This plugin automates the installation and configuration of new plugins within the mgnl.config.js file.

1. In initialized project run:

   npm run mgnl -- add-plugin <plugin> [<pluginArgs>]

Replace <plugin> with one of the following options based on your source:

• npm package name
• tarball
• folder
• HTTP URL
• git URL

References for further details:

• npm install documentation
• yarn add documentation

Optionally, the <pluginArgs> argument allows you to pass an object (JSON) that the plugin constructor will receive during initialization.

The command installs the new plugin by executing npm install <plugin> or yarn add <plugin>. After, it identifies the appropriate plugin's class name and writes it into the mgnl.config.js file for you.

Manually

In the project folder install the package with desired package manager.

npm install <plugin>

Then register the plugin in mgnl.config.js:

import <PluginClass> from <plugin>

export default {
  plugins: [
    new <PluginClass>()
  ] 
}

Observe that the plugin was successfully registered under "Commands" in help:

npm run mgnl -- --help

Running a Plugin

To start a plugin in the context of the CLI, you can run the mgnl script with the plugin name and its options. Here's an example:

npm run mgnl -- <plugin-name> -<plugin-option> <option-value>

NOTE: By default, npm outputs additional information about the script. If you prefer to suppress this output, you can add the --silent (or -s) flag when running the script:

npm run -s mgnl -- <plugin-name> -<plugin-option> <option-value>

Analytics Collection

To help us improve our services, we collect the following information:

• OS Architecture: The architecture of your operating system (e.g., x64, arm64).
• OS Version: The version of your operating system.
• OS Name: The name of your operating system.
• UUID: A unique identifier for analytics purposes.
• Node Version: The version of Node.js you are using.
• CLI Version: The version of the @magnolia/cli package you are using.
• Command: The name and version of the plugin command being executed.

We use this data to enhance your experience by understanding how the CLI and plugins are being used. All collected data are anonymous and not tied to any individual. No personal information is collected.

If you prefer to opt out, you can disable analytics by setting 'analytics.enabled' to 'false' in the mgnl.config.js file.

CLI Documentation

For detailed documentation of the CLI, please refer to CLI Documentation

Magnolia CMS

This CLI is created to work with Magnolia CMS. For more information, please refer to Magnolia CMS Documentation