Skip to main content

Pergola Command-Line Interface (CLI v2)

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​

info

If you have the version 1 of the Pergola CLI installed, please check our Migration Guide first.

Installation via script (Linux / macOS)​

On Linux or macOS, you can install the CLI with the following command, which will download and install the latest version of the CLI for your operating system:

curl -fsSL https://get.pergo.la/cli/latest/install.sh | bash

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

Manual installation (Windows / Linux / macOS)​

If you use Windows or want to install the CLI manually, you can download the latest version of the CLI for your operating system from the following links:

note

You can find the SHA256 checksums of the CLI binaries here.

The downloaded archive contains one binary pergola, or pergola.exe respectively, which you can extract and put on a path you can easily reach from your shell environment.

On Windows you can install the CLI by extracting the pergola.exe binary from the downloaded archive and placing it on a system-wide path, like the C:\Windows\system32 folder of your Windows installation.

On Linux or macOS you can install the CLI by extracting and moving the pergola binary to the system-wide /usr/local/bin path, like:

# replace with concrete .tar.gz file downloaded
tar xf /path/to/downloaded/pergola-cli-2.x.x.tar.gz
# ensure exec permission
chmod +x pergola-cli-2.x.x/pergola
# install for all users
sudo mv pergola-cli-2.x.x/pergola /usr/local/bin/

Once installed, you can use the CLI from your command prompt:

# verify installation
pergola info
Issues?

It might happen that the new pergola command is not on PATH right after a fresh installation. In most cases, starting a new shell session (or logout/login) solves the issue.

Otherwise, make sure pergola is on PATH. See this thread on StackExchange.

First time setup​

After a fresh installation of the CLI, you will need to perform a first time login to your Pergola cluster. Therefore, you will need the concrete endpoint URL first that is either provided by your Pergola administrator, or which you can find on the Pergola Console Web UI.

Once you have the endpoint to your Pergola cluster, 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 <(pergola completion bash)

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

zsh​

# set up autocomplete in current zsh session
source <(pergola completion zsh)

# permanently add autocomplete to your zsh sessions
echo "source <(`which pergola` completion zsh)" >> ~/.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 <(pergola completion zsh)

fish​

# set up autocomplete in current fish session
pergola completion fish | source

# permanently add autocomplete to your fish sessions
echo "`which pergola` completion fish | source" >> ~/.config/fish/config.fish

powershell​

# set up autocomplete in current powershell session
pergola completion powershell | Out-String | Invoke-Expression

# permanently add autocomplete to your powershell sessions
echo "pergola completion powershell | Out-String | Invoke-Expression" >> $PROFILE
Issues?

You might not have a PowerShell profile file yet. In this case you will need to create one first:

New-Item $PROFILE

See also this thread on Microsoft Tech Community.

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 that 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. The same applies when the user code has expired.

Usually, no need to manually log in 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 | --archived]

Returns all Projects you are a member of.

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

If --archived is provided then only archived Projects are returned.

The flags --all and --archived cannot be used together.

pergola list stage​

pergola list stage [-p <project>] [--archived]

Returns all Stages that belong to the provided Project.

If --archived is provided then only archived Stages are returned.

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 the 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 commits​

pergola list commits <build> [-p <project>]

Lists code changes (commits) for provided Build since last Build on same branch.

pergola list vulnerabilities​

pergola list vulnerabilities <build> [-p <project>]
pergola list vulnerabilities <build> [-p <project>] -c <component>
pergola list vulnerabilities <build> [-p <project>] -c <component> --id <vulnerability-id>

Lists all detected vulnerabilites within provided Build.

If only <build> is provided, it will return a summary for the entire Build, with totals by severity (e.g. high, medium, low) and the affected Component.

If <component> is provided, it will return a list of all found vulnerabilities for that provided Component.

If also a specific <vulnerability-id> is provided (e.g. CVE-2022-34903) then a detailed description about that issue is provided.

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 the 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 delete project​

pergola delete project <project>

Marks provided <project> for deletion.

A Project with Stages is archived first and can be restored during the configured retention period. Once the retention period expires, the Project will be permanently deleted.

pergola restore project​

pergola restore project <project>

Restores a previously archived <project> and its Stages.

pergola create stage​

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

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.

The <outpost_uri> is an optional URI to an Outpost. If provided, all Components deployed to this Stage will be deployed and run on a remote Outpost.

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 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 delete stage​

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

Marks provided <stage> for deletion.

A Stage is archived first and can be restored during the configured retention period. Once the retention period expires, the Stage will be permanently deleted.

pergola restore stage​

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

Restores a previously archived <stage>.

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.

If provided configuration <config> does not exist yet, a new (empty) one will be automatically created before the entries are added.

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

If provided configuration <config> does not exist yet, a new (empty) one will be automatically created before the workload identity is added.

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 delete config​

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

Deletes provided Configuration <config> including any underlying config-data or config-identities from provided Stage.

pergola add member​

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

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

You can optionally assign a <role>:

  • member: regular Project member (default)
  • owner: adds User as an additional Project owner

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

  • add/remove other members
  • change a member's role
  • change Project details (update project)

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.

You can change the role of an existing member by issuing the same command with a different <role>.

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>] [--follow] [--since <duration> | --since-time <sincetime>]
pergola logs stage     <stage>     [-p <project>]            [--query <query>] [--follow] [--since <duration> | --since-time <sincetime>]
pergola logs component <component> [-p <project>] -s <stage> [--query <query>] [--follow] [--since <duration> | --since-time <sincetime>]

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

The --follow option causes the command to not stop when last log entry is reached, but rather to wait for additional log entries to be appended (similar to tail -f). You can exit this mode by pressing ctrl+c.

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 narrow down further by hour:minute, or hour:minute:second, and even 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 notifications​

pergola notifications project <project> [--since <duration> | --since-time <sincetime>]

Retrieve notifications for a specific <project>.

The --since option accepts a duration, e.g. --since 3m returns only the notifications 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, 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 narrow down further by hour:minute, or hour:minute:second, and even millis or microseconds and/or timezone offset, if needed.

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

pergola restart component​

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

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 exec​

pergola exec <component> [-p <project>] -s <stage> -- COMMAND [args...]

Executes commands within a running Component instance.

This can be used for troubleshooting and debugging a running Component. You can either issue an individual command, like cat /etc/expected.config, or get a shell into your running Component, e.g. /bin/bash.

pergola local-connect​

pergola local-connect <component> [[<host-address>:]<host-port>:]<component-port>] [-p <project>] -s <stage>

Establishes a local connection between your local system and a running Component. The provided <component> must expose at least one port.

This is useful for scenarios where you need temporary access to your Component without requiring an Ingress, especially for troubleshooting or debugging backend services, like databases. Any TCP traffic from the Component will be forwarded to your local machine, and vice versa. This allows you to use the most suitable tools (e.g. your favorite DB-client) and connect to a running Component from your local environment natively.

If no <host-address> is provided, the local connection will bind to localhost.

If no <host-port> is provided, a random local port will be allocated.

If no <component-port> is provided, the Component's only exposed port will be used. If Component exposes multiple ports, the desired <component-port> must be specified.

If <host-address> is provided, <host-port> and <component-port> must be provided as well.

Example:

pergola local-connect my-component 28080:8080 -p my-project -s my-stage

This will establish a connection from your localhost:28080 to my-component's port 8080. Means, any connection to localhost:28080 will be forwarded to my-project/my-stage/my-component:8080.

pergola validate manifest​

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

Validates the provided Project Manifest file and prints potential errors and warnings.

The same validation rules apply as during a regular Build. Especially for new Projects, unnecessary Build roundtrips can be avoided if the written Manifest file is validated locally beforehand.

pergola list cli-config​

pergola list cli-config

Lists all CLI configurations.

pergola set cli-config​

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

Sets a default Project <default_project> and/or endpoint URL <endpoint> under the provided CLI configuration <cli-config>.

If provided <cli-config> does not exist yet, it will be created. Otherwise, it will be updated.

If no <cli-config> is provided, the current active CLI configuration will be updated.

pergola use cli-config​

pergola use cli-config <cli-config>

Activates the provided CLI configuration <cli-config>.

pergola delete cli-config​

pergola delete cli-config <cli-config>

Deletes the provided CLI configuration <cli-config>.