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 https://get.pergo.la/cli --upgrade
# verify installation
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.
If you need a previous version of the CLI, you can append the concrete version
/vX.Y.Z to the URL:
pip install https://get.pergo.la/cli/v1.1.5 --upgrade
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 pip install https://get.pergo.la/cli --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.
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:
# 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 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.
Almost all commands also support raw output in
json. Check the
-o option for further details.
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 https://api.pergola.mycompany.com/v1
# or, when returning user
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.
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
--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
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.
--force flag is set, it will start a new Build, regardless if there is a new commit or not.
--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).
--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.
<stage> alongside a
<build> and/or a
<config> must be provided.
<build> is omitted, last deployed Build will be used. This requires a previously deployed (=active) Release on Stage.
<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.
<project> is the unique ID of your Project. This cannot be changed later.
<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.
<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>]
<project>'s details. You can change
<git_url> and/or 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.
<stage> is the unique ID for your Stage. This cannot be changed later.
<type> determines what kind of runtime environment will be applied to your Stage.
<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>]
<stage>'s details. You can change
<type> and/or 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
Each entry is either an environment variable (
--env key=value) or a 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.
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
pergola remove config-data
pergola remove config-data <config> [-p <project>] -s <stage> [--key <key>]
Removes an existing data entry from the provided Configuration
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
<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:
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
pergola add member
pergola add member <member> [-p <project>]
Adds an existing user as a new Project member to the provided
Members have read/write access to the Project, means all permissions as the Project owner, except:
- add/remove other members
- change Project details (update project)
<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
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.
--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.
--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: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.
--since-time can be provided, but not both together.
<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"
- "connection attempt has returned an error"
- "connection errors"
- "error connection"
pergola restart component
pergola restart component <component> -s <stage> [-p <project>]
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>]
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>