Connecting the CLI to and authenticating with a database

• Command line parameters
• Parameters from environment variables
• Additional parameters

The YDB CLI determines what DB to connect to and what authentication mode to use based on information from the following sources (in order of priority):

1. The command line.
2. The profile set in the command-line option.
3. Environment variables.
4. The activated profile.

For the YDB CLI to try connecting to the DB after you completed these steps, make sure to specify the and Database location.

If all the steps are completed, but the YDB CLI did not determine the authentication mode, requests will be sent to the YDB server without adding authentication data. This may let you successfully work with locally deployed YDB clusters that require no authentication. For all databases available over the network, such requests will be rejected by the server with an authentication error returned.

For possible situations when the YDB CLI will not try to connect to a database, see the section below.

DB connection options in the command line are specified before defining the command and its parameters:

• -e, --endpoint <endpoint> : Endpoint: The main connection parameter that allows finding the YDB server on the network. If no port is specified, port 2135 is used. If no protocol is specified, gRPCs (with encryption) is used in YDB CLI public builds.
• -d, --database <database> : .

The authentication mode and parameters are selected by setting one of the following options:

• --iam-token-file <filepath> : The Access Token authentication mode is used based on the contents of the file specified in this option value.
• --yc-token-file <filepath> : The Refresh Token authentication mode is used based on the contents of the file specified in this option value.
• --use-metadata-credentials : The Metadata authentication mode is used.

• --user <username> : The username and password based authentication mode is used with the username set in this option value. Additionally , you can specify:

  • --password-file <filename> : The password is read from the specified file.
  • --no-password : Defines an empty password. The password will be requested interactively if none of the password identification options listed above are specified in the command line parameters.

If several of the above options are set simultaneously in the command line, the CLI returns an error asking you to specify only one:

More than one auth method were provided via options. Choose exactly one of them
Try "--help" option for more info.

When using authentication modes that involve token rotation along with regularly re-requesting them from IAM (Refresh Token and Service Account Key), a special parameter can be set to indicate where the IAM service is located:

• --iam-endpoint <URL> : Sets the URL of the IAM service to request new tokens in authentication modes with token rotation. The default value is "iam.api.cloud.yandex.net".

Parameters from the profile set by the command-line option

If a certain connection parameter is not specified in the command line when calling the YDB CLI, it tries to determine it by the set in the --profile command-line option.

The profile may define most variables similar to the options from the Command line parameters section. Their values are processed in the same way as command line parameters.

If you did not explicitly specify a profile or authentication parameters at the command line, the YDB CLI attempts to determine the authentication mode and parameters from the YDB CLI environment as follows:

• If the value of the IAM_TOKEN environment variable is set, the Access Token authentication mode is used, where this variable value is passed.
• Otherwise, if the value of the YC_TOKEN environment variable is set, the Refresh Token authentication mode is used and the token to transfer to the IAM endpoint is taken from this variable value when repeating the request.
• Otherwise, if the value of the USE_METADATA_CREDENTIALS environment variable is set to 1, the Metadata authentication mode is used.

• If the value of the or YDB_PASSWORD environment variable is set, the username and password based authentication mode is used. The username is read from the YDB_USER variable. If it is not set, an error saying User password was provided without user name is returned. The password is read from the YDB_PASSWORD variable. If it is not set, then, depending on whether the --no-password command-line option is specified, either an empty password is used or a password is requested interactively.

Parameters from the activated profile

If some connection parameter could not be determined in the previous steps, and you did not explicitly specify a profile at the command line with the --profile option, the YDB CLI attempts to use the connection parameters from the activated profile.

If all the steps described in the beginning of this article are completed, but the is not determined, the command is aborted and an error message saying Missing required option 'endpoint' is returned.

If all the steps described in the beginning of this article are completed, but the DB location is not identified, the command is aborted and an error message saying Missing required option 'database' is returned.

If the authentication mode is known, but the necessary additional parameters are not, the command is aborted and an error message describing the issue is returned:

Additional parameters

When using gRPCs (with encryption), you may need to select a root certificate:

• --ca-file <filepath> : Root certificate PEM file for a TLS connection.

Currently, root certificates are not stored in profiles and can only be defined by command line options.