Skip to main content
Version: v4.5

Using the Cyral CLI

Command line users can use the Cyral CLI to easily retrieve the access token. The CLI directs the user to the Cyral portal to authenticate using their SSO credentials and then uses the Cyral APIs to retrieve the access token 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 Cyral CLI commands access token and access repo work for all supported data endpoint types. After you authenticate successfully, the access token command simply prints the database access token to the output. The access repo command shows the list of data respositories accessible by the user and the information needed to access the selected repository.

The basic syntax for the access token command is:

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

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 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. This command below will update the .pgpass file in the user's home directory with access token for each PostgreSQL database accessible by the user.

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

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

If your authentication fails, it’s likely your access token has expired. Run the command above again to generate a fresh token.

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. Before you use the AWS CLI to access S3, it is required to install some prerequisites. 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 --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 --profile flag specifies your AWS profile name. The Cyral CLI automatically inserts a token into your AWS credentials file (usually ~/.aws/credentials/), saving the token in the AWS profile that you've specified.
    • 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> --profile <your AWS profile name>

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

If your authentication fails, it’s likely your access token has expired. By default, each token expires 24 hours after it's issued. Run the command above again to generate a fresh token.