<!-- NOTE: This file is automatically generated by running `script/generate_commands_docs`. Do NOT edit it manually. -->

## 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_GVC      - basically GVC or app name
APP_LOCATION - default location
APP_ORG      - organization
APP_IMAGE    - will use latest app image
```

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

# Applies several templates (practically creating full app).
cpl apply-template gvc 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`

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

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

```sh
cpl cleanup-stale-apps -a $APP_NAME
```

### `config`

- Displays config for each app or a specific app

```sh
# 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 org must be specified through `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

```sh
# 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)
- Will ask for explicit user confirmation

```sh
cpl delete -a $APP_NAME
```

### `deploy-image`

- Deploys the latest image to app workloads

```sh
cpl deploy-image -a $APP_NAME
```

### `env`

- Displays app-specific environment variables

```sh
cpl env -a $APP_NAME
```

### `exists`

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

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

### `generate`

Creates base Control Plane config and template files

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

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

```sh
cpl latest-image -a $APP_NAME
```

### `logs`

- Light wrapper to display tailed raw logs for app/workload syntax

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

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

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

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

```sh
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')

```sh
cpl maintenance:set-page PAGE_URL -a $APP_NAME
```

### `open`

- Opens the app endpoint URL in the default browser

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

```sh
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 a release script if specified through `release_script` in the `.controlplane/controlplane.yml` file
  - Runs `cpl deploy-image` to deploy the image

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

### `ps`

- Shows running replicas in app

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

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

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

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

### `ps:wait`

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

```sh
# 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_** replicas (analog of `heroku run`)
- Uses `Standard` workload type and `cpln exec` as the execution method, with CLI streaming
- 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`)

> **IMPORTANT:** Useful for development where it's needed for interaction, and where network connection drops and
> task crashing are tolerable. For production tasks, it's better to use `cpl run:detached`.

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

# Need to quote COMMAND if setting ENV value or passing args.
cpl run 'LOG_LEVEL=warn rails db:migrate' -a $APP_NAME

# COMMAND may also be passed at the end.
cpl run -a $APP_NAME -- 'LOG_LEVEL=warn rails db:migrate'

# Runs command, displays output, and exits shell.
cpl run ls / -a $APP_NAME
cpl run rails db:migrate:status -a $APP_NAME

# Runs command and keeps shell open.
cpl run rails c -a $APP_NAME

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

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

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

### `run:cleanup`

- Deletes stale run workloads for an app
- Workloads are considered stale based on how many days since created
- `stale_run_workload_created_days` in the `.controlplane/controlplane.yml` file specifies the number of days after created that the workload is considered stale
- Works for both interactive workloads (created with `cpl run`) and non-interactive workloads (created with `cpl run:detached`)
- Will ask for explicit user confirmation of deletion

```sh
cpl run:cleanup -a $APP_NAME
```

### `run:detached`

- Runs one-off **_non-interactive_** replicas (close analog of `heroku run:detached`)
- Uses `Cron` workload type with log async fetching
- Implemented with only async execution methods, more suitable for production tasks
- Has alternative log fetch implementation with only JSON-polling and no WebSockets
- Less responsive but more stable, useful for CI tasks

```sh
cpl run:detached rails db:prepare -a $APP_NAME

# Need to quote COMMAND if setting ENV value or passing args.
cpl run:detached 'LOG_LEVEL=warn rails db:migrate' -a $APP_NAME

# COMMAND may also be passed at the end.
cpl run:detached -a $APP_NAME -- 'LOG_LEVEL=warn rails db:migrate'

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

# Uses a different workload than `one_off_workload` from `.controlplane/controlplane.yml`.
cpl run:detached rails db:migrate:status -a $APP_NAME -w other-workload

# Overrides remote CPLN_TOKEN env variable with local token.
# Useful when superuser rights are needed in remote container.
cpl run:detached rails db:migrate:status -a $APP_NAME --use-local-token
```

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

```sh
cpl setup-app -a $APP_NAME
```

### `version`

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

```sh
cpl version
```