Skip to main content

Pergola Command-Line Interface (CLI v1)

info

This documentation is for version 1 of the Pergola CLI only. The Pergola CLI v1 is currently supported, but new features added to the CLI v2 might not be added to the CLI v1. To use those features, you must install the Pergola CLI v2.

For migrating the CLI from v1 to v2, see the Migration Guide.

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 v1:

pip install https://get.pergo.la/cli/v1 --upgrade

# verify installation
pergola info

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

Issues?

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 https://get.pergo.la/cli/v1.1.5 --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 https://get.pergo.la/cli/v1 --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

bash​

# 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

zsh​

# 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
Issues?

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
compinit

autoload -Uz bashcompinit
bashcompinit

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

tcsh​

# 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

Reference​

General​

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
DRY

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.

Example:

# login to a new cluster
pergola login --endpoint https://api.pergola.mycompany.com/v1

# 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.

note

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>