{ /* Automatically Generated */}

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.
cpflow apply-template redis -a $APP_NAME

# Applies several templates (practically creating full app).
cpflow 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

cpflow 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

cpflow cleanup-images -a $APP_NAME

`cleanup-stale-apps`

Deletes the whole app (GVC with all workloads, all volumesets and all images) for all stale apps
Also unbinds the app from the secrets policy, as long as both the identity and the policy exist (and are bound)
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

cpflow cleanup-stale-apps -a $APP_NAME

`config`

Displays config for each app or a specific app

# Shows the config for each app.
cpflow config

# Shows the config for a specific app.
cpflow 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.
cpflow copy-image-from-upstream -a $APP_NAME --upstream-token $UPSTREAM_TOKEN

# Copies a specific image from the source org to the current org.
cpflow 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
Also unbinds the app from the secrets policy, as long as both the identity and the policy exist (and are bound)
Will ask for explicit user confirmation
Runs a pre-deletion hook before the app is deleted if hooks.pre_deletion is specified in the .controlplane/controlplane.yml file
If the hook exits with a non-zero code, the command will stop executing and also exit with a non-zero code
Use --skip-pre-deletion-hook to skip the hook if specified in controlplane.yml

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

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

`deploy-image`

Deploys the latest image to app workloads
Runs a release script before deploying if release_script is specified in the .controlplane/controlplane.yml file and --run-release-phase is provided
The release script is run in the context of cpflow run with the latest image
If the release script exits with a non-zero code, the command will stop executing and also exit with a non-zero code

cpflow deploy-image -a $APP_NAME

`doctor`

Runs validations

# Runs all validations that don't require additional options by default.
cpflow doctor

# Runs config validation.
cpflow doctor --validations config

# Runs templates validation (requires app).
cpflow doctor --validations templates -a $APP_NAME

`env`

Displays app-specific environment variables

cpflow env -a $APP_NAME

`exists`

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

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

`generate`

Creates base Control Plane config and template files

# Creates .controlplane directory with Control Plane config and other templates
cpflow 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`).
cpflow info

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

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

`latest-image`

Displays the latest image name

cpflow 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`).
cpflow logs -a $APP_NAME

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

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

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

# Uses a different loopback window.
cpflow 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

cpflow 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

cpflow 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

cpflow 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')

cpflow 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`).
cpflow open -a $APP_NAME

# Opens the endpoint of a specific workload.
cpflow 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

cpflow 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 cpflow copy-image-from-upstream to copy the latest image from upstream
- Runs cpflow deploy-image to deploy the image
- If .controlplane/controlplane.yml includes the release_script, cpflow deploy-image will use the --run-release-phase option
- If the release script exits with a non-zero code, the command will stop executing and also exit with a non-zero code

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

`ps`

Shows running replicas in app

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

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

`ps:restart`

Forces redeploy of workloads in app

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

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

`ps:start`

Starts workloads in app

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

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

`ps:stop`

Stops workloads in app

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

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

# Stops a specific replica of a workload.
cpflow 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.
cpflow ps:wait -a $APP_NAME

# Waits for a specific workload in app.
cpflow 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 overridden 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 overridden through --terminal-size)
By default, all jobs use a CPU size of 1 (1 core) and a memory size of 2Gi (2 gibibytes) (can be configured through runner_job_default_cpu and runner_job_default_memory in controlplane.yml, and also overridden per job through --cpu and --memory)
By default, the job is stopped if it takes longer than 6 hours to finish (can be configured though runner_job_timeout in controlplane.yml)

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

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

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

# Runs non-interactive command, outputs logs, exits with the exit code of the command and stops job.
cpflow 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
cpflow run -a $APP_NAME --detached -- rails db:migrate

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

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

# Uses a different workload than `one_off_workload` from `.controlplane/controlplane.yml`.
cpflow 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.
cpflow run -a $APP_NAME --use-local-token -- bash

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

# Replaces the existing Dockerfile entrypoint.
cpflow 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 or staging (to update workloads for those, use 'cpflow apply-template' instead)
Configures app to have org-level secrets with default name "{APP_PREFIX}-secrets" using org-level policy with default name "{APP_PREFIX}-secrets-policy" (names can be customized, see docs)
Creates identity for secrets if it does not exist
Use --skip-secrets-setup to prevent the automatic setup of secrets, or set it through skip_secrets_setup in the .controlplane/controlplane.yml file
Runs a post-creation hook after the app is created if hooks.post_creation is specified in the .controlplane/controlplane.yml file
If the hook exits with a non-zero code, the command will stop executing and also exit with a non-zero code
Use --skip-post-creation-hook to skip the hook if specified in controlplane.yml

cpflow setup-app -a $APP_NAME

`version`

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

cpflow 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`

`doctor`

`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

doctor

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`

`doctor`

`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`