Introduction

Catalyst CLI provides tokens that validate your CLI sessions by associating them with a particular user account. When you are logged in to your CLI, the commands you execute are authenticated by a token internally. However, you can also generate a token manually, and use it to perform all the CLI activities without an active login session.   

Tokens are highly useful when you access Catalyst CLI from a remote system, such as a Continuous Integration system, where you need not log in to the CLI exclusively. You can provide authentication for the CI system to access Catalyst and remotely execute CLI commands using a CLI token you generate. To read about using CLI tokens in a CI/CD use case, refer to the Implementing CI/CD in Catalyst help page.

A CLI token can be generated only when you are logged in to a user account from the CLI. Once generated, you can then use that token anywhere from any device to perform CLI operations remotely, even without active login sessions. This token acts as an authenticating factor for that user account, and continues to map your command executions to a project that you specify.  

You can also provide tokens for a particular user account to the collaborators of your Catalyst project and allow them to perform CLI operations, without having to provide them the user login credentials.

When a token is generated, a unique ID is created to identify that token. You must use this token ID while revoking a token.

You must keep the following important points in mind while using tokens:

• A token can only be generated from a CLI and can only be used in a CLI terminal. You will not be able to work with tokens outside of a CLI environment.
• When you generate a token on a particular device's terminal, you will be able to revoke that token from the same terminal only. You will not be able to revoke it from another device's terminal. However, you can use that token to perform CLI operations from any device or environment.
• A token is associated with the data center of the user account that it was generated with. Catalyst will therefore be accessed from the same data center, when you use a token with your command executions.
• A token generated in Catalyst CLI is valid forever. It will not expire unless you personally revoke it.
• You can create multiple tokens for a user account and use any of those tokens at any time from any device.

Generate a Token

You can generate a token for your user account from Catalyst CLI by executing the following command:

$ catalyst token:generate

This will initiate the token generation process. The CLI will display a URL that you can visit from any device. It will also generate a device verification code, which you must enter in the web page of the URL.

Navigate to the URL displayed in the CLI and enter the verification code. Click Verify. The code will only be valid for five minutes.

Once your device's CLI is verified, the token will be generated and displayed in your CLI.

You can now use this token to perform any CLI operation from any remote device, even when logged out, by specifying it as an option with the CLI command in the following manner: 

$ catalyst command --token [token]

To learn more, refer to the CLI options help page.

The CLI operation will be mapped to the user account that you generated the token for, and the command will be executed for the account's project that is active in that directory.

Generate Token Options

You can also use the catalyst token:generate command to check the token that's currently active in your logged-in session. To do so, execute the command with the option --current in the following way:

$ catalyst token:generate --current

This will display the token that is currently active and authenticated in the CLI.

List Tokens

To view a list of the tokens available for your user account, execute the following command in the CLI:

$ catalyst token:list

This will display a list of tokens that you had generated for that account, along with details like Token ID, created date and time.

Revoke a Token

You can revoke a token that was previously generated in the same CLI. This will delete the token permanently, and you will not be able to use it to authenticate your CLI operations any longer.

To revoke a token, execute the following command in the same device's terminal that was used to generate the token:

$ catalyst token:revoke <token ID>

You must specify the token ID of the token to be revoked. You can find the ID of a token using the command mentioned in the previous section.