Skip to main content
Version: v4.17

Using the Cyral CLI

Command line users can use the Cyral CLI to easily manage their access tokens. The CLI directs the user to the Cyral portal to authenticate using their SSO credentials and then uses the Cyral APIs to manage and retrieve access tokens that can be used to authenticate to data endpoints. The CLI can also show other connection information (e.g., the sidecar endpoint etc) for connecting to a data repository.

Install the Cyral CLI​

Procedure​

Install the Cyral CLI for each user as follows:

  1. Install the Cyral CLI on the database user's machine using pip3. Type the following in your command shell:
    pip3 install cyral
  2. Share the appropriate connection instructions below with the database user.

Using the Cyral CLI for SSO​

The first step to use Cyral CLI for SSO database connections is to create an access token. After you authenticate successfully, you can create an access token with the command token create, which will create an access token and store it in a local cache, so that it can be used by the other commands. The token caching is optional and can be disabled with the --no-use-token-cache option.

info

If you already reached the maximum number of concurrent tokens, you will have to delete an existing access token before trying to create a new one, otherwise the Cyral CLI will return an error. You can use the token list command to list all of your existing access tokens and use the token delete command to delete a specific access token.

Once you have created an access token, you can use the access repo to show the list of data respositories accessible to you and the information needed to access the selected repository. This command works for all supported data endpoint types.

You can use the token show command to retrieve an existing access token from the cache.

The basic syntax for the token create command is:

cyral --cp-address <Cyral Control Plane Address> token create

The basic syntax for the access repo command is similarly:

cyral --cp-address <Cyral Control Plane Address> access repo

Where:

  • The --cp-address flag supplies your Cyral service address, which is similar to the URL of your Cyral control plane, for example, acme.app.cyral.com.

Please visit the Cyral CLI PyPI page for additional information about the other commands and options supported by the CLI.

tip

Any command line option of the Cyral CLI can also be specified by setting it as the value of an environment variable. As an example, instead of specifying the Cyral control plane address as the value of the option --cp-address, you can also specify it as the value of the environment variable CYRAL_CP_ADDRESS. Note that the environment variable name corresponding to a command line option is obtained by capitalizing all alphabetical characters, replacing all dash (-) characters with underscores (_), and adding the prefix CYRAL_.

Connect to PostgreSQL using the Cyral CLI​

The Cyral CLI makes it simpler to access a PostgreSQL database using your SSO credentials by adding an entry with the access token in the .pgpass file. The command access pg updates the .pgpass file in the user's home directory with a cached access token for each PostgreSQL database accessible by the user.

  1. Run the access pg command as follows:

    cyral --cp-address <Cyral Control Plane Address> access pg

  2. Now start a database session as usual. PostgreSQL uses your Cyral-provided credentials to log you in.

info

If your authentication fails, it may be because your access token has expired. You can create a new access token using the token create command and then run the access pg command again.

Connect to S3 data using the Cyral CLI​

The Cyral CLI makes it simpler to access S3 using your SSO credentials by adding the necessary information to the configuration files in the .aws directory.

  1. Ensure that the necessary prerequisites are installed. The Cyral CLI will install them on the first run and for that you just need to open a terminal session and run the following command:

    cyral --cp-address <Cyral Control Plane Address> access s3 --aws-profile <your AWS profile name> --autoconfigure

    Where:

    • The --cp-address flag supplies your Cyral service address, which is similar to the URL of your Cyral control plane, for example, acme.app.cyral.com.
    • The --aws-profile flag specifies your AWS profile name. The Cyral CLI automatically inserts the cached access token into your AWS credentials file (usually ~/.aws/credentials/), saving the token in the AWS profile that you've specified. This should be either a new profile, or a profile previously used with the Cyral CLI. Please do not use a profile previously configured by any other tool, or manually configured, as it could lead to conflicting configurations.
    • The --autoconfigure flag will make sure all the necessary configurations and pre-requisites are installed to get AWS CLI to work properly with the sidecar.

  2. After all the prerequisites are installed, the Cyral CLI can be used as follows to configure your access token in the AWS credentials file.

    cyral --cp-address <Cyral Control Plane Address> access s3 --aws-profile <your AWS profile name>

  3. Connect to S3 as usual using the profile you informed in the command. Your Cyral access token will be used to log you in.

info

If your authentication fails, it may be because your access token has expired. You can create a new access token using the token create command and then run the access s3 command again.

warning

Please ensure that only a single version of the AWS CLI is installed before making the configuration with the Cyral CLI. AWS currently offers two major versions of the AWS CLI:

The presence of these two distinct major versions of the AWS CLI within the system environment may cause the Cyral CLI to generate incomplete configurations, ultimately leading to connectivity issues when attempting to access S3 buckets.