What is the Command Line Interface (CLI)?

The Command Line Interface (short “CLI” or “pi tool”) is a local command-line tool, which allows remote control and development of PIPEFORCE from your local terminal.

It makes it handy to do for example:

• Manage the PIPEFORCE Cloud remotely

• Connect On Premises systems with PIPEFORCE Cloud

• Easily excecute single cloud commands or pipelines on the terminal

• Develop integrations, apps, workflows and reports from within your preferred IDE

• Run and monitor tests

• Automate and execute business workflows

See the Downloads section on how to install this tool.

The tutorial Setup local workspace + CLI shows, how to install and work with the CLI.

Usage​

The main structure of a CLI command is always like this:

pi <action> <args>

To get a list of all supported actions and their parameters, use the help command:

pi help

Below, you can find the description of the most important actions.

pi command​

This executes a single pipeline command at the server-side and returns the result.

Each parameter will become a command-line parameter.

Example 1:

pi command log message=HELLO

This executes the log command at server-side with the parameter message set to HELLO.

Example 2:

pi command mail.send to=my@email.tld subject=Hello message="This is a test"

This command sends an email.

Or use the command pi help command COMMAND_NAME to get the documentation for a specific command.

pi delete​

This deletes the remote resources inside a given app. It doesn’t delete any local resource.

Example 1:

pi delete global/app/myapp/pipeline/helloworld

This deletes the pipeline helloworld.

Example 2:

pi delete global/app/myapp/**

This deletes all resources of the app myapp.

pi get​

This downloads all resources of a given app, stores them into the local workspace in order to be able to edit them. If a local resource already exists, this asks for either to overwrite or to skip.

Example 1:

pi get global/app/myapp/**

This command-line call downloads all resources of the app myapp and its sub-folders, and stores them into the local workspace folder properties/global/app/myapp. Note, that you have to define the property key here, not the local file path.

Example 2:

This downloads only the resources inside the myapp folder, but no resource from inside its sub-folders.

pi get global/app/myapp/*

Example 3:

This downloads a single resource by its key:

pi get global/app/myapp/pipeline/hello

pi init​

This command initializes a given folder as a PIPEFORCE workspace folder. It creates all necessary folder structure and configuration files in order to start development of new PIPEFORCE apps inside it. Such a workspace folder can contain one or more apps to be published to PIPEFORCE. It's also good practise to commit the whole workspace folder as single repo to GitHub (or your preferred source code management system).

Example:

pi init

This will create a file and folder structure like this:

• .pipeforce

  • config.json

• properties

  • global

    • app

• PIPEFORCE.code-workspace

The file config.json will contain all required settings for this workspace. Feel free adjust to your needs.

The folder properties is the default home folder for all properties which will be deployed to PIPEFORCE using the command pi publish. The structure inside this folder must correspond with the structure in the property store, you would like to deploy.

The file PIPEFORCE.code-workspace is the default workspace configuration for Visual Studio Code. Feel free to delete it in case you're using a different development environment.

pi help​

This lists all available CLI options or pipeline commands.

Example 1:

pi help

This lists all available command-line options.

Example 2:

pi help command

This lists the documentation of all available pipeline commands for the currently logged-in user.

Example 2:

pi help command log

This explains the log pipeline command. The output could look like this:

log:
  type: "object"
  description: "Logs the given input message without changing it. Sets the log message\
    \ in the body in case body is empty. Doesn't overwrite any existing content in\
    \ the body."
  inputType: "JsonNode"
  outputType: "JsonNode"
  properties:
    message:
      type: "number"
      description: "The message to log. Can be a string or a pipe expression. If null\
        \ or empty, the full pipe message will be logged."
      default: null
    level:
      type: "string"
      description: "The log level. Can be one of DEBUG, TRACE, INFO, WARN, ERROR.\
        \ If null or empty, INFO will be used."
      default: "INFO"
  required:
  - "message"

pi list​

This lists all remote resources of a given path.

Example 1:

pi list global/app/myapp**

This lists all resources of the app myapp recursively.

Example 2:

pi list global/app/myapp/*

This lists all resources of the folder myapp, but not the resources inside any sub-folder.

pi new​

This creates a new resource based on a wizard.

Example 1:

pi new

This would print this wizard:

Create new...
  0: app
  1: form
  2: list
  3: object
  4: pipeline
  5: workflow
Choose number : 

Example 2:

You can also directly start the resource wizard by the command:

pi new app

Example 3:

And if you are inside a app folder, the app you want to create the resource for, is already pre-selected for you.

~ pipeforce> cd properties/global/app/myapp
~ app/myapp> pi new pipeline

pi pipeline​

This executes a a locally stored pipeline file, a remote pipeline or a pipeline uri. Which type of pipeline is detected by the pipeline argument:

• Starts with properties/ (or the name configured as propertiesHome in ./pipeforce/config.json): It's assumed to be a local pipeline file.

• Starts with global/: It's assumed to be a persisted remote pipeline.

• None of the above: It's assumed to be a pipeline uri.

Example 1:

pi pipeline properties/global/app/myapp/pipeline/helloworld.pi.yaml

This example uploads the content of the helloworld.pi.yaml to the server, executes it there, and returns the result. It doesn't store the pipeline at server-side.

Example 2:

pi pipeline global/app/myapp/pipeline/helloworld.pi.yaml

This example executes a persisted pipeline stored at the key path global/app/myapp/pipeline/helloworld.pi.yaml.

Example 3:

pi pipeline "log?message=HELLO"

This example takes the given pipeline uri and executes it at server side.

The syntax of a pipeline uri looks like this:

<command>[?<arg1>=<value1>&<arg2>=<value2>]

It is also possible to combine multiple commands to form a pipeline using the pipe | character:

<commandA>?<arg1>=<value1>&<arg2>=<value2>|<commandB>?<arg1>=<value1>&<arg2>=<value2>

Here is an example to re-write this YAML pipeline configuration:

pipeline:
  - datetime:
      format: "dd.MM.YY"
  - log:

To this pipeline uri format:

datetime?format=dd.MM.YY|log

Therefore, a call of this pipeline uri would look like this:

pi pipeline "datetime?format=dd.MM.YY|log"

Output:

23.01.21

The idea of a pipeline uri is to adhoc execute commands without the need to create a pipeline file and/or upload it.

Also, see the CLI command pi help command, which lists all available pipeline commands and their description you can use to build pipelines and pipeline uris.

pi publish​

This uploads your created or changed resources like pipeline or form configurations to the server.

In case a resource already exists at the server, this updates only if it has changed since last upload.

Example 1:

pi publish

This command uploads / updates all resources inside the properties folder.

Example 2:

If you want to publish only a certain subset of the properties folder, you can specify the folder like this:

pi publish properties/global/app/myapp/**

This will recursively publish any resource inside this folder and its sub-folders.

Example 3:

In case you want to publish only the files inside this folder, but not its sub-folders and files, you can use a single asterisk instead:

pi publish properties/global/app/myapp/*

Example 4:

If you want to publish a single resource, define it by its filename:

pi publish properties/global/app/myapp/pipeline/hello.pi.yaml

Example 5:

Note, that the path argument is always relatively to your current working dir, as long as you are inside the workspace home folder $USER_HOME/pipeforce:

cd $USER_HOME/pipeforce/properties/global/app/myapp
pi publish **

This will publish all resources inside properties/gobal/app/myapp recursively.

For security reasons (for example, to not accidentally publish a huge path structure of your file system to the server), publish is only possible in case your current working dir is inside the workspace folder.

pi setup​

This changes the settings of the CLI tool using a wizard and/or installs the CLI if not already done.

This writes the final result into the file $USER_HOME/pipeforce/pipeforce-cli/conf/cli.conf.json.

Example 1:

pi setup

Example 2:

For more advanced users, you can use the advanced flag in order to be able to adjust more settings:

pi setup advanced

pi status​

This returns status information about the CLI.

Example:

pi status

pi sync​

This does a one-way-sync of files inside the local properties folder to the server. It watches a given folder, and immediately syncs changes of files inside this folder to the server.

Example:

pi sync properties/global/app/myapp

This example syncs all files from the folder myapp to the server.

At the beginning of the sync, you will be asked whether you want to backup and cleanup the given folder. If you choose yes, then the content of the remote folder will be downloaded and stored in your workspace inside the backup folder, and then the remote content gets deleted. This is handy in case you want to start with a clean sync state between local and server side.

pi update​

This looks for an update of the CLI and installs it if a newer version exists.

Example:

pi update

Kubernetes Commands​

Since version v3.0.13 the CLI also contains some useful commands in order to make it easier to work with the Kubernetes backend of PIPEFORCE. These commands are intended mainly to simplify the development for backend developers and DevOps.

In order to be able to use these extended commands, kubectl must be installed and its current context must be configured in a way to successfully access to the Kubernetes cluster, the commands must be targeted to.

All commands specific to Kubernetes are prefixed with a k for example kupload.

All k-commands are executed inside the namespace of the currently active instance, selected by pi setup or pi instance.

pi kdownload​

Downloads a file or folder (recursively) from a container inside Kubernetes to the local file system. Automatically selects the container by resolving the given service name.

pi kdownload <SERVICE> <REMOTE_PATH> <LOCAL_PATH>

Example:

pi kdownload hub /srv/ /Users/user1/

pi kexec​

Executes a command inside a container within Kubernetes. Automatically selects the container by resolving the given service name.

pi kexec <SERVICE> -- <REMOTE_COMMAND>

Example:

pi kexec hub -- ls -l

pi kpodname​

Automatically detects the internal pod names for a given PIPEFORCE service name and returns them.

pi kpodname <SERVICE>

Example:

pi kpodname hub

pi ksync​

Syncs file and folder changes (create, modify, delete) inside a local folder (recursively) with the remote folder in a container. Automatically selects the container by resolving the given service name.

pi ksync <SERVICE> <LOCAL_PATH> <REMOTE_PATH> [<CHOWN>]

Example:

pi ksync drive /Users/me/git/drive/ /var/www/html www-data:root

This example (one-way) syncs any local changes to the remote container and applies a chown with www-data:root recursively on the synced sources.

pi kupload​

Uploads a file or folder (recursively) from local file system to a container inside Kubernetes. Automatically selects the container by resolving the given service name.

pi kupload <SERVICE> <LOCAL_PATH> <REMOTE_PATH>

Example:

pi kupload hub /Users/user1/ /srv/ 

Local Development​

PIPEFORCE gives you full source code control on any of your application resources. This way you can put also the low code sources under GitOps control the same way you would do with any other source code.

The local low-code workspace is a folder on your local machine, where you can store and edit all of your low-code configuration files and scripts, and then sync them with the PIPEFORCE property store with a single call of pi publish.

You could manage all properties in the property store with the property.* commands and the CLI using pi pipeline.

This might be useful for small changes. But, if you want to develop and customize full business applications, we recommend you to use the local low-code workspace. This way you can track changes more easily and be prepared for a good change management process.

The low-code workspace will mirror the property store properties as a local hierarchy of folders and files. Any configuration and script file created locally inside this workspace, can then easily be uploaded to the property store with a single command. For example:

pi publish properties/global/app/myapp/*

This scans the folder myapp inside the workspace, and uploads only those resources which have been changed since last upload or have been created since then.

You can also use the short form of the command:

pi publish 

This will publish any new or changes resources inside the properties folder to the server.

Prerequisites​

To set-up your local low-code workspace, you need to first download and install the CLI as described here: Downloads

Furthermore, we recommend you to download and install the free source code editor Visual Studio Code (as explained in the above link)

Even if you have a different favorite editor, we recommend you to start with this one, since it is easier to follow all of the examples. Later, you can switch to a different editor if you want.

Link to your instance​

After you have installed the CLI, you can link to the remote PIPEFORCE instance you would like to use. Start the setup with this command:

pi setup

This will ask you a few questions to set-up the workspace correctly.

Namespace [None]:

Here, you need to type-in the namespace of your PIPEFORCE instance, which is typically the name of your company. If you’re not sure what your namespace is, ask support@pipeforce.io.

Typically the namespace is the NAMESPACE part of your instance url (not the full url!):
https://NAMESPACE.pipeforce.net

For example, if your instance url is https://acme.pipeforce.net, then your namespace would be acme.

Type this name in, and then press enter.

Username [None]:

Type-in your username.

Password []:

Type-in your password to login into the system.

Congratulations! A new property store workspace was been created for you under
$USER_HOME/pipeforce

Create a new workspace​

After you have installed the CLI and setup an PIPEFORCE instance, you can create a local workspace. Inside this workspace you can store all resources which must be deployed later to PIPEFORCE.

For this, create an empty folder at a location of your choice and change into this folder. Then run pi init inside this folder:

mkdir myworkspace
cd myworkspace
pi init

This will create all the required file and folder structure for you inside your workspace folder.

Also see the pi init command above for more details.

In order to start development in VS code, type-in this command:

cd myworkspace
code .

This will open the workspace in VS code and you can start developing your custom apps.

You can start for example by creating a new app using the command pi new app

Configure the workspace​

Each workspace may contain the file .pipeforce/config.json which contains all settings for your local workspace. If this file is missing, the default values will be used instead. This file will by default look like this:

{
  "propertiesHome": "properties",
  "requiredVersion": null,
  "deployWithExtension": true
}

• propertiesHome defines the name of the folder at root of the worspace which contains all property sources which will be deployed to the PIPEFORCE backend. By default this is set to properties.

• requiredVersion defines the minimum version of the PIPEFORE backend which is required in order to run the apps defined in this workspace. For example 9.0.0 or just 9. If this value is empty or null, specific version check will be done. This will be checked in case the workspace apps are installed using the command app.install or via marketplace. Default value is null.

• deployWithExtension defines whether the filename extensions of the files from inside the propertiesHome folder should be kept in the property path on deployment to the property store or not. For example a file in properties/global/app/config/app.json will be deployed to a property path global/app/config/app.json if this value is set to true, or to global/app/config/app if this value is false. Default is false.

Using Visual Studio Code​

Visual Studio Code (in short: VS Code) is a free resource editor which works nicely together with the pi tool and simplifies customizing PIPEFORCE. You can also use a different editor, but we recommend you to use this one at least for the starting phase.

Download and Installation​

You can download Visual Studio Code for free here: https://code.visualstudio.com/download

Loading the workspace in VS Code​

After you have created a new PIPEFORCE workspace, navigate to its location:

cd myworkspace

Inside this folder, there is a file called PIPEFORCE.code-workspace. Double click this file in order to start the Visual Studio Code. Note: Visual Studio Code needs to be installed beforehand.

This will start Visual Studio Code with everything already set-up, so you can immediately start to create and deploy apps in PIPEFORCE:

Show the terminal​

It is comfortable to also show the terminal inside of VS Code. To do so, in the top menu, click Terminal → New Terminal. This opens a new terminal at the bottom of VS Code:

Create a new resource​

You can now use the terminal to create, for example, a new pipeline by typing this command in the VS Code terminal:

After pressing enter, you will be asked for a name of the new pipeline. Type-in helloworld, and press enter again.

After this, a new pipeline file was created for you with the name helloworld.pi.yaml:

If you open this file, you can see it containing a simple hello world demo pipeline, which logs “Hello World” into the server log, and writes it into the body.

Execute a pipeline in the terminal​

To run the pipeline right from within your VS Code, use this command:

pi pipeline file properties/global/pipeline/helloworld.pi.yaml

You should then see the output of this pipeline in the terminal.

Enable code completion for pipelines​

In order to enable code completion for pipelines inside of VS Code, you can optionally install the free YAML plugin from the Microsoft VS Code marketplace.

Open this url in your browser:
https://marketplace.visualstudio.com/items?itemName=redhat.vscode-yaml

Click install. Allow this link to open with VS Code, if requested.

Now, you should be able to use pipeline code completion.

To test it, add a new command in the helloworld.pi.yaml file. After you started typing, you should get a suggestion list of all available pipeline commands including inline documentation:

Publish a resource​

After you have created a resource locally, you can upload it to the property store with a simple command inside your VS Code terminal:

pi publish

After the command was executed, you can see that your pipeline has been successfully created into the property store.

Anytime you change a resource in the workspace, calling pi publish afterwards, will create or update only those resources which have been changed after the last publish. This way, you can work in a very effective way.