Skip to main content
Use the CLI without an interactive browser login by authenticating with a service account token. This is ideal for SSH sessions, containers, CI/CD pipelines, and other headless environments.

​
Prerequisites

The user setting this up must be a member of the superusers group or have a policy targeting service accounts with these permissions:
  • create
  • edit
  • addKey
Install the Control Plane CLI before proceeding. See Installation.

​
Setup

1

Create a service account

  1. Navigate to Service Accounts in the left menu
  2. Click New or use the Create dropdown
  3. Enter a unique name and optional description
  4. Assign to a group (e.g., superusers, viewers, or a custom group) to grant initial permissions
  5. Click Create
See the Create a Service Account guide for detailed instructions.
2

Generate a key

  1. Open the service account you created
  2. Click the Keys link
  3. Enter a key description and click Add
  4. Copy and securely store the generated key
Store this key securely. It cannot be retrieved after creation.
3

Grant permissions

Create policies to grant the service account access to the resources it needs (GVCs, workloads, secrets, etc.).
See the Policy guide for creating policies via the console.
For testing, you can add the service account to the superusers group for full access, then scope down permissions later.
4

Create a CLI profile

Configure the CLI to use the service account token:
cpln profile create automation --token <your-token> --org <org-name> --gvc <gvc-name> --default
When using --token, always include --gvc to set a default GVC context for your commands.
Your CLI is now configured for browser-less access. Test it with:
cpln workload get

​
Alternative: Environment variables

Instead of creating a profile, you can use environment variables: 
export CPLN_TOKEN=<your-token>
export CPLN_ORG=<org-name>
export CPLN_GVC=<gvc-name>

cpln workload get
This is useful for CI/CD pipelines and containers where you don’t want to persist a profile.

​
Troubleshooting

If CLI commands fail with permission errors:
  1. Test with superusers: Temporarily add the service account to the superusers group
  2. Verify commands work: If they now work, the issue is missing permissions
  3. Add specific permissions: Create policies granting access to the required resources
  4. Remove from superusers: Once policies are in place, remove the service account from superusers
Verify the correct profile is set as default:
cpln profile get
Set the correct profile as default:
cpln profile set-default automation
  1. Verify the token is correct and hasn’t been revoked
  2. Generate a new key if needed: 
    cpln serviceaccount add-key automation --description new-key
  3. Update your profile with the new token: 
    cpln profile update automation --token <new-token>
For more troubleshooting help, see the Troubleshooting page.

​
Next steps

CI/CD Usage

Automate deployments with the CLI

Profiles

Manage multiple authentication contexts

Service Accounts

Create and manage service accounts

Policies

Configure access permissions