Command-line tool: pipectl
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
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.49.4/pipectl_v0.49.4_{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
Asdf
-
Add pipectl plugin to asdf. (If you have not yet
asdf add plugin add pipectl.)asdf add plugin 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
Docker
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
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
Register an event that can be used by 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-fileflag: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.
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.
