Skip to main content
Authenticate the CLI with a service account token instead of an interactive login. This is the right choice for unattended automation — CI/CD pipelines, scripts, and long-lived containers — where no person is available to complete a sign-in.
For interactive use, you no longer need a browser on the machine running the CLI. cpln login prints a URL and a confirmation code that you can complete from a browser on any device, so it works over SSH, inside containers, and in WSL2. Reach for a service account token when the login must be unattended, not merely browser-less. See Authentication.

​
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:
When using --token, always include --gvc to set a default GVC context for your commands.
Your CLI is now configured for unattended access. Test it with:

​
Alternative: Environment variables

Instead of creating a profile, you can use environment variables:
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:
Set the correct profile as default:
  1. Verify the token is correct and hasn’t been revoked
  2. Generate a new key if needed:
  3. Update your profile with the 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