Command-line tool: pipectl

This page describes how to install and use pipectl to manage PipeCD’s resources.

Besides using web UI, PipeCD also provides a command-line tool, pipectl, which allows you to run commands against your project’s resources. You can use pipectl to add and sync applications, wait for a deployment status.

Installation

The Pipectl command-line tool can be installed using one of the following methods:

Directly download and set up binary

Download the appropriate version for your platform from PipeCD Releases.

We recommend using the latest version of pipectl to avoid unforeseen issues. Run the following script:
```
# OS="darwin" or "linux"
curl -Lo ./pipectl https://github.com/pipe-cd/pipecd/releases/download/v0.50.0/pipectl_v0.50.0_{OS}_amd64
```
Make the pipectl binary executable.
```
chmod +x ./pipectl
```

Move the binary to your PATH.

sudo mv ./pipectl /usr/local/bin/pipectl

Test to ensure the version you installed is up-to-date.
```
pipectl version
```

Using Asdf

About Asdf

Add pipectl plugin to asdf. (If you have not yet asdf add plugin add pipectl.)
```
asdf plugin add pipectl
```
Install pipectl. Available versions are here.
```
asdf install pipectl {VERSION}
```
Set a version.
```
asdf global pipectl {VERSION}
```
Test to ensure the version you installed is up-to-date.
```
pipectl version
```

Using Aqua

About Aqua

Add pipectl to aqua.yaml. (If you want to select a version, use aqua g -i -s pipe-cd/pipecd/pipectl)
```
aqua g -i pipe-cd/pipecd/pipectl
```
Install pipectl.
```
aqua i
```
Test to ensure the version you installed is up-to-date.
```
pipectl version
```

Using Homebrew

About Homebrew

Add the pipe-cd/tap and fetch new formulae from GitHub.
```
brew tap pipe-cd/tap
brew update
```
Install pipectl.
```
brew install pipectl
```
Test to ensure the version you installed is up-to-date.
```
pipectl version
```

Run in Docker container

We are storing every version of docker image for pipectl on Google Cloud Container Registry. Available versions are here.

docker run --rm ghcr.io/pipe-cd/pipectl:{VERSION} -h

Authentication

In order for pipectl to authenticate with PipeCD’s Control Plane, it needs an API key, which can be created from Settings/API Key tab on the web UI. There are two kinds of key role: READ_ONLY and READ_WRITE. Depending on the command, it might require an appropriate role to execute.

Adding a new API key from Settings tab

When executing a command of pipectl you have to specify either a string of API key via --api-key flag or a path to the API key file via --api-key-file flag.

Usage

Help

Run help to know the available commands:

$ pipectl --help

The command line tool for PipeCD.

Usage:
  pipectl [command]

Available Commands:
  application  Manage application resources.
  deployment   Manage deployment resources.
  encrypt      Encrypt the plaintext entered in either stdin or the --input-file flag.
  event        Manage event resources.
  help         Help about any command
  init         Generate an application config (app.pipecd.yaml) easily and interactively.
  piped        Manage piped resources.
  plan-preview Show plan preview against the specified commit.
  quickstart   Quick prepare PipeCD control plane in quickstart mode.
  version      Print the information of current binary.

Flags:
  -h, --help                               help for pipectl
      --log-encoding string                The encoding type for logger [json|console|humanize]. (default "humanize")
      --log-level string                   The minimum enabled logging level. (default "info")
      --metrics                            Whether metrics is enabled or not. (default true)
      --profile                            If true enables uploading the profiles to Stackdriver.
      --profile-debug-logging              If true enables logging debug information of profiler.
      --profiler-credentials-file string   The path to the credentials file using while sending profiles to Stackdriver.

Use "pipectl [command] --help" for more information about a command.

Adding a new application

Add a new application into the project:

pipectl application add \
    --address=CONTROL_PLANE_API_ADDRESS \
    --api-key=API_KEY \
    --app-name=simple \
    --app-kind=KUBERNETES \
    --piped-id=PIPED_ID \
    --platform-provider=kubernetes-default \
    --repo-id=examples \
    --app-dir=kubernetes/simple

Run help to know what command flags should be specified:

$ pipectl application add --help

Add a new application.

Usage:
  pipectl application add [flags]

Flags:
      --app-dir string            The relative path from the root of repository to the application directory.
      --app-kind string           The kind of application. (KUBERNETES|TERRAFORM|LAMBDA|CLOUDRUN)
      --app-name string           The application name.
      --platform-provider string  The platform provider name. One of the registered providers in the piped configuration. The previous name of this field is cloud-provider.
      --config-file-name string   The configuration file name. (default "app.pipecd.yaml")
      --description string        The description of the application.
  -h, --help                      help for add
      --piped-id string           The ID of piped that should handle this application.
      --repo-id string            The repository ID. One the registered repositories in the piped configuration.

Global Flags:
      --address string                     The address to Control Plane api.
      --api-key string                     The API key used while authenticating with Control Plane.
      --api-key-file string                Path to the file containing API key used while authenticating with Control Plane.
      --cert-file string                   The path to the TLS certificate file.
      --insecure                           Whether disabling transport security while connecting to Control Plane.
      --log-encoding string                The encoding type for logger [json|console|humanize]. (default "humanize")
      --log-level string                   The minimum enabled logging level. (default "info")
      --metrics                            Whether metrics is enabled or not. (default true)
      --profile                            If true enables uploading the profiles to Stackdriver.
      --profile-debug-logging              If true enables logging debug information of profiler.
      --profiler-credentials-file string   The path to the credentials file using while sending profiles to Stackdriver.

Syncing an application

Send a request to sync an application and exit immediately when the deployment is triggered:

pipectl application sync \
    --address={CONTROL_PLANE_API_ADDRESS} \
    --api-key={API_KEY} \
    --app-id={APPLICATION_ID}

Send a request to sync an application and wait until the triggered deployment reaches one of the specified statuses:

pipectl application sync \
    --address={CONTROL_PLANE_API_ADDRESS} \
    --api-key={API_KEY} \
    --app-id={APPLICATION_ID} \
    --wait-status=DEPLOYMENT_SUCCESS,DEPLOYMENT_FAILURE

Getting an application

Display the information of a given application in JSON format:

pipectl application get \
    --address={CONTROL_PLANE_API_ADDRESS} \
    --api-key={API_KEY} \
    --app-id={APPLICATION_ID}

Listing applications

Find and display the information of matching applications in JSON format:

pipectl application list \
    --address={CONTROL_PLANE_API_ADDRESS} \
    --api-key={API_KEY} \
    --app-name={APPLICATION_NAME} \
    --app-kind=KUBERNETES \

Disable an application

Disable an application with given id:

pipectl application disable \
    --address={CONTROL_PLANE_API_ADDRESS} \
    --api-key={API_KEY} \
    --app-id={APPLICATION_ID}

Deleting an application

Delete an application with given id:

pipectl application delete \
    --address={CONTROL_PLANE_API_ADDRESS} \
    --api-key={API_KEY} \
    --app-id={APPLICATION_ID}

List deployments

Show the list of deployments based on filters.

pipectl deployment list \
    --address={CONTROL_PLANE_API_ADDRESS} \
    --api-key={API_KEY} \
    --app-id={APPLICATION_ID}

Waiting a deployment status

Wait until a given deployment reaches one of the specified statuses:

pipectl deployment wait-status \
    --address={CONTROL_PLANE_API_ADDRESS} \
    --api-key={API_KEY} \
    --deployment-id={DEPLOYMENT_ID} \
    --status=DEPLOYMENT_SUCCESS

Get deployment stages log

Get deployment stages log.

pipectl deployment logs \
    --address={CONTROL_PLANE_API_ADDRESS} \
    --api-key={API_KEY} \
    --deployment-id={DEPLOYMENT_ID}

Registering an event for EventWatcher

pipectl event register \
    --address={CONTROL_PLANE_API_ADDRESS} \
    --api-key={API_KEY} \
    --name=example-image-pushed \
    --data=gcr.io/pipecd/example:v0.1.0

Encrypting the data you want to use when deploying

Encrypt the plaintext entered either in stdin or via the --input-file flag.

You can encrypt it the same way you do from the web.

From stdin:

pipectl encrypt \
    --address={CONTROL_PLANE_API_ADDRESS} \
    --api-key={API_KEY} \
    --piped-id={PIPED_ID} <{PATH_TO_SECRET_FILE}

From the --input-file flag:

pipectl encrypt \
    --address={CONTROL_PLANE_API_ADDRESS} \
    --api-key={API_KEY} \
    --piped-id={PIPED_ID} \
    --input-file={PATH_TO_SECRET_FILE}

Note: The docs for pipectl available command is maybe outdated, we suggest users use the help command for the updated usage while using pipectl.

Generating an application config (app.pipecd.yaml)

Generate an app.pipecd.yaml interactively:

$ pipectl init
Which platform? Enter the number [0]Kubernetes [1]ECS: 1
Name of the application: myApp
...

After the above interaction, you can get the config YAML:

apiVersion: pipecd.dev/v1beta1
kind: ECSApp
spec:
  name: myApp
  input:
    serviceDefinitionFile: serviceDef.yaml
    taskDefinitionFile: taskDef.yaml
    targetGroups:
      primary:
        targetGroupArn: arn:aws:elasticloadbalancing:ap-northeast-1:123456789012:targetgroup/xxx/xxx
        containerName: web
        containerPort: 80
  description: Generated by `pipectl init`. See https://pipecd.dev/docs/user-guide/configuration-reference/ for more.

See Feature Status.

You want more?

We always want to add more needed commands into pipectl. Please let us know what command you want to add by creating issues in the pipe-cd/pipecd repository. We also welcome your pull request to add the command.

Feedback

Was this page helpful?

Glad to hear it! Please tell us how we can improve.

Sorry to hear that. Please tell us how we can improve.

Last modified October 19, 2024: Update pipectl image URI in docs (#5283) (dd779a48)