Skip to main content

Pergola Command-Line Interface (CLI)

How to install the Pergola CLI

Pergola CLI requires at least Python 3.8 and can be installed via the package manager pip. (One might want to use the command 'pip3' instead of 'pip' if multiple versions of python are installed on the system)

The Pergola CLI needs root/administrative rights during installation, but can be used by any user after the installation is finished.

sudo pip install https://get.pergo.la/pip/pergola-cli-1.1.4.tar.gz

pergola info

Reference

General

Each project-related Pergola command also expects a project argument if there is no default project in the configuration.

For simplicity:

<> indicates a mandatory argument
[] indicates a optional argument

pergola login

pergola login --endpoint [endpoint-url]

The endpoint url is optional.

If you are using the cli for the first time, you must first tell the command line interface under which api endpoint the backend is located. This is what the --endpoint argument is for. Just use the url you got from your Pergola administrator. This will also automatically create a .pergola folder in your user home directory with the config.json.

Example:

pergola login --endpoint https://api.garage.pergola.cloud/v1

When you execute the login command, you will receive a link and a code, click on the link. On the website you will find a text field with the code already entered. Now just click on Submit. In the next step select your active directory and log in. Pergola now knows who you are, and you can return to the CLI.

If you are not logged in but execute a command that requires authentication, Pergola will automatically execute the login command for you and then return to execute the requested command.

pergola list project

pergola list project

pergola list release

pergola list release -s <stage> (-p <project)

pergola list build

pergola list build (-p <project>)

pergola list stage

pergola list stage (-p <project>)

pergola list config

pergola list config -s <stage> (-p <project>)

pergola list config-data

pergola list config-data <config> -s <stage> [--with-values] (-p <project>)

pergola list config-identity

pergola list config-identity <config> -s <stage> (-p <project>)

pergola list member

pergola list member (-p <project>)

pergola list component

pergola list component -s <stage> (-p <project>)

pergola list cli-config

pergola list cli-config

pergola push build

pergola push build -p <project> --branch [branch-name] [--force]

The command checks for new commits in your repository, and creates a build if there are some. The project name is mandatory, the branch name and force flag are optional. The force flag triggers a build even if there are no new commits.

pergola push release

pergola push release -s <stage> -b [build-id] -c [config-name] -p [project-name]

The name of the stage on which to deploy is mandatory. The build id, configuration name, and project name are optional, but you must specify either a build id or a configuration name (or both). If you have not configured a default project in your Pergola configuration, the project name is also mandatory. If no build id or config name is given, Pergola uses the latest build and tries to find a default configuration of the stage on which it will be deployed.

pergola create project

pergola create project <project> --git-url <git-repository-url> --display-name [display-name]

The project name and a git-url are mandatory. The display name is optional. The git-url can either be HTTPS or SSH, if pergola knows about it.

Creating a project automatically makes you the owner of the project.

pergola create stage

pergola create stage <stage> --type <stage-type> -p [project] --display-name [stage-display-name] 

The stage name and the stage type are mandatory. If you have no default project configured in your Pergola config, project is also mandatory. The display name of the stage is optional.

pergola update project

pergola update project <project> --git-url [git-url] --display-name [display-name]

pergola update stage

pergola update stage <stage> --type [stage-type] --display-name [display-name] (-p <project>)

The config name, stage name and project name are mandatory.

pergola set cli-config

pergola set cli-config --default-project [default-project] --endpoint [api-endpoint] --config [config-name]

pergola add config-data

pergola add config-data <config> -s <stage-name> --env [key=value] --file [path/to/file]

How to reference data to configure

You can reference as much environment variables or files as you wish to

--env key1=value1 --env key2=value2 --env key3=value3 --file /path/to/file --file /path/to/other/file

pergola remove config-data

pergola remove config-data <config> -s <stage> --key [entry] (-p <project>)

The config name, stage name and project name are mandatory.

pergola add config-identity

pergola add config-identity <config> -s <stage> --identity <identity-name> [--aws-role-arn awsrole] [--azure-client-id azcid] [--gcp-service-account gcpsa] (-p <project>)

The config name, stage name, project name and identity name are mandatory. You need to provide at least one of: --aws-role-arn | --azure-client-id | --gcp-service-account

pergola remove config-identity

pergola remove config-identity <config> -s <stage> --identity <identity-name> (-p <project>)

The config name, stage name, project name and identity name are mandatory.

pergola add member

pergola add member <member> (-p <project>)

pergola remove member

pergola remove member <member> (-p <project>)

pergola use cli-config

pergola use cli-config <cli-config>

pergola validate manifest

pergola validate manifest <path/to/manifest>

pergola suspend stage

pergola suspend stage <stage> (-p <project>)

pergola resume stage

pergola resume stage <stage> (-p <project>)

pergola restart component

pergola restart component <component> -s <stage> (-p <project>)

pergola logs

pergola logs build <build> --query [query] (--since [duration] | --since-time [sincetime]) (-p <project>)
pergola logs stage <stage> --query [query] (--since [duration] | --since-time [sincetime]) (-p <project>)
pergola logs component <component> --query [query] (--since [duration] | --since-time [sincetime]) (-p <project>)

The build, stage or component and project are mandatory. The query (string) can be any word (or sentence in "") to filter the logs for. The --since and --since-time can not be used both in one command.