The Pipelines CLI


The Pipelines CLI provides command line functionality for interfacing with the Pipelines SaaS.

The Pipelines CLI and Pipelines agent are unified into one package.

The Pipelines CLI is used to create, build, push, and deploy applications. With the Pipelines CLI you can create your application in Pipelines without the need for a repository.

Installing the CLI

Linux and macOS X

To install on Linux/Mac you can use either curl or wget with one of the following syntaxes.

wget example
wget -qO- | sh
curl example
curl -sSL | sh


To install on Windows, copy and paste the following PowerShell command into a command (cmd) window.

powershell -NoProfile -ExecutionPolicy Bypass -Command "iex ((new-object net.webclient).DownloadString(''))" & SET PATH=%PATH%;%ProgramFiles%/Distelli

Login and Validate

To complete, and validate, the CLI installation; issue a distelli login command to login to your Puppet Pipelines account.

Important: This requires that you have already completed the Creating an Account steps.

# distelli login


Important: If you enter your account password incorrectly too many times, a Failed to login to your Distelli Account, Please check your credentials message will appear, and your account will be locked as a security precaution. The lock expires in two hours.

Upgrading the CLI

To upgrade the Pipelines CLI, re-install the CLI on top of the existing CLI. This will perform an upgrade.

CLI events

The Pipelines CLI can be used to create application events in Pipelines applications. Typically this would be used in conjunction with a third-party build system; Jenkins, for example.

The events that can be created include:

  • Push - A software repository push (commit) event.
  • PullRequest - A software repository pull request event.
  • Build - A third-party build event.
  • DockerImage - A Docker image event.

An example usage of the Pipelines CLI to create an event:

distelli event -app bmcgehee/cli-demo -type build -build Jenkins:1234 -build-url -build-status Queued
Event Option
-profile-dir <DIR>
AllNoLocation of profile information (like cached credentials), defaults to ~/, may also be set via DISTELLI_PROFILE environment variable.
-app <See Explanation>
AllYesFor Pipelines for Applications, the format is: USERNAME/APP-NAME
For Pipelines for Containers, the format is: USERNAME/PROJECT-NAME.CONTAINER-NAME
-type <EVENT-TYPE>
AllYesEvent types include the following:
  • Push
  • PullRequest
  • Build
  • DockerImage
BuildNoThe build provider and the unique build id. Valid options for build provider include:
  • CircleCLI
  • CodeShip
  • Jenkins
  • TravisCI
  • AzureDevops
-build-url <URL>
BuildNoThe URL to the build.
-build-status <BUILD-STATUS>
BuildNoThe current status of the build. This can be updated when using the same BUILD-ID. Valid Status' include:
  • Queued
  • Waiting
  • Running
  • *TimedOut
  • *Failed
  • *Success
* These are terminal conditions and cannot be changed after they are set.
-build-start <ISO-8601-DATE-TIME>
BuildNoWhen the build started. If a new build event is created, this value does not need to be specified and will default to now. Format example: 2016-12-09T14:25:33Z
-build-end <ISO-8601-DATE-TIME>
BuildNoWhen the build ended. If a build event is updated to a terminal build status, this value does not need to be specified and will default to now. Format example: 2016-12-09T14:25:33Z
-autobuild | -noautobuild
BuildNoFlag the build event as autobuild or noautobuild.
ImageNoThe image that was pushed (and maybe built).
  • ECR
  • GCR
The TAG is optional.
When using this option a local docker inspect <REGISTRY-PROVIDER>:<DOCKER-REPOSITORY>:<TAG> is ran to obtain metadata about this docker image.

This option may be specified multiple times.
-image-registry-id <ECR-REGISTRY-ID>
ImageNoThe aws account id of the ECR registry. Typically an ECR Docker repository that you pull looks like this: This is the aws_account_id portion. Omit this option if not using ECR. If specified multiple times, the first ECR-REGISTRY-ID will be paired with the first --image option in order.
-image-registry-endpoint <REGISTRY-SERVER>
ImageNoThis is the server endpoint which you would pass to `docker login`. If specified multiple times, the first REGISTRY-SERVER will be paired with the first --image option in order.
-image-registry-name <REGISTRY-NAME>
ImageNoThis is the name for the docker repository displayed in the Pipelines interface. If specified multiple times, the first REGISTRY-NAME is paired with the first --image option in order.
AllNoSCM-PROVIDER is one of:
  • GIT
  • HG
COMMIT-ID is the unique identifier of the commit that was pushed.
-commit-msg <TEXT>
AllNoThe content of the commit message. Defaults to inspecting the specified COMMIT-ID of the SCM-PROVIDER.
-commit-url <URL>
AllNoThe URL which provides information about this commit.
AllNoThe source repository provider. REPO-PROVIDER is one of:
-repository-branch <BRANCH-NAME>
AllNoThe name of the repository branch that was pushed to.
-repository-author <REPO-USERNAME>/<DISPLAY-NAME>
AllNoThe username for the REPO-PROVIDER that pushed the commit.


When integrating a third-party build system with Pipelines, using the Pipelines CLI, the event flow is typically the following.

  1. distelli event -app USERNAME/APP-NAME -type push
  2. distelli event -app USERNAME/APP-NAME -type build -build PROVIDER:UID -build-status [QUEUED | WAITING]
  3. distelli event -app USERNAME/APP-NAME -type build -build PROVIDER:UID -build-status RUNNING
  4. distelli event -app USERNAME/APP-NAME -type build -build PROVIDER:UID -build-status [TIMEDOUT | FAILED | SUCCESS]

The above flow represents:

  • The initial commit (push).
  • Starting a build in status Queued or Waiting.
  • Updating the build status to Running.
  • Updating the build termination status to either Timedout, Failed, or Success.
  • The final "image" event would only be necessary if there was a Docker image built during the build process.

Push & PR Events

A Push or PR event in Pipelines represents a software code event. Typically in Continuous Integration (CI), when a developer checks in code (push) it triggers a build system to initiate a build. In the scenario where a Puppet Pipelines user is using a third-party build system, the Pipelines CLI events can accommodate the creation of a Push or PullRequest event in the Pipelines application history. This event, in Pipelines, can provide links to the repository and commit.

If the Pipelines CLI event type “Push” (or PullRequest) is executed from the root of a directory; where the software being built was cloned to, and there is a .git or .hg directory, the Pipelines CLI can gather all the information necessary related to the last commit (push). One can run:

distelli event -app USERNAME/APP-NAME -type push | pullrequest 
If the .git .hg directories are not available, the various push pullrequest information can be manually supplied, like so:
distelli event -app bmcgehee/example-node-docker -type push | pullrequest -commit GIT:abcd -commit-msg "testing this" -commit-url -repository GITHUB:doct15/example-node-docker -repository-branch master -repository-author "doct15/Brian McGehee"

Caution: If the directory where the distelli event -type push | pullrequest occurs has a .git or .hg directory, Pipelines will attempt to get the commit id SHA and the commit message. These values will override any specified as command line options.

Build Events

A build event, in Pipelines, will provide a means for users to navigate to the build. This event will also live track the status of the build. And provide information on when the build started, stopped, and duration.

Build events are tracked, specifically, by the BUILD-ID specified in the -build option. This means future updates to a build, must address that build event by the BUILD-ID. Below is an example showing the creating and updates of BUILD-ID xyz3457:

distelli event -app USERNAME/APP-NAME -type build -build jenkins:xyz3457 -build-url -build-status Queued -autobuild
distelli event -app USERNAME/APP-NAME -type build -build jenkins:xyz3457 -build-status Running
distelli event -app USERNAME/APP-NAME -type build -build jenkins:xyz3457 -build-status Success

The above will create a build event, in Pipelines, identified by BUILD-ID xyz3457 in a build status of Queued. The following two lines will update the same build event status from Queued to Running, and finally from Running to Success. After setting build xyz3457 to a termination state of “Success”, this build can not be updated.

Build status

Image Events

An Image event in Pipelines represents an image that was built. If using a third-party build system to build Docker images, these images are tracked in Pipelines.

To create an image event, use the following syntax:

distelli event -app USERNAME/APP-NAME -type dockerimage -image REGISTRY-PROVIDER:DOCKER-REPOSITORY:TAG

The Pipelines CLI will use the docker inspect command to find information about the last built image that matches REGISTRY-PROVIDER:DOCKER-REPOSITORY:TAG.

You can create many events for a single Docker image inspection details, but the image inspection details will not change unless the image itself actually changes.

Further information can be specified when pushing images as exemplified below:

distelli event -app bmcgehee/cli-demo -type Dockerimage -image dockerhub:doct15/cli-demo:1234 -image-registry-name "doct15/cli-demo" -repository-branch branch3 -repository-author doct15/Brian -commit-msg "Testing"
How helpful was this page?
Puppet sites use proprietary and third-party cookies. By using our sites, you agree to our cookie policy.