Tutorial 12: Setup CLI and Local Workspace

Owned by PIPEFORCE
Last updated: Dec 03, 2024
5 min read

Introduction

This tutorial is targeting

Low-Code Developers who wants to learn creating and publishing resources like apps, workflows, forms, lists or pipelines in your low-code workspace.

What you will learn

In this Tutorial we provide a command line tool which simplifies these steps a lot. In this tutorial, we will setup the CLI and local workspace.

Step 1: Install Java

Open your terminal and verify that you have a Java runtime version >= 17 installed:

$> java -version

You should see an output similar to this:

java version "17"

If there is a version number 17 or higher shown, then you have installed “Java 17” or higher.

In case you see an output like “command not found”, then you probably have no Java environment installed yet. So, go to the next step and download and install the environment.

If you have not installed Java runtime yet, follow these steps to download and install:

  1. Go to https://www.java.com/de/download/, and download the latest Java runtime.

  2. Install the downloaded package.

  3. Open a new console window, and try out that this command to show the installed Java version:

$> java -version

  1. Now, the Java version 17 (or higher) should be shown. You’re done.

  2. If it is not shown, make sure the java command was added to your path variable. See the Java documentation how to do that.

Step 2: Install PIPEFORCE CLI

After you have made sure that Java is installed and is running correctly on your local machine, you can download the latest version of the cli tool here.

Select the pipeforce-cli.jar and download it to your computer.

After this, open a new terminal / command line window and move to the folder where you downloaded the file. Usually, this is the Download folder (as shown in this example for Mac and could differ for your operating system):

Now, install the cli tool by executing this command in your terminal:

A setup wizard will be started automatically with these questions:

Type in your customer namespace, and press enter. This is the prefix name of your instance when you open it in your web browser. For example:

You got this link with your trial or production instance. If unsure, ask your admin for your namespace.

Type in your PIPEFORCE username, and press enter.

Type in your PIPEFORCE password, and press enter.

Done.

Finally, the PIPEFORCE CLI tool was successfully installed to your home folder $USER_HOME/pipeforce, and you can start creating your automation apps. To do so, see the next steps in this guide.

We highly recommend to add the folder $USER_HOME/pipeforce/pipeforce-cli/bin to the path variables of your operating system. See the documentation for your operating system how to do this.

Tip: In case you're an advanced developer or you would like to change the default connection settings on setup, use this command instead:

This will start the setup wizard with advanced settings.

Step 3: Create a PIPEFORCE workspace

In order to start development of your automation ap, you have to create a PIPEFORCE workspace first. Such a workspace is a source repository where all of your development resources and settings for particular PIPEFORCE apps reside. This folder can then be synced with the server.

In order to create such a workspace, follow these steps:

At first create a new, empty folder, for example under this path:

Initialize this folder by calling the init command inside:

This creates the necessary files and folder structure.

Finally, you can open the files in your preferred editor. Or you can install and use Visual Studio Code using these commands, or by double clicking the PIPEFORCE.code-workspace to open the workspace:

At the left, you can see the src folder from your repository (your setup might look a bit different, depending on the CLI version and project setup you’re using).

Step 4: Install Visual Studio Code (optional)

This step is optional but highly recommended.

The VS Code editor will be used to edit configurations for your workflow apps. You can download and install it for free from here:

https://code.visualstudio.com/download

Check encoding

Regardless which editor you’re using, it is very important to make sure the editor handles all files with UTF-8 encoding, which is the default for Visual Studio Code. You can check this here: Preferences → Settings → file.encoding.

Install YAML editor plugin​

Since we will create and edit a lot of configuration files in the YAML format, we recommend you to install the YAML editor plugin in VS Code. With this, you will get YAML editor with text completion as shown here:

To do so, after you have installed VS Code, open this link in your browser, and click on “Install”:

https://marketplace.visualstudio.com/items?itemName=redhat.vscode-yaml

As an alternative, you can go to Preferences → Extensions in VS Code, and then search for YAML. Then, click install on the plugin found:

Step 5: Create GitHub repository (optional)

In order to put the repository under source control, it is best practice to create a Git repository with same name and push all your changes there.

  1. Create a new repository online. For example with name my-workspace in GitHub.

  2. If you are using GitHub, execute these commands in order to push your PIPEFORCE workspace: