This documentation is still in progress. We are working hard to update all our screenshots to the new Magnolia 6 style. Please bear with us.

Page tree
Skip to end of metadata
Go to start of metadata

Magnolia CLI is an npm package providing a command line interface (CLI) tool to set up and facilitate light development with Magnolia. This page describes how to install, set up, configure and use the commands in the version 2 branch. If you are using a Magnolia CLI version 3, see the page called Magnolia CLI v3 instead. 

To install Magnolia CLI, see the main Magnolia CLI page

The commands of the Magnolia CLI package facilitate the creation of a light module skeleton: the folders and files that form a typical Magnolia light module. We assume that you are already familiar with some Magnolia basics of creating light modulestemplates and dialogs

Configuration

Magnolia CLI is configured in these files/folders:

Files

mgnl‑cli‑prototypes/A folder which contains the prototypes for template and dialog definitions and the README file. For further details see prototypes.
mgnl‑cli.json

The configuration file defining the folders of the light module skeleton and some other things.

When a CLI command is executed, the system searches for the JSON configuration. 

Do not modify the package.json of your global installation, consider creating one local package.json for each project instead.

Global and local configurations

  • Use the -h option to show the location of the configuration files corresponding to the location where you run the command. Using this option also shows the general help text. The command itself is not executed.
  • You can use the placeholder variables __name__ and __lightDevModuleFolder__ in all prototypes files for page and component templates (in mgnl-cli-prototypes/page/* and mgnl-cli-prototypes/component). 

Global

The global configuration is created during the global installation of the Magnolia CLI package. On Linux or OS-X the global configuration files are typically located in the /usr/local/lib/node_modules/@magnolia/cli folder.

The CLI commands use the global configuration if no local configuration is found in the current directory or in its parent folders.

Local

For different projects you can create various local configurations with the  customize-local-config  command. This command creates local configuration files in the /wherever/you-have/executed/the-customize-local-config-command folder.

The local configuration is created as a copy of the current configuration (used during execution of the customize-local-config command), which you can edit to define project specific prototypes or dependencies.

When executing commands from within the local configuration folders or subfolders, the local configuration is used.

You cannot mix global and local configurations. When adding a local configuration it must be complete: it must contain the mgnl-cli.json file and the complete mgnl-cli-prototypes folder.

If Magnolia CLI finds the mgnl-cli.json file in the current or a parent directory, it expects to find the complete mgnl-cli-prototypes as well.

mgnl-cli.json

This JSON file contains basic configurations which are used when running the Magnolia CLI commands. Here is a partial list of the properties which you might want to edit:

PropertyMeaningUsed by
downloadUrl

The URL used to download the bundle.

We do not recommend editing this property.

command jumpstart
downloadJars

A map of artifacts to be added to the WEB-INF/lib directory.

command jumpstart
tomcatFolderThe name of the folder where the Magnolia bundled with Tomcat is installed during the execution of the jumpstart command.command jumpstart

magnoliaAuthor,

magnoliaPublic

If set these properties override the same properties in the magnolia.properties file by overwriting them there.

Note that you cannot set the magnolia.resources.dir property since Magnolia CLI overrides it.

The properties are used to update the magnolia.properties files (on both public and author) when executing the jumpstart command.

command jumpstart
lightDevFoldersInModuleThe folders which are created for a light module.command create-light-module
 Click here to expand to see the source of mgnl-cli.json

mgnl-cli.json
 {
  "setupMagnolia": {
    "downloadUrl": "https://nexus.magnolia-cms.com/service/local/artifact/maven/content?r=magnolia.public.releases&g=info.magnolia.bundle&a=magnolia-community-demo-bundle&c=tomcat-bundle&e=zip&v=${magnoliaVersion}",
    "tomcatFolder": "apache-tomcat",
    "webapps": {
      "magnoliaAuthor": {
        "magnolia.develop": true,
        "magnolia.update.auto": true
      },
      "magnoliaPublic": {
        "magnolia.update.auto": true
      }
    },
    "downloadJars": {}
  },
  "lightDevFoldersInModule": {
    "dialogs_components": "/dialogs/components",
    "dialogs_pages": "/dialogs/pages",
    "templates_components": "/templates/components",
    "templates_pages": "/templates/pages",
    "webresources": "webresources",
    "decorations": "decorations",
    "i18n": "i18n"
  }
}

This version of mgnl.json may not include all parameters described below.


Prototypes

When executing either the create-page or the create-component command, new files are created from the prototype files. These prototype files are located in the  mgnl-cli-prototypes  folder. 

<configuration>/mgnl-cli-prototypes/
├── README.md.tpl
├── component
│   ├── definition.yaml
│   ├── dialog.yaml
│   └── template.ftl
└── page
    ├── definition.yaml
    ├── dialog.yaml
    └── template.ftl

Commands

Universally available Magnolia CLI command options

OptionDescription
-h

Shows all the parameters and optional parameters (options) available for a command. When you execute a command with just the -h option, the command itself is not executed.

For example the command mgnl create-light-module -h will not create a light module structure in the current direcory.

-V

Shows version information. When you execute a command with just this option, the command itself is not executed (same as entering mgnl -V).

An example output of the mgnl create-light-module -V command:

2.2.0

add-availability

This command makes a component available to a page by:

  • Adding or updating the page template definition to enable the component for an area.
  • Adding the cms:area directive to the template script (if it is not already there).

The command only succeeds if the current directory (or the directory defined by the -p <path> parameter) is a light module with a minimal folder structure and if the page specified by the second argument exists.

Usage

mgnl add-availability  <[module-id:]path-to-component>  <path-to-page[@area]> [options]

Parameters

Short formDescription
<[module‑id:]path‑to‑component>

required

The component you want to make available.

Must at least contain the path to a component.

Can optionally start with the module identifier [module‑id:] . If the module identifier is not used, Magnolia CLI assumes the component belongs to the current light module or to the light module specified by the -p <path> option.

Magnolia CLI does not check the existence of the specified component.

<path‑to‑page[@area]>

required

The page you want to make the component available to.

The parameter starts with the path to the page template within the templates directory and it must end with an area name [@area] . If the area does not exist yet, the command adds an area to both the template script and the template definition.

If no area is specified, the command defaults to main area (if it exists) or creates main area (if it does not).

Options

Short formLong formDescription
-p <path>--path <path>

optional

The path to the light module that contains the page template.

If no path is specified, the command must be run in an existing light module folder.

-g
Add this parameter to autogenerate the component instead of providing plain availability.

Examples

This example makes a component from the mtk module available to the page named my-page in the area named main:

mgnl add-availability mtk:components/textImage pages/my-page@main
This example makes the component my-component available to the page my-page. Both the component and the page are part of the light module located at /Users/jdoe/dev/mgnl/light-modules/my-module/:
mgnl add-availability components/my-component pages/my-page@main -p /Users/jdoe/dev/mgnl/light-modules/my-module/

create-component

This command creates a new component template including:

  • A template definition YAML file.
  • A freemarker template script.
  • A YAML dialog definition file. 

Optionally, the component can be made available to a page using the -a option (internally calling the  add-availability  command).

The command succeeds only if the current directory (or the directory defined by the -p option) is a light module with a minimal folder structure.

The files which are created while executing this command are based on the files in the prototypes folder of your configuration. The files contain some standard code with some commonly used properties. This is generally a good starting point to build a component template.

Usage

mgnl create-component <name> [options]

Parameters

ParameterDescription
<name>

required

The name of the new component template. The name cannot contain spaces.

Options

Short formLong formDescription
-p <path>--path <path>

optional

The path to the light module you want to add the component template to.

If no path is specified, the command must be run within an existing light module folder.

-a <path‑to‑page[@area]>

optional

The page you want to make the component available to. When you specify this option, add-availability is called after the creation of component to make it available in a page area.

The parameter must start with the path to the page template within the templates directory and it must end with an area name. If the area does not exist yet, the command adds an area to both the template script and the template definition. If no area is specified, the command defaults to main area (if it exists) or creates main area (if it does not).

-g  <path‑to‑page[@area]>

optional

Add this parameter to autogenerate the component instead of providing plain availability. As for the -a option the target area and page must be specified.

Example

mgnl create-component my-component -a pages/my-page@footer -p /Users/johndoe/dev/mgnl/light-modules/my-module/

create-light-module

This command creates a new light module in the form of a set of empty light module folders and the following two files:

  • README.md , in the root folder of the module.
  • <moduleName>-messages_en.properties, in the i18n folder this command creates.

The name of the light module should be provided as a parameter when calling the command. The light module is created in the current directory or in the directory specified with the optional -p <path> parameter.

Usage

mgnl create-light-module [<moduleName>] [options]

Parameters

ParameterDescription
<moduleName>

optional (but recommended)

The name of the new light module.

Avoid spaces and special characters since this name is used as folder name.

If no <moduleName> is specified, the name of the current directory is used as the module's name. This can be useful when the folder for the light module already exists.

Options

Short formLong formDescription
-p <path> --path <path>

optional

The path of the parent directory for the new light module. If no path is specified, the new light module is created within the current folder.

Examples

mgnl create-light-module my-module
mgnl create-light-module my-module -p ../../light-modules/
 Expand to see the created directory tree

my-module/
├── README.md
├── decorations
├── dialogs
│   ├── components
│   └── pages
├── i18n
│   └── my-module-messages_en.properties
├── templates
│   ├── components
│   └── pages
└── webresources


create-page

This command creates a new page template including:

  • A template definition YAML file.
  • A freemarker template script.
  • A YAML dialog definition file. 

The command succeeds only if the current directory (or the directory defined by the optional  -p <path> parameter) is a light module with a minimal folder structure. The files which are created when executing this command are built from the files in the prototypes  folder of your configuration. The files contain some standard code with some commonly used properties. This is generally a good starting point to build a page template.

Usage

mgnl create-page <templateName> [options]

Parameters

ParameterDescription
<templateName>

required

The name of the new page template. The template name cannot contain spaces.

Options

Short formLong formDescription
-p <path> --path <path>

optional

The path to the light module to add the new template to.

If no path is specified, the command must be run within an existing light module folder.

Example

mgnl create-page my-page

If you do not use the -p <path> parameter, you must run the command from an existing light module folder.

 Expand to see the output of the command in the shell

INFO: No path option provided, page template will be created in the current folder.
DONE: Page template created
INFO: /Users/jdoe/dev/mgnl/light-modules/my-module/templates/pages/my-page.yaml created
INFO: /Users/jdoe/dev/mgnl/light-modules/my-module/templates/pages/my-page.ftl created
INFO: /Users/jdoe/dev/mgnl/light-modules/my-module/dialogs/pages/my-page.yaml created

customize-local-config

Run this command to create a local configuration. It installs the files for the local configuration within the current directory, or within the directory defined by the optional -p <path> parameter.

Usage

mgnl customize-local-config [options]

Options

Short formLong formDescription
-p <path>--path <path>

optional

The path into which the mgnl-cli-prototypes folder and mgnl-cli.json file are installed.

Example

mgnl customize-local-config -p ~/dev/mgnl/light-modules/

help

Run the help command to list all the available commands of the Magnolia CLI package.

Usage

mgnl help [options]

Options

OptionDescription
<command>

optional

Shows basic help for the Magnolia CLI command specified as the option.

Without the option, a list of available CLI commands are displayed (same as entering mgnl -h).

install


Downloads and installs one or more light modules from npm to the light module directory.

Usage

mgnl install <light-module-name> [options]

Parameters

ParameterDescription
<light-module-name>

required

At least one name of a light module to be downloaded from npm. If installing more than one module from the repository, separate the module names with a space.

Options

Short formLong formDescription
-p <path>--path <path>

optional

The path to the light-modules folder.

If no path is specified, mgnl searches for the nearest apache-tomcat* folder and checks the value of the magnolia.resources.dir property as defined in the webapps of the folder.

Example

mgnl install google-maps-magnolia mgnl-bobby -p /Users/johndoe/dev/mgnl/light-modules/other-users-modules/

jumpstart

This command downloads, unpacks and pre-configures a Magnolia Tomcat bundle.  It creates folders for the Tomcat server and for the light modules according to the configuration

By default the command downloads the latest released version of the magnolia-community-demo-bundle. Use the -e  parameter to get the EE Pro demo bundle (magnolia-enterprise-pro-demo-bundle) instead. These bundles contain the Magnolia Travel Demo. Chose a specific version by providing the -m parameter.

The jumpstart command installs the bundle within the current directory.

You may remove the magnolia.zip file once the installation is complete.

Usage

mgnl jumpstart [options]

Options

Short formLong formDescription
-p <path>--path <path>

optional

The -p option for the jumpstart command specifies the path to the light modules root folder which is observed for changes, not to an alternative location for the bundle to be installed.

The path to the light modules root folder is set by the magnolia.resources.dir  property in the magnolia.properties file of the installed Magnolia bundle.

If no path is provided:

  • A default folder named light-modules is created in the current folder.
  • Light modules are then created under this folder which is observed by Magnolia for changes.
  • The property is set to the following relative path: magnolia.resources.dir=${magnolia.home}/../../../light-modules
-m <version>

--magnolia-version <version>

optional

The desired version of the Magnolia bundle. If not provided, defaults to the latest version of the chosen bundle (magnolia-community-demo-bundle or magnolia-enterprise-pro-demo-bundle).

-i <name>

--install-sample-module <name>

optional

If provided, a sample light module under the light modules root folder with the given name is created.

-e


optional (since 1.0.5)

Downloads a magnolia-enterprise-pro-demo-bundle. Requires enterprise credentials to Magnolia Nexus.

-c

optional (since 2.2.0)

Downloads a Magnolia Cloud bundle. Requires enterprise credentials to Magnolia Nexus.

Example

mgnl jumpstart -e -m 5.4.5

When running the jumpstart command, make sure that a magnolia.zip file does not already exist in the directory in which you are running the command. The zip file prevents the command from downloading another version and simply installs from the existing file.

See NPMCLI-100 - Getting issue details... STATUS


Searches for Magnolia-related packages available from npm and returns their list together with the following information:

  • Package name.
  • Date and version of the latest commit.
  • Brief description of the package.
  • Contributor's username.

Usage

mgnl search [options]

Options

OptionDescription
<query>

optional

The search query sent to the npm's API (see https://api-docs.npms.io).

The query can contain multiple terms separated with commas and no spaces. When no query is provided, returns a list of all light modules.

Example

mgnl search language-switcherinfo 1 result foundinfo info 1) language-switcher-magnoliainfo     2017-02-25 1.0.5info     Language Switcher - Component template for Magnolia CMSinfo     magnolia

start

This command starts up Magnolia and displays the main log file (apache-tomcat/logs/catalina.out). Magnolia CLI looks in the current working directory or parent directories for the nearest folder with a name that starts with "apache-tomcat". To stop Magnolia, simply use CTRL+C. 

Usage

mgnl start [options]

Options

Short formLong formDescription
-p <path>--path <path>

optional

The path to the apache-tomcat folder. If no path is specified, Magnolia CLI looks in the current working directory or in the parent directories for the nearest folder with a name that starts with "apache-tomcat".

-d

optional

Does NOT ignore the open files limit check. The files limit check is ignored by default. See Too many open files for more.

Example 

mgnl start -p C:/magnolia-installations/magnolia-5.5.1/apache-tomcat-8.5.5

tab-completion

Run the command to install or uninstall autocompletion for Magnolia CLI commands. 

Usage

mgnl tab-completion <command>

Parameters

ParameterDescription
installInstalls the required files for autocompletion.
uninstallRemoves the files which were previously installed during installation.

Examples

mgnl tab-completion install
A successful installation displays a list of files to which the tab-completion script has been appended.

See also

  • No labels