Skip to main content

Pergola Command-Line Interface (CLI)

The Pergola CLI is a tool for managing your Pergola resources and services (Projects, Stages, Releases, etc.) on a command line interface or in scripts. It provides all the features that are also available on the UI and can be used for automation in scripts, as a complementary tool or even as a drop-in replacement to the UI, especially in constrained environments without a (proper) browser, or when you feel more comfortable with a shell and keyboard than with a web frontend and mouse.

How to install or upgrade the Pergola CLI

Pergola CLI requires at least Python 3.8 and can be installed or upgraded via the package manager pip v22.0 (or newer).

This will install the latest available version of the CLI:

pip install --upgrade

# verify installation
pergola info

For upgrading an existing installation you can issue the same command above.


You might need to use the command pip3 instead of pip based on OS and/or versions of Python installed on your system.

In some rare cases the new pergola command is not on PATH right after a fresh installation. In this case starting a new shell session (or logout/login) solves the issue.

Install previous versions

If you need a previous version of the CLI, you can append the concrete version /vX.Y.Z to the URL:

pip install --upgrade
Install for all users

If you want to install the CLI globally, for all users, you'll need local root privileges (sudo rights). In that case, just prepend the installation command with sudo:

sudo pip install --upgrade

First time setup

After a fresh installation of the CLI you will need to perform a first time login to your Pergola cluster. Therefor you will need the concrete endpoint URL first that is provided by your Pergola administrator. Once you have the endpoint URL, you can issue:

pergola login --endpoint <URL of your Pergola cluster>

This will guide you through the login process. Once successfully logged in you are ready to explore the CLI. The endpoint is remembered in your local CLI configuration and does not need to be provided again.

Auto completion

The command line tab completion lets the CLI dynamically suggest completions for the arguments and options available next. Just press the TAB key anywhere after the pergola command and you'll get the relevant suggestions based on the context you are.

To enable this feature follow the instructions next based on the shell you are using. If you are not sure which shell is in use, you can get it via: echo $0


# set up autocomplete in current bash session
source <(register-python-argcomplete pergola)

# permanently add autocomplete to your bash sessions
echo "source <(`which register-python-argcomplete` pergola)" >> ~/.bashrc


# set up autocomplete in current zsh session
source <(register-python-argcomplete pergola)

# permanently add autocomplete to your zsh sessions
echo "source <(`which register-python-argcomplete` pergola)" >> ~/.zshrc

If you encounter issues like command not found: complete or command not found: compdef or similar, then you need to enable autocomplete in your zsh first. Add these lines to your ~/.zshrc before sourcing any autocomplete scripts:

autoload -Uz compinit

autoload -Uz bashcompinit

# Pergola CLI autocomplete script
source <(register-python-argcomplete pergola)


# set up autocomplete in current tcsh session
eval `register-python-argcomplete --shell tcsh pergola`

# permanently add autocomplete to your tcsh sessions
echo 'eval `register-python-argcomplete --shell tcsh pergola`' >> ~/.cshrc



The anatomy of the pergola command is as follows:

pergola <command> [<subcommand> [...]] [<args>] [<--options>] [-h]

It always starts with the main command, followed by optional sub-commands with their potentially required arguments and optional flags.

You can get help on any level which will output all available (sub-)commands, their arguments and options, default values and a brief description:

pergola -h
pergola push -h
pergola push release -h

Most of the commands require a Project scope (via the -p or the --project option). If you work mainly on a specific Project and want to avoid entering the same Project name over and over again, you can set a default Project for the current CLI configuration:

pergola set cli-config --default-project=myproject

For further options, see how to list, set and use CLI configurations.

Output formats for automation

Almost all commands also support raw output in yaml or json. Check the -o option for further details.

pergola login

pergola login [--endpoint <endpoint>]

Logs in current user.

It will present a login URL which you will need to open in a browser (can be on any machine) and follow the instructions there. First, it will ask for a user code which is usually pre-filled if you've clicked or copied the link the CLI provided. If not, just enter the code also provided by the CLI. Once you click on Submit, you will be forwarded to the authentication flow of your actual identity provider (e.g. login via Active Directory, or with your GitHub account, etc). Eventually, when authentication was successful, you will be dropped back to the original login page with a success message. You can now return to your CLI which will be already waiting for you with a warm welcome.


# login to a new cluster
pergola login --endpoint

# or, when returning user
pergola login

The endpoint URL is optional if you were logged in before. It will automatically use the same endpoint. If you are using the CLI for the first time, you have to provide a concrete URL of the Pergola cluster which you can obtain from your Pergola administrator. See also initial setup above.

If you cancel the login flow you'll need to start over again, with a fresh pergola login. The provided link is not valid anymore. Same applies when the user code has expired.

Usually, no need to manually login again

If you issue a command and you are not logged in (or your session has timed out), Pergola will automatically take you to the login and then proceed with the actual command.

pergola list project

pergola list project [--all]

Returns all Projects you are member of. If --all is provided then all publicly visible (read-only) Projects are also returned.

pergola list stage

pergola list stage [-p <project>]

Returns all Stages that belong to the provided Project.

pergola list release

pergola list release [-p <project>] [-s <stage>]

If a specific <stage> is provided, it returns the full Release history of that Stage. If only Project is provided, it returns an overview of current Release per Stage.

pergola list component

pergola list component [-p <project>] -s <stage>

Lists all Components, including their status (health, URL, ...) currently deployed on provided Stage.

pergola list build

pergola list build [-p <project>]

Lists Build history and their status for provided Project.

pergola list config

pergola list config [-p <project>] -s <stage>

Lists all available Configurations on provided Stage. Configurations are always per Stage, thus <stage> is required.

pergola list config-data

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

Lists all data entries (name/value pairs) within provided Configuration <config>.

If --with-values is provided, it will return all entries as name/value pairs. Otherwise, it will return their names only.

pergola list config-identity

pergola list config-identity <config> [-p <project>] -s <stage>

Lists all configured workload identities (including their IAM mappings) within provided Configuration <config>.

pergola list member

pergola list member [-p <project>]

Lists all Project members.

pergola push build

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

Triggers a new Build process.

It will check for a new commit (since last Build) within each branch and, if there are new commits, it will start a new Build for that branch and commit. Only branches with a valid Project Manifest file are included.

If a specific <branch> is provided, the check will be limited to that branch only.

If the --force flag is set, it will start a new Build, regardless if there is a new commit or not.


Using the --force flag can be useful in order to keep container images up-to-date even if there are no code changes, or to manually retry a Build if it obviously failed due to a temporary issue (e.g. network connectivity issues during source checkout).

Using --force in combination with a specific <branch> is recommended in order to avoid unnecessary Builds.

pergola push release

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

Deploys a new Release to provided Stage.

The target <stage> alongside a <build> and/or a <config> must be provided.

If <build> is omitted, last deployed Build will be used. This requires a previously deployed (=active) Release on Stage.

If <config> is omitted, current active Configuration will be used, if there is one previously deployed on Stage. Otherwise, a Release without Configuration (Build only) will be created.

pergola create project

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

Creates a new Project.

The <project> is the unique ID of your Project. This cannot be changed later.

The <git_url> is the URL to read and download (clone) your application code from which is required at build-time. For more details, see how to get the Git clone URL.

The <display_name> is an optional user-friendly name of your Project, as displayed also on the UI. You can change it any time.

You will be the owner of the new Project created. As an owner, you can add other team members to your Project.

pergola update project

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

Updates provided <project>'s details. You can change <git_url> and/or the <display_name>.

Changing the <git_url> will only affect new Builds.

pergola create stage

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

Creates a new Stage under given Project.

The <stage> is the unique ID for your Stage. This cannot be changed later.

The <type> determines what kind of runtime environment will be applied to your Stage.

The <display_name> is an optional user-friendly name for your Stage, as displayed also on the UI. You can change it any time.

pergola update stage

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

Updates provided <stage>'s details. You can change <type> and/or the <display_name>.

Changing the <type> will only affect new Releases.

pergola add config-data

pergola add config-data <config> [-p <project>] -s <stage> [--env <key=value>] [--file <file>]

Adds a new data entry to the provided Configuration <config>.

Each entry is either an environment variable (--env key=value) or a file (--file /path/to/file).

In case of a file, the filename (without any leading paths) becomes the key, and its content (binary or text) becomes its value. E.g. the file /path/to/config.json will be added under config.json=<content of config.json>.

If provided key (or filename) already exists, its content (value) will be updated instead. Any other existing entries will remain untouched.

Multiple files

If you add multiple files to the same Configuration and they all have the same filename, even if they are under different paths, the last one added will prevail. The data entry key for a file is always derived from its filename, without leading path names and slashes.

You can add multiple environment variables and/or files in one command by repeating the --env and/or the --file options, like:

--env key1=value1 --env key2=value2 --env key3=value3 --file config.json --file /path/to/another_config.json

This has the same effect as issuing the add config-data command one by one for each --env and --file individually.

pergola remove config-data

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

Removes an existing data entry from the provided Configuration <config>.

pergola add config-identity

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

Adds a workload identity to the provided Configuration <config>.

The provided <identity> will be linked to a cloud specific identity (IAM) at release-time if any of the Components in your Project Manifest have the same identity name defined. Once linked, all Components with this identity are able to consume cloud resources at runtime based on trust and permissions assigned to the cloud IAM entity (e.g. an IAM role on AWS, a service account on GCP, or an application on Azure).

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> [-p <project>] -s <stage> --identity <identity>

Removes an existing workload identity entry from the provided Configuration <config>.

pergola add member

pergola add member <member> [-p <project>]

Adds an existing user as a new Project member to the provided <project>.

Members have read/write access to the Project, means all permissions as the Project owner, except:

The parameter <member> accepts either the email or the uuid of the user to be added. You can obtain these details from your profile on the UI or via the pergola info command.

pergola remove member

pergola remove member <member> [-p <project>]

Removes an existing Project member from the provided <project>.

pergola logs

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

Retrieve logs for a specific Build, a Stage, or a Component on Stage.

The --since option accepts a duration, e.g. --since 3m returns only the log entries that are not older than 3 minutes. You can also combine multiple units, like --since 2h30m. Accepted units are days, hours, minutes and seconds.

The --since-time option accepts a timestamp, same format as returned by the logs, like --since-time "2023-01-09" or --since-time "2023-01-09 17:18". You have to provide at least year-month-day and can futher reduce by hour:minute, or hour:minute:second, and even append millis or microseconds and/or timezone offset, if needed. You can basically copy-paste the timestamp returned in the logs and use it as a new starting point for retrieving further logs.

Either --since or --since-time can be provided, but not both together.

The <query> parameter accepts one or multiple words to further filter the log entries. Multiple words must be put in single or double-quotes (e.g. "operation completed successfully"). Only exact matches, case-insensitive, are returned. E.g. --query "connection error" will return all log entries containing:

  • "A connection error has occured"
  • "There was a connection error."
  • "any coNNectioN ERRoR is evil"

but not:

  • "connection attempt has returned an error"
  • "connection errors"
  • "error connection"

pergola restart component

pergola restart component <component> -s <stage> [-p <project>]

Restarts specified <component>.

To minimize service outage to an absolute minimum, the provided Component's instances are restarted in a rolling fashion. Means, depending on the Component's setup, mainly its storage and scaling definitions, Pergola will try to keep at least one instance available while replacing all instances one by one.

Each instance to be replaced receives a graceful shutdown (SIGTERM) first. After a grace period (usually 60secs) they are forcibly killed.

pergola suspend stage

pergola suspend stage <stage> [-p <project>]

Suspends provided <stage>.

This will gracefully shut down all running Components (services, jobs, etc.) on given Stage, while retaining data on persistent storage. For further details, see Suspending and resuming a Stage.

pergola resume stage

pergola resume stage <stage> [-p <project>]

Resumes a previously suspended Stage.

This will revive all Components and re-enable scheduled jobs. For further details, see Suspending and resuming a Stage.

pergola validate manifest

pergola validate manifest <path/to/manifest/file>

pergola list cli-config

pergola list cli-config

pergola set cli-config

pergola set cli-config [--default-project <default_project>] [--endpoint <endpoint>] [--config <cli-config>]

pergola use cli-config

pergola use cli-config <cli-config>

pergola remove cli-config

pergola remove cli-config <cli-config>