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

# Profiles

> Manage authentication and default context across multiple organizations and environments.

Profiles store authentication credentials and default context (organization and GVC) for the Control Plane CLI. They enable you to switch between different environments and accounts without re-authenticating.

## Why use profiles

<CardGroup cols={2}>
  <Card title="Multiple orgs and environments" icon="layer-group">
    Separate profiles for each org (dev, staging, production)
  </Card>

  <Card title="Multiple accounts" icon="users">
    Switch between user and service accounts easily
  </Card>

  <Card title="Secure credentials" icon="key">
    Store tokens in a profile instead of passing them with every command
  </Card>

  <Card title="CI/CD friendly" icon="robot">
    Create dedicated profiles for automation
  </Card>
</CardGroup>

## Working with profiles

### List all profiles

```bash theme={null}
cpln profile get
```

### View a specific profile

```bash theme={null}
cpln profile get <profile-name>
```

### Create a new profile

<Tabs>
  <Tab title="Interactive login">
    ```bash theme={null}
    cpln login <profile-name>
    ```

    This creates a profile, authenticates via browser, and sets the profile as the default.

    <Note>
      The profile name is optional. If omitted, the CLI creates or updates the `default` profile.
    </Note>
  </Tab>

  <Tab title="Service account token">
    ```bash theme={null}
    cpln profile create <profile-name> --token <token> --org <org-name>
    ```

    Set default GVC and mark as default profile:

    ```bash theme={null}
    cpln profile create <profile-name> --token <token> --org <org-name> --gvc <gvc-name> --default
    ```

    <Tip>
      Use `--default` to set the profile as the default immediately. This is equivalent to running `cpln profile set-default <profile-name>` after creation.
    </Tip>

    <Warning>
      When using `--token` with a service account key, the profile will not have a default GVC unless you explicitly set it with `--gvc`. Always include `--gvc <gvc-name>` when updating an existing profile if your workflow requires a default GVC.
    </Warning>
  </Tab>
</Tabs>

### Set default profile

```bash theme={null}
cpln profile set-default <profile-name>
```

All subsequent commands will use this profile unless overridden with `--profile`.

<Tip>
  You can also use `--default` with `cpln profile create` or `cpln profile update` to set the profile as default in a single command.
</Tip>

### Update a profile

Update the organization, GVC, or default status for a profile and set it as the default:

```bash theme={null}
cpln profile update <profile-name> --org <new-org> --gvc <new-gvc> --default
```

### Clear default context

Remove the default organization or GVC from a profile by passing an empty string:

<CodeGroup>
  ```bash Remove default org theme={null}
  cpln profile update <profile-name> --org ""
  ```

  ```bash Remove default GVC theme={null}
  cpln profile update <profile-name> --gvc ""
  ```
</CodeGroup>

<Warning>
  Removing the default organization from a profile also removes the default GVC, since the GVC is tied to a specific organization.
</Warning>

### Delete a profile

```bash theme={null}
cpln profile delete <profile-name>
```

<Warning>
  Deleting a profile removes stored credentials. You'll need to re-authenticate to access that account.
</Warning>

## Profile properties

Each profile stores authentication and configuration settings that apply to all CLI commands.

### Context properties

| Property     | Flag    | Description                                    |
| ------------ | ------- | ---------------------------------------------- |
| Organization | `--org` | Default org for all commands                   |
| GVC          | `--gvc` | Default GVC for workload and identity commands |

### Output properties

| Property      | Flag       | Description                                      | Default |
| ------------- | ---------- | ------------------------------------------------ | ------- |
| Output format | `--output` | `text`, `json`, `yaml`, `json-slim`, `yaml-slim` | `text`  |
| Color         | `--color`  | Enable colored output (`true`/`false`)           | `true`  |
| Timestamps    | `--ts`     | Timestamp format: `iso`, `local`, `age`          | `age`   |
| Max records   | `--max`    | Maximum records to display                       | `50`    |

### Request properties

| Property | Flag         | Description                            | Default               |
| -------- | ------------ | -------------------------------------- | --------------------- |
| Token    | `--token`    | Authentication token                   | Set via login         |
| Endpoint | `--endpoint` | API endpoint URL                       | `https://api.cpln.io` |
| Insecure | `--insecure` | Skip TLS verification (`true`/`false`) | `false`               |

Update any property with:

```bash theme={null}
cpln profile update <profile-name> --<property> <value>
```

<CodeGroup>
  ```bash Set output format theme={null}
  cpln profile update my-profile --output json
  ```

  ```bash Set multiple properties theme={null}
  cpln profile update my-profile --org my-org --gvc my-gvc --output yaml --color false
  ```
</CodeGroup>

## Override context

### Override profile context

Override defaults for a single command:

<CodeGroup>
  ```bash Override profile theme={null}
  cpln <command> --profile <profile-name>
  ```

  ```bash Override org theme={null}
  cpln <command> --org <org-name>
  ```

  ```bash Override GVC theme={null}
  cpln <command> --gvc <gvc-name>
  ```

  ```bash Override multiple theme={null}
  cpln <command> --profile <profile-name> --org <org-name> --gvc <gvc-name>
  ```
</CodeGroup>

## Environment variable overrides

Set these environment variables to override profile defaults:

* `CPLN_PROFILE` - The profile name that will become the default
* `CPLN_TOKEN` - Authentication token
* `CPLN_ORG` - Default organization
* `CPLN_GVC` - Default GVC

<CodeGroup>
  ```bash Set profile theme={null}
  export CPLN_PROFILE=production
  ```

  ```bash Set token theme={null}
  export CPLN_TOKEN=your-token-here
  ```

  ```bash Set org and GVC theme={null}
  export CPLN_ORG=my-org
  export CPLN_GVC=my-gvc
  ```
</CodeGroup>

## View profile token

Display the token for a profile (useful for debugging or CI/CD setup):

```bash theme={null}
cpln profile token <profile-name>
```

<Warning>
  Tokens are sensitive credentials. Do not share them or commit them to version control.
</Warning>

## Profile best practices

<AccordionGroup>
  <Accordion title="Use descriptive profile names">
    Name profiles by environment or purpose:

    * `dev`, `staging`, `production`
    * `org1-prod`, `org2-staging`
    * `ci`, `local-dev`
  </Accordion>

  <Accordion title="Set default org and GVC in profiles">
    Reduce the need for `--org` and `--gvc` flags by setting defaults:

    ```bash theme={null}
    cpln profile update <profile-name> --org <org-name> --gvc <gvc-name>
    ```
  </Accordion>

  <Accordion title="Verify profile before mutating operations">
    Always check your active profile before running destructive commands:

    ```bash theme={null}
    cpln profile get
    ```

    Look for the profile marked as default with a star `*`.
  </Accordion>

  <Accordion title="Use dedicated profiles for CI/CD">
    First, set your environment variables:

    ```bash theme={null}
    export CPLN_TOKEN=<service-account-token>
    export CPLN_ORG=<org-name>
    export CPLN_GVC=<gvc-name>
    ```

    Then create a profile and set it as default:

    ```bash theme={null}
    cpln profile create ci --default
    ```

    The CLI automatically uses the environment variables for authentication and context.

    See [CI/CD usage](/cli-reference/ci-cd-development/ci-cd) for details.
  </Accordion>
</AccordionGroup>

## Common pitfalls

<Warning>
  **Wrong context**: Always verify the active profile before running commands that create or modify resources. Use `cpln profile get` and check the active button.
</Warning>

<Warning>
  **Service account tokens and GVC**: When creating or updating a profile with `--token` using a service account key, the default GVC on the profile is removed. Always include `--gvc <gvc-name>` on profile update to avoid "GVC required" errors.
</Warning>

<Warning>
  **Multi-org developers**: Explicitly pass `--org` and `--gvc` when switching contexts in scripts to avoid unintended changes.
</Warning>

<Warning>
  **CI runners**: Store tokens securely in your CI/CD platform's secret manager. Never hardcode tokens in scripts or configuration files.
</Warning>

## Next steps

<CardGroup cols={2}>
  <Card title="Common Options" href="/cli-reference/using-cli/common-options" icon="sliders">
    Learn about all shared CLI flags
  </Card>

  <Card title="CI/CD Setup" href="/cli-reference/ci-cd-development/ci-cd" icon="code">
    Configure profiles for automation
  </Card>
</CardGroup>