Common Options

-a XXX, --app XXX         app ref on Control Plane (GVC)

This -a option is used in most of the commands and will pick all other app configurations from the project-specific .controlplane/controlplane.yml file.

Commands

`apply-template`

Applies application-specific configs from templates (e.g., for every review-app)
Publishes (creates or updates) those at Control Plane infrastructure
Picks templates from the .controlplane/templates directory
Templates are ordinary Control Plane templates but with variable preprocessing

Preprocessed template variables:

{{APP_ORG}}           - organization name
{{APP_NAME}}          - GVC/app name
{{APP_LOCATION}}      - location, per YML file, ENV, or command line arg
{{APP_LOCATION_LINK}} - full link for location, ready to be used for the value of `staticPlacement.locationLinks` in the templates
{{APP_IMAGE}}         - latest app image
{{APP_IMAGE_LINK}}    - full link for latest app image, ready to be used for the value of `containers[].image` in the templates
{{APP_IDENTITY}}      - default identity
{{APP_IDENTITY_LINK}} - full link for identity, ready to be used for the value of `identityLink` in the templates

# Applies single template.
cpl apply-template redis -a $APP_NAME

# Applies several templates (practically creating full app).
cpl apply-template app postgres redis rails -a $APP_NAME

`build-image`

Builds and pushes the image to Control Plane
Automatically assigns image numbers, e.g., app:1, app:2, etc.
Uses .controlplane/Dockerfile or a different Dockerfile specified through dockerfile in the .controlplane/controlplane.yml file
If a commit is provided through --commit or -c, it will be set as the runtime env var GIT_COMMIT
Accepts extra options that are passed to docker build

cpl build-image -a $APP_NAME

`cleanup-images`

Deletes all images for an app that either exceed the max quantity or are older than the specified amount of days
Specify the max quantity through image_retention_max_qty in the .controlplane/controlplane.yml file
Specify the amount of days through image_retention_days in the .controlplane/controlplane.yml file
If image_retention_max_qty is specified, any images that exceed it will be deleted, regardless of image_retention_days
Will ask for explicit user confirmation
Never deletes the latest image

cpl cleanup-images -a $APP_NAME

`cleanup-stale-apps`

Deletes the whole app (GVC with all workloads and all images) for all stale apps
Stale apps are identified based on the creation date of the latest image
Specify the amount of days after an app should be considered stale through stale_app_image_deployed_days in the .controlplane/controlplane.yml file
If match_if_app_name_starts_with is true in the .controlplane/controlplane.yml file, it will delete all stale apps that start with the name
Will ask for explicit user confirmation

cpl cleanup-stale-apps -a $APP_NAME

`config`

Displays config for each app or a specific app

# Shows the config for each app.
cpl config

# Shows the config for a specific app.
cpl config -a $APP_NAME

`copy-image-from-upstream`

Copies an image (by default the latest) from a source org to the current org
The source app must be specified either through the CPLN_UPSTREAM env var or upstream in the .controlplane/controlplane.yml file
Additionally, the token for the source org must be provided through --upstream-token or -t
A cpln profile will be temporarily created to pull the image from the source org

# Copies the latest image from the source org to the current org.
cpl copy-image-from-upstream -a $APP_NAME --upstream-token $UPSTREAM_TOKEN

# Copies a specific image from the source org to the current org.
cpl copy-image-from-upstream -a $APP_NAME --upstream-token $UPSTREAM_TOKEN --image appimage:123

`delete`

Deletes the whole app (GVC with all workloads, all volumesets and all images) or a specific workload
Will ask for explicit user confirmation

# Deletes the whole app (GVC with all workloads, all volumesets and all images).
cpl delete -a $APP_NAME

# Deletes a specific workload.
cpl delete -a $APP_NAME -w $WORKLOAD_NAME

`deploy-image`

Deploys the latest image to app workloads
Optionally runs a release script before deploying if specified through release_script in the .controlplane/controlplane.yml file and --run-release-phase is provided
The release script is run in the context of cpl run with the latest image
The deploy will fail if the release script exits with a non-zero code or doesn't exist

cpl deploy-image -a $APP_NAME

`env`

Displays app-specific environment variables

cpl env -a $APP_NAME

`exists`

Shell-checks if an application (GVC) exists, useful in scripts, e.g.:

if [ cpl exists -a $APP_NAME ]; ...

`generate`

Creates base Control Plane config and template files

# Creates .controlplane directory with Control Plane config and other templates
cpl generate

`info`

Displays the diff between defined/available apps/workloads (apps equal GVCs)
Apps that are defined but not available are displayed in red
Apps that are available but not defined are displayed in green
Apps that are both defined and available are displayed in white
The diff is based on what's defined in the .controlplane/controlplane.yml file

# Shows diff for all apps in all orgs (based on `.controlplane/controlplane.yml`).
cpl info

# Shows diff for all apps in a specific org.
cpl info -o $ORG_NAME

# Shows diff for a specific app.
cpl info -a $APP_NAME

`latest-image`

Displays the latest image name

cpl latest-image -a $APP_NAME

`logs`

Light wrapper to display tailed raw logs for app/workload syntax
Defaults to showing the last 200 entries from the past 1 hour before tailing

# Displays logs for the default workload (`one_off_workload`).
cpl logs -a $APP_NAME

# Displays logs for a specific workload.
cpl logs -a $APP_NAME -w $WORKLOAD_NAME

# Displays logs for a specific replica of a workload.
cpl logs -a $APP_NAME -w $WORKLOAD_NAME -r $REPLICA_NAME

# Uses a different limit on number of entries.
cpl logs -a $APP_NAME --limit 100

# Uses a different loopback window.
cpl logs -a $APP_NAME --since 30min

`maintenance`

Checks if maintenance mode is on or off for an app
Outputs 'on' or 'off'
Specify the one-off workload through one_off_workload in the .controlplane/controlplane.yml file
Optionally specify the maintenance workload through maintenance_workload in the .controlplane/controlplane.yml file (defaults to 'maintenance')
Maintenance mode is only supported for domains that use path based routing mode and have a route configured for the prefix '/' on either port 80 or 443

cpl maintenance -a $APP_NAME

`maintenance:off`

Disables maintenance mode for an app
Specify the one-off workload through one_off_workload in the .controlplane/controlplane.yml file
Optionally specify the maintenance workload through maintenance_workload in the .controlplane/controlplane.yml file (defaults to 'maintenance')
Maintenance mode is only supported for domains that use path based routing mode and have a route configured for the prefix '/' on either port 80 or 443

cpl maintenance:off -a $APP_NAME

`maintenance:on`

Enables maintenance mode for an app
Specify the one-off workload through one_off_workload in the .controlplane/controlplane.yml file
Optionally specify the maintenance workload through maintenance_workload in the .controlplane/controlplane.yml file (defaults to 'maintenance')
Maintenance mode is only supported for domains that use path based routing mode and have a route configured for the prefix '/' on either port 80 or 443

cpl maintenance:on -a $APP_NAME

`maintenance:set-page`

Sets the page for maintenance mode
Only works if the maintenance workload uses the shakacode/maintenance-mode image
Will set the URL as an env var PAGE_URL on the maintenance workload
Optionally specify the maintenance workload through maintenance_workload in the .controlplane/controlplane.yml file (defaults to 'maintenance')

cpl maintenance:set-page PAGE_URL -a $APP_NAME

`open`

Opens the app endpoint URL in the default browser

# Opens the endpoint of the default workload (`one_off_workload`).
cpl open -a $APP_NAME

# Opens the endpoint of a specific workload.
cpl open -a $APP_NAME -w $WORKLOAD_NAME

`open-console`

Opens the app console on Control Plane in the default browser
Can also go directly to a workload page if --workload is provided

cpl open-console -a $APP_NAME

`promote-app-from-upstream`

Copies the latest image from upstream, runs a release script (optional), and deploys the image
It performs the following steps:
- Runs cpl copy-image-from-upstream to copy the latest image from upstream
- Runs cpl deploy-image to deploy the image
- If .controlplane/controlplane.yml includes the release_script, cpl deploy-image will use the --run-release-phase option
- The deploy will fail if the release script exits with a non-zero code

cpl promote-app-from-upstream -a $APP_NAME -t $UPSTREAM_TOKEN

`ps`

Shows running replicas in app

# Shows running replicas in app, for all workloads.
cpl ps -a $APP_NAME

# Shows running replicas in app, for a specific workload.
cpl ps -a $APP_NAME -w $WORKLOAD_NAME

`ps:restart`

Forces redeploy of workloads in app

# Forces redeploy of all workloads in app.
cpl ps:restart -a $APP_NAME

# Forces redeploy of a specific workload in app.
cpl ps:restart -a $APP_NAME -w $WORKLOAD_NAME

`ps:start`

Starts workloads in app

# Starts all workloads in app.
cpl ps:start -a $APP_NAME

# Starts a specific workload in app.
cpl ps:start -a $APP_NAME -w $WORKLOAD_NAME

`ps:stop`

Stops workloads in app

# Stops all workloads in app.
cpl ps:stop -a $APP_NAME

# Stops a specific workload in app.
cpl ps:stop -a $APP_NAME -w $WORKLOAD_NAME

# Stops a specific replica of a workload.
cpl ps:stop -a $APP_NAME -w $WORKLOAD_NAME -r $REPLICA_NAME

`ps:wait`

Waits for workloads in app to be ready after re-deployment

# Waits for all workloads in app.
cpl ps:wait -a $APP_NAME

# Waits for a specific workload in app.
cpl ps:swait -a $APP_NAME -w $WORKLOAD_NAME

`run`

Runs one-off interactive or non-interactive replicas (analog of heroku run)
Uses Cron workload type and either:
- cpln workload exec for interactive mode, with CLI streaming
- log async fetching for non-interactive mode
The Dockerfile entrypoint is used as the command by default, which assumes exec "${@}" to be present, and the args ["bash", "-c", cmd_to_run] are passed
The entrypoint can be overriden through --entrypoint, which must be a single command or a script path that exists in the container, and the args ["bash", "-c", cmd_to_run] are passed, unless the entrypoint is bash, in which case the args ["-c", cmd_to_run] are passed
Providing --entrypoint none sets the entrypoint to bash by default
If fix_terminal_size is true in the .controlplane/controlplane.yml file, the remote terminal size will be fixed to match the local terminal size (may also be overriden through --terminal-size)

# Opens shell (bash by default).
cpl run -a $APP_NAME

# Runs interactive command, keeps shell open, and stops job when exiting.
cpl run -a $APP_NAME --interactive -- rails c

# Some commands are automatically detected as interactive, so no need to pass `--interactive`.
cpl run -a $APP_NAME -- bash
      cpl run -a $APP_NAME -- rails console
      cpl run -a $APP_NAME -- rails c
      cpl run -a $APP_NAME -- rails dbconsole
      cpl run -a $APP_NAME -- rails db

# Runs non-interactive command, outputs logs, exits with the exit code of the command and stops job.
cpl run -a $APP_NAME -- rails db:migrate

# Runs non-iteractive command, detaches, exits with 0, and prints commands to:
# - see logs from the job
# - stop the job
cpl run -a $APP_NAME --detached -- rails db:migrate

# The command needs to be quoted if setting an env variable or passing args.
cpl run -a $APP_NAME -- 'SOME_ENV_VAR=some_value rails db:migrate'

# Uses a different image (which may not be promoted yet).
cpl run -a $APP_NAME --image appimage:123 -- rails db:migrate # Exact image name
cpl run -a $APP_NAME --image latest -- rails db:migrate       # Latest sequential image

# Uses a different workload than `one_off_workload` from `.controlplane/controlplane.yml`.
cpl run -a $APP_NAME -w other-workload -- bash

# Overrides remote CPLN_TOKEN env variable with local token.
# Useful when superuser rights are needed in remote container.
cpl run -a $APP_NAME --use-local-token -- bash

# Replaces the existing Dockerfile entrypoint with `bash`.
cpl run -a $APP_NAME --entrypoint none -- rails db:migrate

# Replaces the existing Dockerfile entrypoint.
cpl run -a $APP_NAME --entrypoint /app/alternative-entrypoint.sh -- rails db:migrate

`setup-app`

Creates an app and all its workloads
Specify the templates for the app and workloads through setup_app_templates in the .controlplane/controlplane.yml file
This should only be used for temporary apps like review apps, never for persistent apps like production (to update workloads for those, use 'cpl apply-template' instead)
Automatically binds the app to the secrets policy, as long as both the identity and the policy exist
Use --skip-secret-access-binding to prevent the automatic bind

cpl setup-app -a $APP_NAME

`version`

Displays the current version of the CLI
Can also be done with cpl --version or cpl -v

cpl version

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

commands.md

commands.md

Common Options

Commands

`apply-template`

`build-image`

`cleanup-images`

`cleanup-stale-apps`

`config`

`copy-image-from-upstream`

`delete`

`deploy-image`

`env`

`exists`

`generate`

`info`

`latest-image`

`logs`

`maintenance`

`maintenance:off`

`maintenance:on`

`maintenance:set-page`

`open`

`open-console`

`promote-app-from-upstream`

`ps`

`ps:restart`

`ps:start`

`ps:stop`

`ps:wait`

`run`

`setup-app`

`version`

Files

commands.md

Latest commit

History

commands.md

File metadata and controls

Common Options

Commands

apply-template

build-image

cleanup-images

cleanup-stale-apps

config

copy-image-from-upstream

delete

deploy-image

env

exists

generate

info

latest-image

logs

maintenance

maintenance:off

maintenance:on

maintenance:set-page

open

open-console

promote-app-from-upstream

ps

ps:restart

ps:start

ps:stop

ps:wait

run

setup-app

version

`apply-template`

`build-image`

`cleanup-images`

`cleanup-stale-apps`

`config`

`copy-image-from-upstream`

`delete`

`deploy-image`

`env`

`exists`

`generate`

`info`

`latest-image`

`logs`

`maintenance`

`maintenance:off`

`maintenance:on`

`maintenance:set-page`

`open`

`open-console`

`promote-app-from-upstream`

`ps`

`ps:restart`

`ps:start`

`ps:stop`

`ps:wait`

`run`

`setup-app`

`version`