Development commands

By projects, we generally refer to the set of code and configuration required to build applications or libraries for XP. There are two main commands available to assist developers with setting up and managing projects:

Create

Simplified Enonic project creation with most values having reasonable defaults.

$ enonic create [project name]

Options:

Option Description

Option	Description
`project name`	project name. E.g. `myproject`
`-r, --repo, --repository`	repository path of the starter to base the project on. Format: <enonic repo> or <organisation>/<repo> on github or <full repo url>
`-s, --sandbox`	sandbox name to link project to
`--prod`	run Enonic XP distribution in non-development mode
`--skip-start`	If a new sandbox was created during project creation, do not start it
`-f, --force`	accept default answers to all prompts and run non-interactively

project name

project name. E.g. myproject

-r, --repo, --repository

repository path of the starter to base the project on. Format: <enonic repo> or <organisation>/<repo> on github or <full repo url>

-s, --sandbox

sandbox name to link project to

--prod

run Enonic XP distribution in non-development mode

--skip-start

If a new sandbox was created during project creation, do not start it

-f, --force

accept default answers to all prompts and run non-interactively

destination and version params for the new project will have default values equal to project name and 1.0.0-SNAPSHOT respectively

Example creating a project called 'foo' in a new folder with the same name ('foo'), with default version number ('1.0.0-SNAPSHOT'):

$ enonic create foo

Equivalent enonic project create command will be:

$ enonic project create foo -d foo -n foo -v 1.0.0-SHAPSHOT

The only values you will need to choose in the above example are a starter and a sandbox to link the new project to. If you need to automate this command completely for pipeline integration, you can use -f flag and specify a starter repo and an existing sandbox:

Example creating a project called 'foo' non-interactively in a new folder with the same name ('foo') using the Vanilla starter and existing sandbox called 'Sandbox1', with default version number ('1.0.0-SNAPSHOT'):

$ enonic create foo -f -r starter-vanilla -s Sandbox1

Dev

This command is essential for developers who want to work on their app in "hot reload" mode, which will "pick up" changes (both server- and client-side) made to the app’s source code without developer having to rebuild and redeploy the app. Make sure you execute this command from the project’s folder.

All the Enonic starters are coming with built-in support of the CLI’s dev command. This means that a project based on any of the Enonic starters will run smoothly in the dev mode. It will not work in your custom repository unless you implement the Gradle task called "dev" which runs your app in watch mode.

This command does two things:

Starts the project’s sandbox in detached dev mode. Detached means that logs from the XP instance running in the sandbox will not be output in the terminal window. Read the tip below if you need to combine the dev command with being able to see the XP logs.
Executes dev command for the app itself. This will deploy the app once (for XP to pick it up) and then read server-side source files directly from the app’s folder, also build client-side code if needed. In the Terminal window you’ll only see the output from this command.

If you need to see XP logs while working on the app, you will need to start the sandbox in a separate Terminal window/tab: enonic sandbox start, then run enonic dev in the first window/tab to start the project in dev mode.

Example starting a project in development mode from the project’s folder:

$ enonic dev

To terminate the dev mode, use Ctrl-C combination. If the sandbox was started in the detached mode in the same Terminal window/tab, CLI will attempt to stop the sandbox as well.

Project

Projects are commonly hosted in a Git repo and need to follow a set of principles to work with Enonic XP. Each project is associated with a sandbox to which it will be deployed.

All project commands should be run from the project root folder.

Command list is available by running following command:

$ enonic project

Manage Enonic projects

USAGE:
   enonic [command] [options] [arguments...]

COMMANDS:
     create             Create a new Enonic project
     sandbox, sbox, sb  Set the default sandbox associated with the current project
     clean              Clean current project
     build              Build current project
     deploy             Deploy current project to its sandbox
     install, i         Build current project and install it to Enonic XP
     shell              Create a new shell with project environment variables
     gradle             Run arbitrary gradle task in current project
     dev                Start current project in dev mode
     env                Export project environment variables as string to be used in any third-party shell

OPTIONS:
   --help, -h  show help

Create

Navigate to the folder you wish to place your project in and run the following command:

$ enonic project create [name] [-n <value>] [-b <value>] [-c <value>] [-d <value>] [-r <value>] [-v <value>] [-s <value>]

Follow wizard instructions that will set everything up for you.

Options:

Option Description

Option	Description
`name`	project name (e.g. `com.example.myapp`). Can also be specified using `--name` flag
`-n, --name`	project name. Overrides `[name]` argument if specified
`-r, --repo, --repository`	repository path of the starter to base the project on. Format: <enonic repo> or <organisation>/<repo> on github or <full repo url>
`-b, --branch`	repository branch to use. `master` is used if none specified
`-c, --checkout`	commit hash to use (mutually exclusive with branch option, used if both are present)
`-d, --dest, --destination`	destination folder name. Defaults to last word of the project name, i.e. `myapp`
`-v, --ver, --version`	version number to assign to new project. Default value `1.0.0-SNAPSHOT`
`-s, --sandbox`	sandbox name to link project to
`--prod`	run Enonic XP distribution in non-development mode
`--skip-start`	If a new sandbox was created during project creation, do not start it
`-f, --force`	accept default answers to all prompts and run non-interactively

name

project name (e.g. com.example.myapp). Can also be specified using --name flag

-n, --name

project name. Overrides [name] argument if specified

-r, --repo, --repository

repository path of the starter to base the project on. Format: <enonic repo> or <organisation>/<repo> on github or <full repo url>

-b, --branch

repository branch to use. master is used if none specified

-c, --checkout

commit hash to use (mutually exclusive with branch option, used if both are present)

-d, --dest, --destination

destination folder name. Defaults to last word of the project name, i.e. myapp

-v, --ver, --version

version number to assign to new project. Default value 1.0.0-SNAPSHOT

-s, --sandbox

sandbox name to link project to

--prod

run Enonic XP distribution in non-development mode

--skip-start

If a new sandbox was created during project creation, do not start it

-f, --force

accept default answers to all prompts and run non-interactively

name, repository, destination and version params are sufficient to create a project without a wizard allowing it to be used in script files.

Example creating 'myProject' project in 'myFolder' folder from vanilla starter and setting '1.0.0-SNAPSHOT' version:

$ enonic project create myProject -d myFolder -r starter-vanilla -v 1.0.0-SHAPSHOT

Same example but providing name as a flag:

$ enonic project create -n myProject -d myFolder -r starter-vanilla -v 1.0.0-SHAPSHOT

Sandbox

create command will link the project to a sandbox. To change it later, run this command inside the project folder:

$ enonic project sandbox [name]

Options:

Option Description

Option	Description
`name`	sandbox name
`-f, --force`	accept default answers to all prompts and run non-interactively

name

sandbox name

-f, --force

accept default answers to all prompts and run non-interactively

If name is not provided or does not exist, you will be asked for it.

Example setting 'myOtherBox' as default sandbox for current project:

$ enonic project sandbox myOtherBox

Build

You can build your project by running following command inside the project folder:

$ enonic project build

Options:

Option Description

Option	Description
`-f, --force`	accept default answers to all prompts and run non-interactively

-f, --force

accept default answers to all prompts and run non-interactively

Sandbox is not required when running with --force flag. In that case system wide java version will be used.

The build command helps you with:

Compiling code
Running tests
Creating artifacts (executables)

The build system is based on Gradle and the XP Gradle plugin.

The "project build" command is an alias for the Gradle Wrapper, which must be located in your project through a file called .gradlew (linux/mac) or gradlew.bat (windows). The Gradle Wrapper is by default available with all Starter Kits on Enonic Market.

You may also use the Gradle Wrapper directly by running ./gradlew build (linux/mac) or gradlew build (windows) from your projects directory.

Clean

Alias for the gradlew clean command

$ enonic project clean

Options:

Option Description

Option	Description
`-f, --force`	accept default answers to all prompts and run non-interactively

-f, --force

accept default answers to all prompts and run non-interactively

Sandbox is not required when running with --force flag. In that case system wide java version will be used.

Test

Alias for the gradlew test command

$ enonic project test

Options:

Option Description

Option	Description
`-f, --force`	accept default answers to all prompts and run non-interactively

-f, --force

accept default answers to all prompts and run non-interactively

Sandbox is not required when running with --force flag. In that case system wide java version will be used.

Deploy

As developers, we continuously need to deploy and test our code. Following command will build current project and deploy it to associated sandbox:

$ enonic project deploy [name]

Options:

Option Description

Option	Description
`name`	sandbox name to deploy to (overrides associated sandbox)
`--prod`	run Enonic XP distribution in non-development mode
`--debug`	run enonic XP server with debug enabled on port 5005
`-c, --continuous`	watch changes and deploy project continuously
`--skip-start`	Do not start the new sandbox after deployment
`-f, --force`	accept default answers to all prompts and run non-interactively

name

sandbox name to deploy to (overrides associated sandbox)

--prod

run Enonic XP distribution in non-development mode

--debug

run enonic XP server with debug enabled on port 5005

-c, --continuous

watch changes and deploy project continuously

--skip-start

Do not start the new sandbox after deployment

-f, --force

accept default answers to all prompts and run non-interactively

If the sandbox is already running, --prod and --debug parameters will be ignored. In this case you’ll have to make sure the sandbox is running in dev mode.

If sandbox name is provided, it overrides the sandbox associated with the project for this time only.

Sandbox is not required when running with --force flag. In that case system wide java version will be used.

Example deploying current project to 'otherSandbox' sandbox, starting XP in dev mode and continuously watching changes:

$ enonic project deploy otherSandbox -c

Install

To install current project to running enonic instance

$ enonic project install

Options:

Option Description

Option	Description
`-a, --auth`	Authentication token for basic authentication in the following format <user:password>
`-f, --force`	accept default answers to all prompts and run non-interactively

-a, --auth

Authentication token for basic authentication in the following format <user:password>

-f, --force

accept default answers to all prompts and run non-interactively

Enonic XP instance must be running when executing this command !

Install command does 2 things:

Builds the project
Installs built project to a running enonic XP instance using XP API

Options:

Option Description

Option	Description
`-a, --auth`	Authentication token for basic authentication in the following format <user:password>
`-f, --force`	accept default answers to all prompts and run non-interactively

-a, --auth

Authentication token for basic authentication in the following format <user:password>

-f, --force

accept default answers to all prompts and run non-interactively

if auth param is missing and there is no valid session CLI will look for ENONIC_CLI_REMOTE_USER and ENONIC_CLI_REMOTE_PASS environment variables. See configuration section.

Shell

This is an advanced command to export project JAVA_HOME and XP_HOME variables to a new shell. Following command starts a new shell bound to project sandbox and enonic XP distribution

$ enonic project shell

Run quit command to exit enonic shell. Parent shell environment is not modified.

Gradle

In case you want to run arbitrary gradle task or group multiple ones in one command you can use following command:

$ enonic project gradle [tasks / flags ...]

The text after gradle is sent directly to gradlew, without modifications.

Options:

Option Description

Option	Description
`tasks`	a space delimited list of gradle tasks and flags to invoke

tasks

a space delimited list of gradle tasks and flags to invoke

Flags like --force or --help are not supported by this command because it forwards all flags directly to gradle!

The difference between enonic project gradle clean build deploy and gradlew clean build deploy is that the former uses sandbox and Enonic XP distribution configured for the project, while the latter uses system-wide settings.

Example running gradle clean build deploy:

$ enonic project gradle clean build deploy

Dev

Same as the global dev command (see above)

Env

This command is currently not available on Windows.

If you are an expert user loving your shell you can export project JAVA_HOME and XP_HOME environment variables as strings to be used there

$ eval $(enonic project env)

Unlike enonic project shell command, this one will modify your current shell environment varialbes. Shell restart is needed to undo the changes.

Sandbox

Developers can use the CLI to work with one or several instances of XP locally. These instances are called sandboxes. Each sandbox will be associated with a specific distribution (version) of Enonic XP and will have its own Enonic XP home folder.

The CLI automates setting up, starting, stopping and upgrading sandboxes. When creating a new sandbox, user will be asked to select a template. Each template has a predefined list of applications serving a specific purpose, which will be automatically installed on the first sandbox launch, speeding up and simplifying the development startup process. Sandbox commands list is available by running following command:

$ enonic sandbox

Manage Enonic instances

USAGE:
   enonic sandbox [command] [command options] [arguments...]

COMMANDS:
     list, ls         List all sandboxes
     start            Start the sandbox.
     stop             Stop the sandbox started in detached mode.
     create           Create a new sandbox.
     delete, del, rm  Delete a sandbox
     upgrade, up      Upgrades the distribution version.
     copy, cp         Create a copy of a sandbox with all content.

OPTIONS:
   --help, -h  show help

Create

Starts a new sandbox wizard:

$ enonic sandbox create [name] [-v <value>] [-a]

Options:

Option Description

Option	Description
`name`	sandbox name
`-t, --template`	use specific template
`--skip-template`	skip template selection step
`-v, --version`	use specific distro version
`-a, --all`	include pre-releases when selecting XP version for the new sandbox
`--prod`	run Enonic XP distribution in non-development mode
`--skip-start`	Do not start the new sandbox after creation
`-f, --force`	accept default answers to all prompts and run non-interactively

name

sandbox name

-t, --template

use specific template

--skip-template

skip template selection step

-v, --version

use specific distro version

-a, --all

include pre-releases when selecting XP version for the new sandbox

--prod

run Enonic XP distribution in non-development mode

--skip-start

Do not start the new sandbox after creation

-f, --force

accept default answers to all prompts and run non-interactively

If all params are present and correct, sandbox is created immediately without wizard allowing usage in script files.

Example creating a sandbox called 'myBox' using the latest version of Enonic XP

$ enonic sandbox create myBox -f

Example creating a sandbox called 'myBox' using the latest version of Enonic XP and "Headless Demo" template

$ enonic sandbox create myBox -t "Headless Demo" -f

Example creating a sandbox called 'myBox' using the latest version of Enonic XP and without a template (no apps will be preinstalled)

$ enonic sandbox create myBox --skip-template -f

Example creating sandbox called 'myBox' using Enonic XP version 7.2.1

$ enonic sandbox create myBox -v 7.2.1

List

Lists all sandboxes previously created by user:

$ enonic sandbox list

Example output:

$ enonic sandbox ls

* Sandbox1 ( windows-sdk-7.2.1 )
  Sandbox2 ( windows-sdk-7.2.0 )
  Sandbox3 ( windows-sdk-7.0.3 )
  Sandbox4 ( windows-sdk-7.2.1 )

Asterisk marks currently running sandbox

Start

Starts a sandbox and ensures that only one is started at a time:

$ enonic sandbox start [name] [-d]

Options:

Option Description

Option	Description
`name`	sandbox name
`--prod`	run Enonic XP distribution in non-development mode
`--debug`	run enonic XP server with debug enabled on port 5005
`-d, --detach`	flag to start sandbox in detached mode (background process)
`--http.port`	set to the http port used by Enonic XP to check availability on startup (default: 8080)
`-f, --force`	accept default answers to all prompts and run non-interactively

name

sandbox name

--prod

run Enonic XP distribution in non-development mode

--debug

run enonic XP server with debug enabled on port 5005

-d, --detach

flag to start sandbox in detached mode (background process)

--http.port

set to the http port used by Enonic XP to check availability on startup (default: 8080)

-f, --force

accept default answers to all prompts and run non-interactively

Sandox is started in development mode by default. Use --prod flag to start it in non-development mode.

Example starting 'myBox' sandbox in a prod mode:

$ enonic sandbox start myBox --prod

Stop

Stops a running sandbox:

$ enonic sandbox stop

only sandboxes started with CLI can be stopped using this command.

Example stopping sandbox:

$ enonic sandbox stop

Upgrade

Upgrades enonic distribution used for a sandbox:

$ enonic sandbox upgrade [name] [-v <value>]

Options:

Option Description

Option	Description
`name`	sandbox name
`-v, --version`	enonic distribution version
`-a, --all`	List all distro versions
`-f, --force`	accept default answers to all prompts and run non-interactively

name

sandbox name

-v, --version

enonic distribution version

-a, --all

List all distro versions

-f, --force

accept default answers to all prompts and run non-interactively

Downgrades are not permitted.

Example upgrading enonic distribution for 'myBox' sandbox to 'windows-sdk-7.2.1':

$ enonic sandbox upgrade myBox -v 7.2.1

Delete

Deletes a sandbox:

$ enonic sandbox delete [name] [-f]

Options:

Option Description

Option	Description
`name`	sandbox name
`-f, --force`	accept default answers to all prompts and run non-interactively

name

sandbox name

-f, --force

accept default answers to all prompts and run non-interactively

All data that may have been created in this sandbox will be deleted.

Example deleting 'myBox' sandbox:

$ enonic sandbox delete myBox -f

Copy

Copies a sandbox with all content to a new sandbox:

$ enonic sandbox copy [source] [target] [-f]

Options:

Option Description

Option	Description
`source`	existing sandbox name
`target`	new sandbox name
`-f, --force`	accept default answers to all prompts and run non-interactively

source

existing sandbox name

target

new sandbox name

-f, --force

accept default answers to all prompts and run non-interactively

Example copying 'oldBox' sandbox to 'newBox' sandbox:

$ enonic sandbox copy oldBox newBox

Development commands

Contents

Create

Dev

Project

Create

Sandbox

Build

Clean

Test

Deploy

Install

Shell

Gradle

Dev

Env

Sandbox

Create

List

Start

Stop

Upgrade

Delete

Copy

Contents

Contents