Skip to main content

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

Multiple orgs and environments

Separate profiles for each org (dev, staging, production)

Multiple accounts

Switch between user and service accounts easily

Secure credentials

Store tokens in a profile instead of passing them with every command

CI/CD friendly

Create dedicated profiles for automation

​
Working with profiles

​
List all profiles

cpln profile get

​
View a specific profile

cpln profile get <profile-name>

​
Create a new profile

cpln login <profile-name>
This creates a profile, authenticates via browser, and sets the profile as the default.
The profile name is optional. If omitted, the CLI creates or updates the default profile.

​
Set default profile

cpln profile set-default <profile-name>
All subsequent commands will use this profile unless overridden with --profile.
You can also use --default with cpln profile create or cpln profile update to set the profile as default in a single command.

​
Update a profile

Update the organization, GVC, or default status for a profile and set it as the default: 
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: 
cpln profile update <profile-name> --org ""
Removing the default organization from a profile also removes the default GVC, since the GVC is tied to a specific organization.

​
Delete a profile

cpln profile delete <profile-name>
Deleting a profile removes stored credentials. You’ll need to re-authenticate to access that account.

​
Profile properties

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

​
Context properties

PropertyFlagDescription
Organization--orgDefault org for all commands
GVC--gvcDefault GVC for workload and identity commands

​
Output properties

PropertyFlagDescriptionDefault
Output format--outputtext, json, yaml, json-slim, yaml-slimtext
Color--colorEnable colored output (true/false)true
Timestamps--tsTimestamp format: iso, local, ageage
Max records--maxMaximum records to display50

​
Request properties

PropertyFlagDescriptionDefault
Token--tokenAuthentication tokenSet via login
Endpoint--endpointAPI endpoint URLhttps://api.cpln.io
Insecure--insecureSkip TLS verification (true/false)false
Update any property with: 
cpln profile update <profile-name> --<property> <value>

cpln profile update my-profile --output json

​
Override context

​
Override profile context

Override defaults for a single command: 
cpln <command> --profile <profile-name>

​
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
export CPLN_PROFILE=production

​
View profile token

Display the token for a profile (useful for debugging or CI/CD setup): 
cpln profile token <profile-name>
Tokens are sensitive credentials. Do not share them or commit them to version control.

​
Profile best practices

Name profiles by environment or purpose:
  • dev, staging, production
  • org1-prod, org2-staging
  • ci, local-dev
Reduce the need for --org and --gvc flags by setting defaults:
cpln profile update <profile-name> --org <org-name> --gvc <gvc-name>
Always check your active profile before running destructive commands:
cpln profile get
Look for the profile marked as default with a star *.
First, set your environment variables:
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:
cpln profile create ci --default
The CLI automatically uses the environment variables for authentication and context.See CI/CD usage for details.

​
Common pitfalls

Wrong context: Always verify the active profile before running commands that create or modify resources. Use cpln profile get and check the active button.
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.
Multi-org developers: Explicitly pass --org and --gvc when switching contexts in scripts to avoid unintended changes.
CI runners: Store tokens securely in your CI/CD platform’s secret manager. Never hardcode tokens in scripts or configuration files.

​
Next steps

Common Options

Learn about all shared CLI flags

CI/CD Setup

Configure profiles for automation