A command is:

  • A set of instructions that is injected into the workspace machine for execution

  • A goal to organize commands for your workflow

  • A context to scope the command to particular projects

  • A preview URL to expose the URL of a running server

Commands are saved in the configuration storage of your workspace and are part of any workspace export operation.

Command goals

A developer executes a command to achieve a particular step in the development workflow. Che provides the ability to organize commands per goal:

  • Build: Commands that build the projects in a workspace.

  • Test: Commands related to test execution.

  • Run: Commands that run projects in a workspace.

  • Debug: Commands used to start a debugging session.

  • Deploy: Commands that are used to deploy projects in a workspace on specific servers or services.

  • Common: Commands used for general purpose.

Command context

The context of a command defines the projects that the command can be used with. For example: a maven build command is relevant only if the project uses Maven.

Managing commands

Workspace commands are available in the Commands Explorer view. This view is accessible from the left pane. The commands are organized in this view by goal.

command explorer

To create new commands, use the + icon next to a goal. Alternatively, you can select a command from the tree to edit, duplicate, or delete it.

command editor

The command editor is a distinct tab in the existing editor pane. Double-click the tab to use the full-screen edit mode. The editor can be split vertically or horizontally to display multiple editors at once.

  • Name: A unique command name in your workspace. The name is not restricted to CamelCase.

  • Intructions: To learn more about instructions and macros, see the Macros section.

  • Goal: Use the dropdown list to change the goal of the command.

  • Context: By default, the command is available with all the workspace projects. You can scope the command to be available only for selected projects.

  • Preview: To learn more about servers, see the Servers section.

Che provides macros that can be used within a command or preview URL to reference workspace objects. To learn more, see the Macros section.

Macros list

When editing a command, you can access all the macros that can be used in the command’s instructions or in the preview URL. To display a complete list of macros, click on the Macros link.

command macros list

Auto-completing macros

You can auto-complete all macros used in the editor. To activate the auto-complete feature, press Ctrl+Space. This displays a menu listing all the possible macros based on what is typed.

command macros autocompletion

Using commands

You can use commands from the following widgets:

  • Command Palette

  • Command toolbar

  • Contextual menu in the Project Explorer view

Using the Command Palette

Use the Shift+F10 keys to open the Command Palette. Use the arrow keys to navigate through the list of commands. Use Enter to execute a selected command.

command palette

Using the command toolbar

Using the command toolbar, you can execute the most common Run and Debug goals. The toolbar provides access to all the executed commands and previews.

command toolbar

Using the Run and Debug buttons

To trigger commands directly from the Run and Debug buttons, you must define the commands for the Run and Debug goals.

You are asked to choose the default command associated with a button when you use this button for the first time and this button has multiple commands defined for a goal. Consecutive clicks of this button trigger the previously selected command.

To select a command to execute from a goal, click and hold the button. This command becomes the default command associated with the button.

Using the command controller

Use the command controller to view the state of the workspace and the last command that was executed. You can see the time span since a command was started and decide if it should be stopped or relaunched.

To view the list of all the previously executed commands when multiple commands are executed, click on the widget.

command toolbar expanded

To clean the list, remove the process of the command from the list of processes.

command clean toolbar

Using the Preview button

For commands used to start servers, define the preview URL to access the running server. To learn more, see the Preview URLs section.

The Preview button provides quick access to all of fthe servers that are running in the machines of the workspace.

Authoring command instructions

A command may contain a single instruction or a succession of commands. For example:

cd /projects/spring				(1)
mvn clean install
1 Each command starts on a new line
cd /projects/spring; mvn clean install		(1)
1 A succession of several commands where ; stands for a new line
cd /projects/spring && mvn clean install	(1)
1 A succession of several commands where execution of a subsequent command depends on the execution of the preceeding one. If the /projects/spring directory is absent, the mvn clean install command is not executed.

To check for conditions, use loops and other bash syntax:

mvn -f ${current.project.path} clean install	(1)
  if [[ $? -eq 0 ]]; then
    cp /projects/kitchensink/target/*.war /home/user/wildfly-10.0.0.Beta2/standalone/deployments/ROOT.war
    echo "BUILD ARTIFACT SUCCESSFULLY DEPLOYED..."
else
    echo "FAILED TO DEPLOY NEW ARTIFACT DUE TO BUILD FAILURE..."
fi
1 Copy build artifact only if build is successful.

Macros

Che provides macros that can be used within a command or preview URL to reference workspace objects. Macros are translated into real values only when used in the IDE.

You cannot use macros in commands that are launched from the server side.

The following table lists the macros and their descriptions.

Macro Details

${current.project.path}

Absolute path to the project or module currently selected in the Project Explorer tree.

${current.project.eldest.parent.path}

Absolute path to a project root (for example, in the Maven-multi-module project).

${current.class.fqn}

The fully qualified package.class name of the Java class currently active in the editor panel.

${current.project.relpath}

The path to the currently selected project relative to /projects. Effectively removes the /projects path from any project reference.

${editor.current.file.name}

Currently selected file in the editor.

${editor.current.file.basename}

Currently selected file in the editor without extension.

${editor.current.file.path}

Absolute path to the selected file in the editor.

${editor.current.file.relpath}

Path relative to the /projects directory to the selected file in editor.

${editor.current.project.name}

Project name of the file currently selected in the editor.

${editor.current.project.type}

Project type of the file currently selected in the editor.

${explorer.current.file.name}

Currently selected file in the project tree.

${explorer.current.file.basename}

Currently selected file in the project tree without extension.

${explorer.current.file.path}

Absolute path to the selected file in the project tree.

${explorer.current.file.relpath}

Path relative to the /projects directory in the project tree.

${explorer.current.project.name}

Project name of the file currently selected in the explorer.

${java.main.class}

Path to the main class.

${machine.dev.hostname}

Current machine host name.

${project.java.classpath}

Project classpath.

${project.java.output.dir}

Path to the Java project output directory.

${project.java.sourcepath}

Path to the Java project source directory.

${explorer.current.project.type}

Project type of the file currently selected in the explorer.

${server.<serverName>}

Returns protocol, hostname, and port of an internal server. <port> is defined by the same internal port of the internal service that you have exposed in your workspace recipe.

  • Returns the hostname and port of a service or application you launch inside a machine.

  • The hostname resolves to the hostname or the IP address of the workspace machine. This name varies depending on where Docker is running and whether it is embedded within a VM.

  • The port returns the Docker ephemeral port that you can give to your external clients to connect to your internal service. Docker uses ephemeral port mapping to expose a range of ports that your clients may use to connect to your internal service. This port mapping is dynamic. In case of OpenShift, a route is returned.

Macro

Details

${workspace.name}

Returns the name of the workspace.

${workspace.namespace}

Workspace namespace (defaults to che in single-user Che).

Environment variables

The workspace machine has a set of system environment variables that have been exported. They are reachable from your command scripts using the bash syntax.

export					(1)

$TOMCAT_HOME/bin/catalina.sh run	(2)
1 List of all the available machine system environment variables.
2 Reference an environment variable, where $TOMCAT_HOME points to the /home/user/tomcat8 directory.