> ## Documentation Index
> Fetch the complete documentation index at: https://docs.controlplane.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Install and Manage using the CLI

> Install, upgrade, and manage Control Plane Template Catalog releases using the CLI and Helm. Covers prerequisites, installation, listing revisions, and uninstalling templates.

## Prerequisites

<AccordionGroup>
  <Accordion title="CLI installed">
    Install the Control Plane CLI. See [Installation](/cli-reference/installation).
  </Accordion>

  <Accordion title="Helm installed">
    Install [Helm](https://helm.sh/docs/intro/install/) (v3 or later).
  </Accordion>
</AccordionGroup>

## Install a Template

<Steps>
  <Step title="Choose a Template">
    Browse the [Template Catalog](/template-catalog/overview) to find the template you want to deploy.

    * Each template page includes a full configuration reference and a snippet of the default `values.yaml` file.
  </Step>

  <Step title="Configure Values">
    Create a `values.yaml` file to customize the template for your environment. This can include settings such as resource limits, replica counts, and any template-specific options.

    <Note>
      Your values file must follow the same structure and format as the template's default values file.
    </Note>
  </Step>

  <Step title="Install the Release">
    Run the following command to install the template as a release:

    ```bash theme={null}
    cpln helm install <RELEASE_NAME> oci://ghcr.io/controlplane-com/templates/<TEMPLATE_NAME> \
      --version <VERSION> \
      -f values.yaml \
      --state-tag cpln/marketplace=true \
      --state-tag cpln/marketplace-template=<TEMPLATE_NAME> \
      --state-tag cpln/marketplace-template-version=<VERSION> \
      --state-tag cpln/marketplace-gvc=<GVC>
    ```

    Replace:

    * `<RELEASE_NAME>` — A unique name for this installation.
    * `<TEMPLATE_NAME>` — The name of the template (example: `postgres`).
    * `<VERSION>` — The version to install (example: `3.2.0`). Omitting `--version` defaults to the latest version.
    * `<GVC>`: The GVC the release installs into, taken from `--gvc` or from your profile's default GVC.

    <Note>
      Omitting `-f values.yaml` will deploy the template using its default values.
    </Note>

    **Template Catalog state tags**

    The four `--state-tag` flags mark the release as a Template Catalog release. They are written to the release state secret, not to the resources the release creates.

    | State tag | Value |
    | - | - |
    | `cpln/marketplace` | Always `true`. This tag alone is what the Console checks to tell a Template Catalog release from a plain Helm release. |
    | `cpln/marketplace-template` | The template name, for example `postgres`. |
    | `cpln/marketplace-template-version` | The template version installed, for example `3.2.0`. |
    | `cpln/marketplace-gvc` | The GVC the release installs into. Omit this tag entirely for a template that creates its own GVC. |

    Install without these tags and the release is still created and still works, but:

    * The Console lists it under **Helm Releases** instead of the Template Catalog's **Releases** page, so the upgrade, revision history, and rollback screens built for catalog templates never see it.
    * The Terraform `cpln_catalog_template` resource and the Pulumi `CatalogTemplate` resource will not manage it, because both require `cpln/marketplace`, `cpln/marketplace-template`, and `cpln/marketplace-template-version` to all be present.

    Installing from the Console applies these tags for you. They are only your responsibility when you install from the CLI.

    Pin `--version` on a tagged install. Omitting it installs the latest version, which leaves you with no version number to put in `cpln/marketplace-template-version`.

    **Example — install PostgreSQL v3.2.0 with custom values:**

    ```bash theme={null}
    cpln helm install my-postgres oci://ghcr.io/controlplane-com/templates/postgres \
      --version 3.2.0 \
      -f values.yaml \
      --state-tag cpln/marketplace=true \
      --state-tag cpln/marketplace-template=postgres \
      --state-tag cpln/marketplace-template-version=3.2.0 \
      --state-tag cpln/marketplace-gvc=my-gvc
    ```

    You can also override individual values inline using `--set` without a values file:

    ```bash theme={null}
    cpln helm install my-pg oci://ghcr.io/controlplane-com/templates/postgres \
      --version 3.2.0 \
      --set config.database=myapp \
      --set config.username=myuser \
      --set pgbouncer.enabled=true
    ```

    `-f` and `--set` can also be combined — `--set` values take precedence over those in the file.

    The `--set` snippet above leaves the four `--state-tag` flags out only to keep the example short. Pass them on every install, whether you supply values through `-f`, through `--set`, or not at all.
  </Step>
</Steps>

## Manage a Template

### View Releases

List all installed releases in your organization:

```bash theme={null}
cpln helm list
```

### Release Details

View full details for a specific release, including the manifest, values, and notes:

```bash theme={null}
cpln helm get all <RELEASE_NAME>
```

You can also retrieve individual pieces of release information:

```bash theme={null}
# View the rendered manifest
cpln helm get manifest <RELEASE_NAME>

# View the configured values
cpln helm get values <RELEASE_NAME> --all

# View release notes
cpln helm get notes <RELEASE_NAME>
```

### Upgrade

To upgrade a release with new values or a new template version:

```bash theme={null}
cpln helm upgrade <RELEASE_NAME> oci://ghcr.io/controlplane-com/templates/<TEMPLATE_NAME> \
  --version <VERSION> \
  -f values.yaml \
  --state-tag cpln/marketplace-template-version=<VERSION>
```

State tags carry over from the previous revision, so `cpln/marketplace`, `cpln/marketplace-template`, and `cpln/marketplace-gvc` do not need repeating. Pass `cpln/marketplace-template-version` again on every upgrade that changes the version, so the Console and the Terraform provider report the version that is actually installed.

<Note>
  Any workloads affected by the change will roll out new deployments. Unchanged items will not be redeployed.
</Note>

Some templates created their own GVC in their 1.x versions and install into an existing GVC from 2.x onward. Upgrade such a release with `--gvc` set to the GVC the release already lives in:

```bash theme={null}
cpln helm upgrade <RELEASE_NAME> oci://ghcr.io/controlplane-com/templates/<TEMPLATE_NAME> \
  --version <VERSION> \
  --gvc <THE_GVC_THE_RELEASE_LIVES_IN> \
  -f values.yaml \
  --state-tag cpln/marketplace-template-version=<VERSION>
```

The GVC stays exactly as it is, and the release stops managing it, so a later uninstall leaves it alone. An upgrade that points `--gvc` at a different GVC is refused before anything is written, because the release's workloads, volume sets, and identities would be stranded in the GVC it leaves. See [Moving a release between GVCs](/guides/cpln-helm#moving-a-release-between-gvcs).

### Template Preview

Generate a preview of the resources that will be created without deploying:

```bash theme={null}
cpln helm template <RELEASE_NAME> oci://ghcr.io/controlplane-com/templates/<TEMPLATE_NAME> \
  --version <VERSION> \
  -f values.yaml
```

### Revisions

View the revision history for a release:

```bash theme={null}
cpln helm history <RELEASE_NAME>
```

Roll back to a previous revision:

```bash theme={null}
# Roll back to the previous revision
cpln helm rollback <RELEASE_NAME>

# Roll back to a specific revision
cpln helm rollback <RELEASE_NAME> <REVISION_NUMBER>
```

## Uninstall a Template

Remove all resources created by the release and delete the release state:

```bash theme={null}
cpln helm uninstall <RELEASE_NAME>
```

A GVC the release created is deleted with it, unless it still holds resources the release does not own or the release's newest revision no longer declares it. In both cases the GVC is left in place and the CLI prints the reason together with the `cpln gvc delete` command that removes it by hand. See [Uninstall a release](/guides/cpln-helm#uninstall-a-release).

## Related

<CardGroup cols={2}>
  <Card title="Templates Repository" icon="github" href="https://github.com/controlplane-com/templates">
    Source files, default values, and chart definitions for all templates.
  </Card>

  <Card title="Template Packages" icon="box" href="https://github.com/orgs/controlplane-com/packages?repo_name=templates">
    OCI packages for all templates, hosted on the GitHub Container Registry.
  </Card>

  <Card title="Manage Helm Releases" href="/guides/cpln-helm" icon="cube">
    Deploy and manage Control Plane resources using Helm charts with the cpln helm command.
  </Card>
</CardGroup>