Skip to main content

16. Command Line Interface

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 automate local tasks by executing commands and pipelines.

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.

Note

Use the command pi help command to get the documentation of all available commands activated in your license.

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.

caution

This command deletes remote resources without the option to recover. So, be careful in using it!

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 src/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 help

Thid 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 src/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 src/: 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 src/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 src folder.

Example 2:

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

pi publish src/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 src/global/app/myapp/*

Example 4:

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

pi publish src/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/src/global/app/myapp
pi publish **

This will publish all resources inside src/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/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 src folder to the server. It watches a given folder, and immediately syncs changes of files inside this folder to the server.

info

The folder to sync must be located inside the src folder of your workspace.

Example:

pi sync src/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.

caution

This is a one-way-sync from local to server. Changes made on the server-side will not be merged to your local sources. If you need such an approach, please refer to source managament tools like Git, for example, which have built-in merge conflict handling and concurrent editing features.

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/
For Windows users

Make sure to not use backslashes \ or drive letters like C:for example in your path. You have to rewrite a path like C:\myfolder to C/myfolder or simply /myfolder.

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.

For Windows users

Make sure to not use backslashes \ or drive letters like C:for example in your path. You have to rewrite a path like C:\myfolder to C/myfolder or simply /myfolder.

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/ 
For Windows users

Make sure to not use backslashes \ or drive letters like C:for example in your path. You have to rewrite a path like C:\myfolder to C/myfolder or simply /myfolder.

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 src/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 src 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.

Create a new workspace

After you have installed the CLI (Command Line Interface (CLI)), you can create a new workspace by using 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.

note

Your password is never stored by the CLI for security reasons. Instead, the CLI automatically exchanges this password with an API access token and stores this access token. This token is valid for 30 days. That means: If you did not login into PIPEFORCE for longer than 30 days, you need to re-generate this access token. You can do that by simply calling pi setup later, which asks again for credentials, and then creates and stores a new access token for you if the login was successful.

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

note

Replace $USER_HOME by the path of your user home folder, which differs depending on your current operating system.

  • For Windows, this is typically: C:\Users\YOUR_USERNAME
  • For Mac, this is typically: /Users/YOUR_USERNAME

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 customization workspace, navigate to its location which looks similar to this (could differ depending on your operating system):

cd /Users/USERNAME/pipeforce/

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 customizations 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 src/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.

Report an Issue

Your help is needed!

In case you're missing something on this page, you found an error or you have an idea for improvement, please click here to create a new issue. Another way to contribute is, to click Edit this page below and directly add your changes in GitHub. Many thanks for your contribution in order to improve PIPEFORCE!