### Example package.json with index.js or server.js in root

Source: https://docs.controlplane.com/guides/buildpacks

A package.json example where the Node.js start command is implicitly handled by the buildpack.

```json
{
  "name": "my-app",
  "engines": {
    "node": "20.x"
  }
}
```

--------------------------------

### Example package.json with start script

Source: https://docs.controlplane.com/guides/buildpacks

Specifies the start command for a Node.js application within package.json.

```json
{
  "name": "my-app",
  "scripts": {
    "start": "node src/app.js"
  },
  "engines": {
    "node": "20.x"
  }
}
```

--------------------------------

### Setup GCP Cloud Account

Source: https://docs.controlplane.com/mcp/examples

Get the setup guide for a GCP cloud account. This requires specifying the provider and the GCP project ID.

```text
Get the setup guide for creating a GCP cloud account with:
  - Provider: gcp
  - Project ID: my-gcp-project-123
```

--------------------------------

### Example C#/.NET Procfile

Source: https://docs.controlplane.com/guides/buildpacks

Optional Procfile for C#/.NET applications to explicitly set the start command, recommended for multi-project solutions.

```procfile
web: dotnet MyApp.dll
```

--------------------------------

### Setup AWS Cloud Account

Source: https://docs.controlplane.com/mcp/examples

Get the setup guide for an AWS cloud account. This involves specifying the provider, account name, AWS account ID, and IAM role ARN.

```text
Get the setup guide for creating an AWS cloud account with:
  - Provider: aws
  - Cloud account name: my-aws-prod
  - AWS account ID: 123456789012
  - Role ARN: arn:aws:iam::123456789012:role/cpln-my-org
```

--------------------------------

### Prometheus Ready Replicas Query Example

Source: https://docs.controlplane.com/reference/workload/autoscaling

Example PromQL query to get the count of ready replicas for a workload. Useful for scaling down when fewer replicas are ready than expected.

```bash
sum(workload_ready_replicas{
  gvc="my-gvc",
  workload="backend-service"
})
```

--------------------------------

### Install Control Plane Provider (Go)

Source: https://docs.controlplane.com/iac/pulumi

Install the Control Plane Pulumi provider for Go projects.

```bash
go get github.com/pulumiverse/pulumi-cpln/sdk/go/cpln
```

--------------------------------

### Apply Example Application Manifest

Source: https://docs.controlplane.com/guides/cli/cpln-operator

Apply the example ArgoCD Application manifest to your Kubernetes cluster.

```bash
kubectl apply -f example-app.yaml
```

--------------------------------

### Define Application Start Command

Source: https://docs.controlplane.com/guides/buildpacks

Specify how your application should be started by the platform. Place this file in the project root.

```text
web: <start-command>
```

--------------------------------

### Example with specific org and gvc

Source: https://docs.controlplane.com/cli-reference/commands/workload

Demonstrates running a command with explicit organization and global virtual cloud settings.

```bash
cpln workload run --org demo-cpln-organization --gvc demo-gvc -- ls -al
```

--------------------------------

### Create and Initialize Pulumi Project (Go)

Source: https://docs.controlplane.com/quickstart/sample-application

Create a new directory and initialize a Pulumi project for Go. Follow the terminal prompts to complete setup.

```bash
mkdir cpln-quickstart && cd cpln-quickstart
pulumi new go
```

--------------------------------

### Get Location Installation Script

Source: https://docs.controlplane.com/cli-reference/commands/location

Obtain the installation script for a BYOK location. This command must be performed before a specified timestamp.

```none
cpln location install <ref> [OPTIONS]
```

```bash
cpln location install demo-byok-location --org demo-cpln-organization
```

```text
# this commmand must be performed before 2024-7-16 22:42:00
kubectl apply -f 'https://byok-api.cpln.io/install/download/xxxxxxxxxx/byok-agent.k8s.yaml'
```

--------------------------------

### Install PostgreSQL Template with Specific Version and Values

Source: https://docs.controlplane.com/template-catalog/install-manage/cli

Example of installing the PostgreSQL template version 3.2.0 using a values.yaml file.

```bash
cpln helm install my-postgres oci://ghcr.io/controlplane-com/templates/postgres \
  --version 3.2.0 \
  -f values.yaml
```

--------------------------------

### Create and Initialize Pulumi Go Project

Source: https://docs.controlplane.com/quickstart/quick-start-1-deploy-workload

Set up a new Pulumi project for Go and install the Control Plane provider.

```bash
mkdir cpln-quickstart && cd cpln-quickstart
pulumi new go
go get github.com/pulumiverse/pulumi-cpln/sdk/go/cpln
```

--------------------------------

### Example Image Build with Push and Buildpack Flags

Source: https://docs.controlplane.com/cli-reference/commands/image

This example demonstrates building an image named 'demo-image:1', pushing it to 'demo-cpln-organization', and passing a build-time environment variable `CPLN_IMAGE_BUILD=true` to the `pack` binary.

```bash
cpln image build demo-image:1 --push demo-cpln-organization -- --env CPLN_IMAGE_BUILD=true
```

--------------------------------

### Get All Users Example

Source: https://docs.controlplane.com/cli-reference/commands/user

This example demonstrates how to retrieve all users in a specified organization. It uses the '--org' flag to set the organization context.

```bash
cpln user get --org demo-cpln-organization
```

```text
+-----------------------------+---------------------+-----------------------+-------------+---------+------------------------------------------+
|ID                           |FULL NAME            |EMAIL                  |CREATED      |IDP      |TAGS                                      |
|-----------------------------|---------------------|-----------------------|-------------|---------|------------------------------------------|
|rMdL2BFDxEeYQPA5qRYGbLivhVS2 |Kyle Cupp            |kyle@controlplane.com  |2 years ago  |firebase |firebase/sign_in_provider="microsoft.com" |
|3mpcnkfyNhYXdjq8TbLefzXwyfu1 |Majid Abu Rmelah     |majid@controlplane.com |4 months ago |firebase |firebase/sign_in_provider="microsoft.com" |
|HkKCu6TcHIMB8ON8iXayuKw5oop2 |test-128@example.com |test-128@example.com   |5 years ago  |firebase |firebase/sign_in_provider="password"      |
+-----------------------------+---------------------+-----------------------+-------------+---------+------------------------------------------+
```

--------------------------------

### Build and Deploy Workflow Example

Source: https://docs.controlplane.com/guides/push-image

A common workflow combining building and pushing an image using the CLI, which automatically handles authentication.

```bash
# Build and push (Authenticates automatically)
cpln image build --name my-app:v1.2.3 --push

```

--------------------------------

### Example: Create a new agent

Source: https://docs.controlplane.com/cli-reference/commands/agent

Demonstrates creating a new agent named 'demo-agent' with a description and a tag, specifying the organization.

```bash
cpln agent create --name demo-agent --desc demo-agent --tag drink=water --org demo-cpln-organization
```

```json
{
  "agentId": "51dcc109-809d-47b4-b2e7-4222c5bfe2bd",
  "agentLink": "/org/demo-cpln-organization/agent/demo-agent",
  "hubEndpoint": "https://hub.test.cpln.io",
  "registrationToken": "a2zQ1CsVtyAidBuk9sqJBi8FyericIOF5P8XBYN0-A1bnrwOKTzFZWIA/oPwt-4",
  "protocolVersion": "v2"
}
```

--------------------------------

### Get One User Example

Source: https://docs.controlplane.com/cli-reference/commands/user

This example shows how to retrieve a specific user by providing their reference (email in this case) along with the organization context. It uses the '--org' flag to set the organization context.

```bash
cpln user get test-128@example.com --org demo-cpln-organization
```

```text
+-----------------------------+---------------------+---------------------+------------+---------+-------------------------------------+
|ID                           |FULL NAME            |EMAIL                |CREATED     |IDP      |TAGS                                 |
|-----------------------------|---------------------|---------------------|------------|---------|-------------------------------------|
|HkKCu6TcHIMB8ON8iXanyeKw5oop2 |test-128@example.com |test-128@example.com |5 years ago |firebase |firebase/sign_in_provider="password" |
+-----------------------------+---------------------+---------------------+------------+---------+-------------------------------------+
```

--------------------------------

### Example of creating a workload with specific options

Source: https://docs.controlplane.com/cli-reference/commands/workload

Demonstrates creating a workload named 'demo-workload' with a description, tag, and specifying organization and GVC. The output shows the created workload's details.

```bash
cpln workload create --name demo-workload --image gcr.io/knative-samples/helloworld-go --desc demo-workload --tag drink=water --org demo-cpln-organization --gvc demo-gvc-workload
```

```text
+--------------+--------------+------------------+------+--------+-------------------------------------------------------------+--------------+
|NAME          |DESCRIPTION   |GVC               |READY |CREATED |ENDPOINT                                                     |TAGS          |
|--------------|--------------|------------------|------|--------|-------------------------------------------------------------|--------------|
|demo-workload |demo-workload |demo-gvc-workload |      |Now     |https://demo-workload-2qaf1h5bgpgf8.geta3p46gfrsp.t.cpln.app |drink="water" |
+--------------+--------------+------------------+------+--------+-------------------------------------------------------------+--------------+

```

--------------------------------

### Workload Cron Get Example Output

Source: https://docs.controlplane.com/cli-reference/commands/workload

Sample output displaying job execution details for a cron workload.

```text
+-------------------+-----------------+-------------------------------------+-------+----------------------+----------------------+
|WORKLOAD           |LOCATION         |NAME OR COMMAND ID                   |STATUS |START TIME            |COMPLETION TIME       |
|-------------------|-----------------|-------------------------------------|-------|----------------------|----------------------|
|demo-cron-workload |aws-eu-central-1 |ce770d2b-2b7f-4415-b41e-961f161bcd86 |Active |3/30/2024, 3:29:47 AM |3/30/2024, 3:30:14 AM |
+-------------------+-----------------+-------------------------------------+-------+----------------------+----------------------+
```

--------------------------------

### Example: Create Organization

Source: https://docs.controlplane.com/cli-reference/commands/org

Demonstrates the creation of a new organization named 'demo-cpln-organization' with specified account ID and invitee email.

```bash
cpln org create --name demo-cpln-organization --acountId ACCOUNT_ID --invitee EMAIL
```

--------------------------------

### Example JWT Authentication Configuration

Source: https://docs.controlplane.com/reference/workload/jwt-auth

A comprehensive example demonstrating JWT authentication setup. It includes cluster definitions, HTTP filter configuration with providers, audiences, claim mappings, issuer details, and matching rules based on URI prefixes.

```yaml
sidecar:
  envoy:
    clusters:
      - name: cpln_foo
        type: STRICT_DNS
        load_assignment:
          cluster_name: cpln_foo
          endpoints:
            - lb_endpoints:
                - endpoint:
                    address:
                      socket_address:
                        address: foo.com
                        port_value: 443
        transport_socket:
          name: envoy.transport_sockets.tls
    http:
      - name: envoy.filters.http.jwt_authn
        priority: 50
        typed_config:
          '@type': >-
            type.googleapis.com/envoy.extensions.filters.http.jwt_authn.v3.JwtAuthentication
          providers:
            cpln_foo:
              audiences:
                - myaudience
              claim_to_headers:
                - claim_name: user.special
                  header_name: X_SPECIAL_USER
              issuer: https://foo.com/auth
              remote_jwks:
                cache_duration: 5s
                http_uri:
                  cluster: cpln_foo
                  timeout: 5s
                  uri: https://foo.com/auth
          rules:
            - match:
                headers: []
                prefix: /metric
            - match:
                headers: []
                prefix: /
              requires:
                provider_name: cpln_foo
```

--------------------------------

### Create a Global Virtual Cloud (GVC)

Source: https://docs.controlplane.com/quickstart/quick-start-1-deploy-workload

Create a GVC named 'quickstart-gvc' with specified locations in AWS and GCP.

```bash
cpln gvc create quickstart-gvc --locations aws-us-west-2 --locations gcp-us-east1
```

--------------------------------

### Debug in a Cloned Environment

Source: https://docs.controlplane.com/guides/cli/workload/run

A common workflow example: clones a production workload and starts an interactive bash shell for debugging purposes.

```bash
cpln workload run --clone production-api --interactive -- bash
```

--------------------------------

### Deploy Hello World Application (Go)

Source: https://docs.controlplane.com/quickstart/sample-application

Creates a Google Kubernetes Engine (GKE) cluster and deploys a 'Hello World' workload to it. This snippet configures GVC, Workload, containers, and firewall settings.

```go
package main

import (
	"github.com/pulumi/pulumi/sdk/v3/go/pulumi"
	"github.com/pulumiverse/pulumi-cpln/sdk/go/cpln"
)

func main() {
	pulumi.Run(func(ctx *pulumi.Context) error {
		// Create a GVC
		gvc, err := cpln.NewGvc(ctx, "quickstart-gvc", &cpln.GvcArgs{
			Name:        pulumi.String("quickstart-gvc"),
			Description: pulumi.String("Quickstart GVC"),
			Locations: pulumi.StringArray{
				pulumi.String("aws-us-west-2"),
				pulumi.String("gcp-us-east1"),
			},
		})
		if err != nil {
			return err
		}

		// Create a Workload
		workload, err := cpln.NewWorkload(ctx, "hello-world", &cpln.WorkloadArgs{
			Gvc:  gvc.Name,
			Name: pulumi.String("hello-world"),
			Type: pulumi.String("standard"),
			Containers: cpln.WorkloadContainerArray{
				&cpln.WorkloadContainerArgs{
					Name:   pulumi.String("helloworld-go"),
					Image:  pulumi.String("gcr.io/knative-samples/helloworld-go"),
					Cpu:    pulumi.String("50m"),
					Memory: pulumi.String("128Mi"),
					Ports: cpln.WorkloadContainerPortArray{
						&cpln.WorkloadContainerPortArgs{
							Number:   pulumi.Int(8080),
							Protocol: pulumi.String("http"),
						},
					},
				},
			},
			Options: &cpln.WorkloadOptionsArgs{
				CapacityAi:     pulumi.Bool(true),
				TimeoutSeconds: pulumi.Int(5),
				Autoscaling: &cpln.WorkloadOptionsAutoscalingArgs{
					Metric:   pulumi.String("disabled"),
					Target:   pulumi.Int(95),
					MinScale: pulumi.Int(1),
					MaxScale: pulumi.Int(1),
				},
			},
			FirewallSpec: &cpln.WorkloadFirewallSpecArgs{
				External: &cpln.WorkloadFirewallSpecExternalArgs{
					InboundAllowCidrs: pulumi.StringArray{pulumi.String("0.0.0.0/0")},
				},
			},
		})
		if err != nil {
			return err
		}

		// Export the canonical endpoint
		ctx.Export("canonical_endpoint", workload.Statuses.Index(pulumi.Int(0)).CanonicalEndpoint())
		return nil
	})
}

```

--------------------------------

### Control Plane CLI Usage Example

Source: https://docs.controlplane.com/reference/workload/general

Shows how to use the Control Plane CLI to retrieve organization details, assuming the CLI is installed.

```bash
cpln org get ${CPLN_ORG}
```

--------------------------------

### Deploy Hello World Application (C#)

Source: https://docs.controlplane.com/quickstart/sample-application

Creates a Google Kubernetes Engine (GKE) cluster and deploys a 'Hello World' workload to it using C#. This snippet configures GVC, Workload, containers, and firewall settings.

```csharp
using Pulumi;
using Pulumiverse.Cpln;
using Pulumiverse.Cpln.Inputs;
using System.Collections.Generic;

return await Deployment.RunAsync(() =>
{
    // Create a GVC
    var gvc = new Gvc("quickstart-gvc", new GvcArgs
    {
        Name = "quickstart-gvc",
        Description = "Quickstart GVC",
        Locations = new[] { "aws-us-west-2", "gcp-us-east1" }
    });

    // Create a Workload
    var workload = new Workload("hello-world", new WorkloadArgs
    {
        Gvc = gvc.Name,
        Name = "hello-world",
        Type = "standard",
        Containers = new[]
        {
            new WorkloadContainerArgs
            {
                Name = "helloworld-go",
                Image = "gcr.io/knative-samples/helloworld-go",
                Cpu = "50m",
                Memory = "128Mi",
                Ports = new[]
                {
                    new WorkloadContainerPortArgs
                    {
                        Number = 8080,
                        Protocol = "http"
                    }
                }
            }
        },
        Options = new WorkloadOptionsArgs
        {
            CapacityAi = true,
            TimeoutSeconds = 5,
            Autoscaling = new WorkloadOptionsAutoscalingArgs
            {
                Metric = "disabled",
                Target = 95,
                MinScale = 1,
                MaxScale = 1
            }
        },
        FirewallSpec = new WorkloadFirewallSpecArgs
        {
            External = new WorkloadFirewallSpecExternalArgs
            {
                InboundAllowCidrs = new[] { "0.0.0.0/0" }
            }
        }
    });

    // Export the canonical endpoint
    return new Dictionary<string, object?>
    {
        ["canonical_endpoint"] = workload.Statuses.Apply(s => s[0].CanonicalEndpoint)
    };
});

```

--------------------------------

### Helm CLI Command List

Source: https://docs.controlplane.com/cli-reference/commands/helm

Lists available subcommands for managing Helm releases, including get, history, install, list, rollback, template, uninstall, and upgrade.

```bash
Commands:
  cpln helm get                            Download extended information of a named release
  cpln helm history <release>              Fetch release history
  cpln helm install [release] [chart]      Install a release  [aliases: apply]
  cpln helm list                           List releases
  cpln helm rollback <release> [revision]  Roll back a release to a previous revision
  cpln helm template [release] [chart]     Generate cpln resources from a template
  cpln helm uninstall <release>            Uninstall a release  [aliases: destroy, del, delete, un]
  cpln helm upgrade [release] [chart]      Upgrade a release

Options:
  --help  Show help  [boolean]
```

--------------------------------

### Open Application via CLI

Source: https://docs.controlplane.com/quickstart/quick-start-2-deploy-application

Opens the 'my-app' workload in the 'quickstart-gvc' GVC. This command is used after the workload has become ready.

```bash
cpln workload open my-app --gvc quickstart-gvc
```

--------------------------------

### Get GVC by Name using cURL

Source: https://docs.controlplane.com/api-reference/api

Example cURL command to retrieve a GVC by its organization and name. Ensure you replace 'YOUR_TOKEN_HERE', '{org}', and '{name}' with your actual values.

```bash
curl --request GET \
  --url https://api.cpln.io/org/{org}/gvc/{name} \
  --header 'Authorization: YOUR_TOKEN_HERE'
```

--------------------------------

### Create and Initialize Pulumi Project (Python)

Source: https://docs.controlplane.com/quickstart/sample-application

Create a new directory and initialize a Pulumi project for Python. Follow the terminal prompts to complete setup.

```bash
mkdir cpln-quickstart && cd cpln-quickstart
pulumi new python
```

--------------------------------

### Autocomplete API Endpoint

Source: https://docs.controlplane.com/cli-reference/using-cli/shell-completion

Suggests the API endpoint URL when completing the `--endpoint` flag. For example, `cpln workload get --endpoint <Tab>` will suggest `https://api.cpln.io`.

```bash
cpln workload get --endpoint <Tab>
# https://api.cpln.io
```

--------------------------------

### Install Control Plane Provider (uv)

Source: https://docs.controlplane.com/quickstart/sample-application

Activate the virtual environment and install the Control Plane provider using uv.

```bash
source .venv/bin/activate
uv add pulumiverse-cpln
```

--------------------------------

### Autocomplete Commands and Subcommands

Source: https://docs.controlplane.com/cli-reference/using-cli/shell-completion

Use tab completion to discover available subcommands for a given command. For example, typing `cpln workload <Tab>` will list subcommands like `get`, `create`, and `delete`.

```bash
cpln workload <Tab>
# get  create  delete  update  patch  ...
```

--------------------------------

### Deploy with natural language

Source: https://docs.controlplane.com/mcp/ai-plugin

This example shows how to use natural language to deploy a Compose file, including autoscaling and idle scaling configurations.

```text
Deploy this Compose file to my GVC "staging" — autoscale on requests
per second, scale to zero when idle, and give me the public URL.
```

--------------------------------

### Kubernetes Service port name prefix

Source: https://docs.controlplane.com/guides/cli/cpln-convert

The converter checks if any Service port targeting this container has a name with a protocol prefix. For example, a name starting with "grpc" infers the gRPC protocol.

```yaml
spec:
  ports:
    - name: grpc-api  # "grpc" prefix → gRPC protocol
      port: 50051
```

--------------------------------

### Install Control Plane Provider (pip)

Source: https://docs.controlplane.com/quickstart/sample-application

Activate the virtual environment and install the Control Plane provider using pip.

```bash
source venv/bin/activate
pip install pulumiverse-cpln
```

--------------------------------

### Retrieve details of a specific volume from a volume set

Source: https://docs.controlplane.com/cli-reference/commands/volumeset

Use this command to get the current details of a volume within a volume set. The output displays the volume's location, index, and lifecycle status, which is 'Bound' in the example.

```bash
cpln volumeset volume get demo-volume-set
```

```text
+-----------------+-------------+----------+
|LOCATION         |VOLUME INDEX |LIFECYCLE |
|-----------------|-------------|----------|
|aws-eu-central-1 |0            |Bound     |
+-----------------+-------------+----------+
```

--------------------------------

### Initialize Pulumi Project (Go)

Source: https://docs.controlplane.com/iac/pulumi

Initialize a new Pulumi project using the Go template.

```bash
pulumi new go
```

--------------------------------

### Example: Creating an Organization with rest create

Source: https://docs.controlplane.com/cli-reference/commands/rest

Demonstrates how to use the 'rest create' command to create an organization using a JSON file. The command performs a POST request with the file's content and then a GET request on the created resource.

```bash
cpln rest create /org --file create-org.json
```

```text
The metadata contained within the JSON file will be performed against the referenced path as a POST request.

If successful, a GET request will be performed on the resource and outputted to stdout.
```

--------------------------------

### Install shell completion

Source: https://docs.controlplane.com/cli-reference/commands/misc

Installs shell completion for your local profile. The shell needs to be restarted after installation.

```bash
cpln misc install-completion
```

```text
Running the command will prompt the user with a few questions. Once compelete, the completion functionality
will be installed. The shell will need to be restarted.
```

--------------------------------

### Query Policies by Description

Source: https://docs.controlplane.com/cli-reference/commands/policy

This example demonstrates how to find policies based on their description. It uses the `--match any` flag and specifies the description property.

```bash
cpln policy query --match any --prop description="demo-policy" --org demo-cpln-organization
```

```text
+------------+------------+--------------+------------+--------+--------+--------------+
|NAME        |DESCRIPTION |CREATED       |TARGET KIND |MATCHES |ORIGIN  |TAGS          |
|------------|------------|--------------|------------|--------|--------|--------------|
|demo-policy |demo-policy |6 minutes ago |org         |all     |default |drink="water" |
+------------+------------+--------------+------------+--------+--------+--------------+
```

--------------------------------

### Install Helm CLI

Source: https://docs.controlplane.com/guides/cli/cpln-operator

Install the Helm CLI using package managers or a script. Ensure Helm v3.0+ is installed.

```bash
# macOS
brew install helm

# Linux
curl https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3 | bash

# Windows
choco install kubernetes-helm
```

--------------------------------

### Install Rosetta on macOS (Apple Silicon)

Source: https://docs.controlplane.com/cli-reference/using-cli/shell-completion

On macOS with Apple Silicon, install Rosetta before attempting to install shell completion if it fails.

```bash
softwareupdate --install-rosetta
cpln misc install-completion
```

--------------------------------

### Install CLI with Homebrew

Source: https://docs.controlplane.com/cli-reference/get-started/quickstart

Install the Control Plane CLI using Homebrew on macOS or Linux. Ensure Homebrew is installed first.

```bash
brew tap controlplane-com/cpln && brew install cpln
```

--------------------------------

### Example C#/.NET .csproj

Source: https://docs.controlplane.com/guides/buildpacks

An example .csproj file for a .NET web project. Ensure the TargetFramework is compatible.

```xml
<Project Sdk="Microsoft.NET.Sdk.Web">
  <PropertyGroup>
    <TargetFramework>net9.0</TargetFramework>
  </PropertyGroup>
</Project>
```

--------------------------------

### Initialize Pulumi Project (Python)

Source: https://docs.controlplane.com/iac/pulumi

Initialize a new Pulumi project using the Python template.

```bash
pulumi new python
```