Specifying your Snowflake credentials

This topic covers the following subjects:

Before you can use Snowflake CLI, you must add your credentials to connect to Snowflake. You can add your Snowflake credentials by using any of the following methods:

Important

Beginning with Snowflake version 8.24, network administrators have the option to require multi-factor authentication (MFA) for all connections to Snowflake. If your administrator decides to enable this feature, you must configure your client or driver to use MFA when connecting to Snowflake. For more information, see the following resources:

Add credentials using a Snowflake CLI connection command

To add Snowflake credentials using the Snowflake CLI connection add command:

  1. Enter the following shell command:

    snow connection add
    
    Copy
  2. When prompted, supply the required connection, account, username parameters, and any desired optional parameters:

    Name for this connection: <connection-name>
    Snowflake account name: <account-name>
    Snowflake username: <user-name>
    Snowflake password [optional]: <password-value>
    Role for the connection [optional]: <role-name>
    Warehouse for the connection [optional]: <warehouse-name>
    Database for the connection [optional]: <database-name>
    Schema for the connection [optional]: <schema-name>
    Connection host [optional]: <host-name>
    Connection port [optional]: <port-value>
    Snowflake region [optional]: <region-name>
    
    Copy

Snowflake CLI uses the connection context (database, schema, role, and so on) when performing any command. You can change this behavior by using environment variables or by using dedicated connections.

Add Snowflake credentials using a configuration file

Snowflake CLI lets you add connection definitions to a configuration file. A connection definition refers to a collection of connection parameters.

Snowflake CLI uses a a global configuration file called config.toml. If the file does not exist, running any snow command for the first time automatically creates an empty config.toml file that you can then populate with the desired connections. For more information about toml file formats, see TOML (Tom’s Obvious Minimal Language). Snowflake Python libraries currently support TOML version 1.0.0.

Snowflake CLI looks for the config.toml file in the following locations, in order:

  • If you specify the --config-file option (such as, snow --config-file ./my-config-file-path), Snowflake CLI uses the specified configuration file.

  • If a ~/.snowflake directory exists on your machine, Snowflake CLI uses the ~/.snowflake/config.toml file.

  • Otherwise, Snowflake CLI uses the config.toml file in the one of the following locations, based on your operating system:

    • Linux: ~/.config/snowflake/config.toml, but you can update it with with XDG vars

    • Windows: %USERPROFILE%\AppData\Local\snowflake\config.toml

    • Mac: ~/Library/Application Support/snowflake/config.toml

Note

For MacOS and Linux systems, Snowflake CLI requires the config.toml file to limit its file permissions to read and write for the file owner only. To set the file required file permissions execute the following commands:

chown $USER config.toml
chmod 0600 config.toml
Copy

To add credentials in a configuration file:

  1. In a text editor, open the config.toml file for editing, such as the following for the Linux vi editor:

    vi config.toml
    
    Copy
  2. Add a new Snowflake connection definition. You must prefix the configuration with connections.

    For example, to add a Snowflake connection called myconnection with the credentials account myaccount, user profile johndoe, and password hunter2, add the following lines to the configuration file:

    [connections.myconnection]
    account = "myaccount"
    user = "jondoe"
    password = "hunter2"
    warehouse = "my-wh"
    database = "my_db"
    schema = "my_schema"
    
    Copy

    Connection definitions support the same configuration options available in the Python Connector.

    Snowflake CLI also supports the connections.toml configuration file. The file should be placed in the same directory as the config.toml file, and it should contain only connections. Configurations in connections.toml require a different section name, without connections.

    Note

    For MacOS and Linux systems, Snowflake CLI requires the connections.toml file to limit its file permissions to read and write for the file owner only. To set the file required file permissions execute the following commands:

    chown $USER connections.toml
    chmod 0600 connections.toml
    
    Copy

    If both the config.toml and connections.toml configurations contain connections, Snowflake CLI uses only configurations from connections.toml.

  3. Optional: Add more connections, as shown:

    [connections.myconnection-test]
    account = "myaccount"
    user = "jondoe-test"
    password = "hunter2"
    warehouse = "my-test_wh"
    database = "my_test_db"
    schema = "my_schema"
    
    Copy
  4. Save changes to the file.

If you do not want to use the config.toml file for a specific situation, you can create a temporary connection that relies only on command-line parameters and system environment variables.

Change the default connection for Snowflake CLI

By default, Snowflake CLI uses the default connection. You can change this default value by changing it in the config.toml file:

default_connection_name = "my_prod_connection"
Copy

You can also change the default connection by setting the SNOWFLAKE_DEFAULT_CONNECTION_NAME environment variable, as shown:

export SNOWFLAKE_DEFAULT_CONNECTION_NAME="my_prod_connection"
Copy

You can quickly switch between multiple connections with the snow connection set-default command, as shown:

snow connection set-default "my_test_connection"
Copy
Default connection set to: my_test_connection

The command also updates the default_connection_name parameter in the config.toml file.

Use environment variables for Snowflake credentials

You can specify Snowflake credentials in system environment variables instead of in configuration files. You can use the following generic environment variables only to replace connection parameters:

  • SNOWFLAKE_ACCOUNT

  • SNOWFLAKE_USER

  • SNOWFLAKE_PASSWORD

  • SNOWFLAKE_DATABASE

  • SNOWFLAKE_SCHEMA

  • SNOWFLAKE_ROLE

  • SNOWFLAKE_WAREHOUSE

  • SNOWFLAKE_AUTHENTICATOR

  • SNOWFLAKE_PRIVATE_KEY_PATH

  • SNOWFLAKE_SESSION_TOKEN

  • SNOWFLAKE_MASTER_TOKEN

You can also use environment variables to override configuration parameters using the following formats:

  • SNOWFLAKE_<config-section>_<variable>=<value>

  • SNOWFLAKE_CONNECTIONS_<connection-name>_<param>=<value>

For example:

export SNOWFLAKE_CONNECTIONS_MYCONNECTION_ACCOUNT="myaccount"
Copy

You can specify some credentials, such as account and user, in the configuration file, and specify the password in an environment variable as follows:

  1. Define the following connection configuration, as appropriate for your Snowflake account:

    [connections]
    [connections.myconnection]
    account = "myaccount"
    user = "jdoe"
    
    Copy
  2. Create a generic system environment variable for the password as follows:

    export SNOWFLAKE_PASSWORD="xyz2000"
    
    Copy

You can also override a value in the configuration file by using a system environment variable. Assume the config.toml file contains the following:

[connections]
[connections.myconnection]
account = "myaccount"
user = "jdoe"
password = "xyz2000"
Copy

You can supply a different password for that connection by creating the following environment variables:

export SNOWFLAKE_CONNECTIONS_MYCONNECTION_PASSWORD="pass1234"
Copy

In these two examples, Snowflake CLI uses pass1234 for the password.

If you do not want to use the config.toml file for a specific situation, you can create a temporary connection that relies only on command-line parameters and system environment variables.

Snowflake CLI uses the following precedence hierarchy to determine which value to use when a parameter is defined in multiple locations:

  • Command-line parameters

  • Connection-specific environment variables, such as SNOWFLAKE_CONNECTION_<name>_USER

  • config.toml file

  • Generic environment variables, such as SNOWFLAKE_USER.

Use a private key file for authentication

To use private key file for authentication, your connection configuration requires you to set the authenticator value to SNOWFLAKE_JWT and provide path to file with your private key similar to the following:

  • Specify the --private_key-path option in the snow connection add command, as shown:

    snow connection add \
       --connection-name jwt \
       --authenticator SNOWFLAKE_JWT \
       --private-key-path "~/.ssh/sf_private_key.p8"
    
    Copy
  • Use the configuration file:

    [connections.jwt]
    account = "my_account"
    user = "jdoe"
    authenticator = "SNOWFLAKE_JWT"
    private_key_path = "~/sf_private_key.p8"
    
    Copy

For more details on configuring key pair authentication, see Key-pair authentication and key-pair rotation.

Note

If your private key is passphrase-protected, set the PRIVATE_KEY_PASSPHRASE environment variable to that passphrase.

Use OAuth authentication

To use connect using OATH, you can do either of the following:

  • Specify the --token-file-path option in the snow connection add command, as shown:

    snow connection add --token-file-path "my-token.txt"
    
    Copy
  • In the config.toml file, set authenticator = "oauth", and add the token_file_path parameter to the connection definition, as shown:

    [connections.oauth]
    account = "my_account"
    user = "jdoe"
    authenticator = "oauth"
    token_file_path = "my-token.txt"
    
    Copy

Use multi-factor authentication (MFA)

To use MFA:

  1. Set up multi-factor authentication in Snowflake and set the authenticator parameter to snowflake (which is a default value).

  2. If you want to use a Duo-generated passcode instead of the push mechanism, modify the passcode or passcode_in_password parameters in config.toml as described in Using MFA in Python.

Enable MFA caching

To enable MFA caching:

  1. For your account, set ALLOW_CLIENT_MFA_CACHING = true.

  2. In your config.toml file, add authenticator = username_password_mfa to your connection.

Use SSO (single sign-on)

If you have configured Snowflake to use single sign-on (SSO), you can configure your client application to use SSO for authentication. See Using SSO with client applications that connect to Snowflake for details.