Skip to main content
Quick solutions for common problems when using the Control Plane CLI.

​
Installation and setup

Problem: The CLI is installed but not found when running cpln.Solutions:
  1. Verify the installation: 
    which cpln
  2. Check if the binary is on your PATH: 
    echo $PATH
    Ensure /usr/local/bin (or your installation directory) is included.
  3. Reinstall the CLI: 
    npm install -g @controlplane/cli
  4. Restart your terminal after installation.
Problem: Installation fails with permission errors.Solutions:
Use sudo (not recommended) or configure npm to install globally without sudo:
# Configure npm prefix
mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'
Add to your shell profile (~/.bashrc, ~/.zshrc, etc.):
export PATH=~/.npm-global/bin:$PATH
Reload and reinstall:
source ~/.bashrc  # or ~/.zshrc
npm install -g @controlplane/cli

​
Authentication

Problem: Commands fail with authentication errors.Solutions:
  1. Check for typos in the org name: 
    cpln profile get
    Verify the org value is correct. A 403 often means you’re trying to access an org that doesn’t exist or that you don’t have access to.
  2. Re-authenticate: 
    cpln login
  3. Check which profile is marked as active with a star *: 
    cpln profile get
  4. Verify the token is valid: 
    cpln profile token <profile-name>
  5. For service accounts, regenerate the key: 
    cpln serviceaccount add-key <service-account-name> --description <key-description>
    Make sure the service account is assigned to a group that has the necessary permissions to access and manage resources (e.g. the superusers group).
    Update your profile with the new token: 
    cpln profile update <profile-name> --token <new-token> --gvc <gvc-name>
    When using --token, always include --gvc to preserve or set your default GVC context.
Problem: cpln login opens a browser you don’t use.Solutions:
  1. Copy the URL from the terminal and paste it into your preferred browser.
  2. Change your system’s default browser (OS-specific).
  3. Use a service account token instead of interactive login. See Authentication.
Problem: cpln login opens a localhost URL that doesn’t work in your Windows browser.Cause: The localhost URL points to the WSL2 instance, not Windows.Solution: Install a browser in WSL2 (requires WSLg):
cd /tmp
sudo wget https://dl.google.com/linux/direct/google-chrome-stable_current_amd64.deb
sudo dpkg -i google-chrome-stable_current_amd64.deb
sudo apt install --fix-broken -y
sudo dpkg -i google-chrome-stable_current_amd64.deb
After installation, Chrome appears in your Windows Start menu under the distro name (e.g., Ubuntu → Google Chrome). Run cpln login, copy the localhost URL from the terminal, and paste it into your WSL2 Chrome.Alternative: Use browser-less login with a service account token.
Problem: Commands execute in the wrong org or GVC.Solutions:
  1. Check your active profile: 
    cpln profile get
  2. Override for a single command: 
    cpln <command> --org <org-name> --gvc <gvc-name>
  3. Update your profile defaults: 
    cpln profile update <profile-name> --org <org-name> --gvc <gvc-name>
  4. Use a different profile: 
    cpln <command> --profile <profile-name>
  5. Set environment variables: 
    export CPLN_ORG=my-org
export CPLN_GVC=my-gvc

​
Connectivity and network

Problem: Commands fail with TLS/SSL errors.Solutions:
  1. Verify your system’s certificate trust store is up to date.
  2. Check if you’re behind a corporate proxy or firewall that intercepts TLS.
  3. As a temporary workaround (not recommended for production): 
    cpln <command> --insecure
  4. Contact your network administrator to add Control Plane’s certificate to your trust store.
Problem: Commands fail with timeout or connection errors.Solutions:
  1. Check your internet connection.
  2. Verify you can reach the Control Plane API: 
    curl -I https://api.cpln.io/about
  3. Check if you’re behind a proxy.

​
Output and display

Problem: Text output doesn’t show all data.Solutions:
  1. Use JSON or YAML output for complete data: 
    cpln <command> --output json
cpln <command> --output yaml
  2. Increase the max results: 
    cpln <command> --max 100
    Set --max 0 to get all the records.
  3. Use json-slim or yaml-slim for cleaner structured output: 
    cpln <command> --output json-slim
See Output Formats for details.
Problem: Log files contain ANSI color codes.Solutions:
  1. Disable color: 
    cpln <command> --color=false
  2. Color is automatically disabled when stdout is not a terminal. Redirect to a file: 
    cpln <command> -o json > output.log

​
Commands and operations

Problem: CLI doesn’t recognize a command or flag.Solutions:
  1. Verify you’re using the correct command syntax: 
    cpln <command> --help
  2. Check your CLI version: 
    cpln --version
  3. Update to the latest version: 
    npm update -g @controlplane/cli

​
Debugging

Enable verbose or debug output to troubleshoot issues: 
cpln <command> --verbose
Debug output may contain sensitive information (tokens, resource details). Use with caution and avoid sharing publicly.

​
Getting help

If you can’t resolve the issue:

​
Next steps

Common Options

Learn about shared CLI flags

Getting Help

Use the built-in help system