Skip to main content

​
Overview

The CLI is used to perform actions against the Control Plane API. Since most of the CLI commands require the caller to be authenticated and authorized, the CLI profile is used to store the security token and default properties.

​
Prerequisites

  • Install the CLI
  • Review the CLI profile command page

​
Create a Profile

After installation, to execute any of the CLI commands, at least one profile must be created and associated with an authenticated user or service account. To create the profile named default and authenticate with a user account, follow the interactive login - default profile instructions. To create a profile using a custom name and authenticate with a user account, follow the interactive login - custom profile instructions. After logging in, that profile will be marked as the default and used by any future CLI command. The following default properties are set on the profile during creation:
  • Context
    • Org: None
    • GVC: None
  • Format
    • Color: true
    • Output: text
    • Timestamp: age
  • Request
    • Endpoint: https://api.cpln.io
    • Insecure: false
    • Timeout: 30
    • Token: AUTH_TOKEN
To override these values, refer to the default properties section.

​
Interactive Login - Default Profile

Executing the command: 
cpln profile login
will launch the login page within a browser. If the authentication is successful, a new profile named default will be created (if it doesn’t already exist). This login targets only the profile named default. After logging in, this profile will be marked as the default and used by any future CLI command.

​
Interactive Login - Custom Profile

To authenticate to a specific profile, executing the command: 
cpln profile update PROFILE_NAME --login
will launch the login page within a browser. If the authentication is successful, a new profile with the given name will be created (if it doesn’t already exist). After logging in, this profile will be marked as the default and used by any future CLI command.

​
Interactive Login - Existing Profile

To authenticate to an existing profile, execute the following command: 
cpln profile login PROFILE_NAME

​
Default Properties

The --org or --gvc options are required on a majority of the CLI commands and are set to an empty string by default. The default org, GVC, and other properties can be set by updating your profile. The following properties can be updated:
  • default
  • org
  • gvc
  • output
    • Default output format (text, json, yaml, json-slim, or yaml-slim)
  • color
    • Default colorization of the output (true or false)
  • ts
    • Default timestamp format (iso, local, or age)
  • max
    • Default max number of records to show (number > 0)
  • token
    • Override profile token
  • endpoint
    • Default API endpoint
  • insecure
    • Override TLS errors (true or false)
Sample Command: 
cpln profile update PROFILE_NAME --PROPERTY NEW_VALUE
Examples: 
cpln profile update my_profile --org test-org

​
Set Default Profile

If you have multiple profiles, execute the following command to mark a profile as default: 
cpln profile set-default PROFILE_NAME
Future CLI commands will use this profile. If the profile is not authenticated, follow the instructions here.

​
Remove Profile Default Context (Org/GVC)

To remove the default organization and/or default GVC from a specific profile, pass an empty string as the value. 
cpln profile update PROFILE_NAME --org ""
Removing the default organization from a profile will also remove the default GVC. This is because the GVC is tied to the specific organization and may not be applicable to a future default organization.

​
Security Token

Executing the command: 
cpln profile token PROFILE_NAME
will show the JWT token for the given profile if it has a valid authentication token. This token can be used to override any of the CLI commands by using the --token option.

​
Delete Profile

If a profile is no longer needed, execute the command: 
cpln profile delete PROFILE_NAME
The profile and any associated data will be deleted.