How to use Snowflake CLI: install it, connect with a key pair, and run snow sql

Install Snowflake CLI, add a named connection with key-pair authentication, test it, and run queries and SQL files with snow sql, step by step.

Written by Linus Tse, founder of Greyfield Data

ยท 9 min read

On this page 12 sections

Snowflake CLI is Snowflake's command-line client, and the command is snow. You install it, save a named connection, and run SQL with snow sql -c <connection> -q "...". We run it every day for client work, with key-pair authentication on a service user and one named connection per client.

If you want a Snowflake account set up this way from the start, with service users, roles and cost limits, that is part of our Snowflake consulting. For the wider picture of how to use Snowflake, from first login to cost controls, start with our Snowflake resource hub.

Key takeaways

  • Install Snowflake CLI with the standalone installer, Homebrew, an OS package, or Python (pipx install snowflake-cli or pip install snowflake-cli, Python 3.11 or later), then check it with snow --version.
  • Connections live in config.toml, or in a separate connections.toml in the same folder. If connections.toml exists, its connections win and the ones in config.toml are ignored.
  • For key-pair authentication, set authenticator = "SNOWFLAKE_JWT" and private_key_file to the path of your .p8 key. Snowflake requires at least a 2048-bit RSA key pair.
  • snow connection test -c <name> proves a connection works before you run anything that matters.
  • snow sql -q runs a query string, snow sql -f runs a file, and --format JSON or --format CSV changes the output for scripts.

Quick answers

  • Install command: pipx install snowflake-cli, brew install snowflake-cli, or the standalone installer.
  • Check the install: snow --version.
  • Run a query: snow sql -c my_conn -q "select current_role()".
  • Run a file: snow sql -c my_conn -f setup.sql.
  • Replaces: SnowSQL, which Snowflake now calls a legacy client.

What is Snowflake CLI, and how is it different from SnowSQL?

Snowflake CLI is the current command-line client for Snowflake, and SnowSQL is the older one. Snowflake's SnowSQL page calls SnowSQL "a legacy command-line client" and says new features go only into Snowflake CLI. SnowSQL 1.5.x is supported through April 16, 2028.

Snowflake CLI does more than run SQL. Snowflake's introduction lists Snowpark functions and procedures, warehouses and Streamlit apps, and it can also deploy and run dbt projects on Snowflake with snow dbt deploy and snow dbt execute. For day-to-day data work, snow sql and snow connection are the two you use most.

Snowflake CLI SnowSQL
Command snow snowsql
Status Current, gets new features Legacy, 1.5.x supported through April 16, 2028
Run a query snow sql -q "..." snowsql -q "..."
Connection config config.toml or connections.toml SnowSQL's own config file
Moving over snow helpers import-snowsql-connections copies SnowSQL connections Not applicable

Snowflake keeps a migration guide from SnowSQL to Snowflake CLI if you have scripts to move.

How do you install Snowflake CLI?

Pick one install method from Snowflake's installation page and stick with it, because each one upgrades differently.

Method Command Upgrade with
Standalone, macOS or Linux curl -LsS https://sfc-repo.snowflakecomputing.com/snowflake-cli/install.sh | sh snow upgrade
Standalone, Windows PowerShell irm https://sfc-repo.snowflakecomputing.com/snowflake-cli/install.ps1 | iex snow upgrade
Homebrew (community formula) brew install snowflake-cli brew upgrade snowflake-cli
pipx pipx install snowflake-cli pipx
uv uv tool install snowflake-cli uv tool upgrade snowflake-cli
pip, into the active environment pip install snowflake-cli pip

Snowflake also publishes an official Homebrew tap, and .pkg, .msi, .deb and .rpm packages in its CLI repository. The Python methods need Python 3.11 or later.

Open a new terminal and check the install:

snow --version

If you searched "how to install Snowflake", note that Snowflake itself is a cloud service with nothing to install. The CLI, drivers and connectors are what you install on your machine.

Where does Snowflake CLI keep its connections?

Snowflake CLI reads connections from config.toml, or from connections.toml in the same folder. Per Snowflake's configuration page, it looks in this order:

  1. A file you pass with --config-file.
  2. The folder in SNOWFLAKE_HOME, if that variable is set and the folder exists, otherwise ~/.snowflake if it exists.
  3. The OS default: ~/.config/snowflake/ on Linux, ~/Library/Application Support/snowflake/ on macOS, and %USERPROFILE%\AppData\Local\snowflake\ on Windows.

Run snow --info and read default_config_file_path to see which file your install actually uses. That one check saves a lot of guessing.

On macOS and Linux, Snowflake CLI requires config.toml to be readable and writable by its owner only. Set that with chmod 0600 config.toml, as the connection docs describe.

How do you connect Snowflake CLI with key-pair authentication?

Generate a key pair, put the public key on the Snowflake user, and point a named connection at the private key file with authenticator = "SNOWFLAKE_JWT". That is how we connect: a service user with a key, never a password.

1. Create the key pair

These are the commands from Snowflake's key-pair authentication guide. The first one makes an encrypted private key, and the second derives the public key from it.

openssl genrsa 2048 | openssl pkcs8 -topk8 -v2 aes-256-cbc -inform PEM -out rsa_key.p8
openssl rsa -in rsa_key.p8 -pubout -out rsa_key.pub

Snowflake requires at least a 2048-bit RSA key pair. Keep rsa_key.p8 on your machine, readable only by you, and out of any git repository.

2. Put the public key on the user

Paste the key body from rsa_key.pub, without the header and footer lines:

ALTER USER CLIENT_A_SVC SET RSA_PUBLIC_KEY = 'MIIBIjANBgkqh...';

Snowflake's guide also shows a named form, ALTER USER ... ADD KEY PAIR my_key PUBLIC_KEY = '...'. For creating the service user itself, with TYPE = SERVICE, a default role and no secondary roles, see how I set up a new Snowflake account.

3. Add the named connection

snow connection add writes the connection for you. This uses the option names from Snowflake's connection add reference; the values are placeholders.

snow connection add \
  --connection-name client_a \
  --account myorg-client_a \
  --user CLIENT_A_SVC \
  --authenticator SNOWFLAKE_JWT \
  --private-key-file ~/.snowflake/keys/client_a.p8 \
  --role CLIENT_A_READER \
  --warehouse REPORTING_WH \
  --no-interactive

The result in connections.toml looks like this. In config.toml, the same block is written as [connections.client_a].

[client_a]
account = "myorg-client_a"
user = "CLIENT_A_SVC"
authenticator = "SNOWFLAKE_JWT"
private_key_file = "/home/you/.snowflake/keys/client_a.p8"
role = "CLIENT_A_READER"
warehouse = "REPORTING_WH"

If the key has a passphrase, Snowflake CLI reads it from the PRIVATE_KEY_PASSPHRASE environment variable. Snowflake's docs also accept private_key_path or private_key_raw, but private_key_file is checked first.

4. Test it

snow connection test -c client_a
snow connection list

Then run snow sql -c client_a -q "select current_user(), current_role(), current_warehouse()". If the role or warehouse is not the one you expect, fix the user's defaults or the connection before going further.

How do you run queries with snow sql?

snow sql runs SQL on a connection, from a string, a file or standard input. The options below come from the snow sql command reference.

Option What it does Example
-q, --query Runs a query string snow sql -c client_a -q "select count(*) from analytics.marts.orders"
-f, --filename Runs every statement in a file; repeat -f to run several files in order snow sql -c client_a -f grants.sql
-i, --stdin Reads SQL from standard input cat check.sql | snow sql -c client_a -i
-c, --connection Picks the named connection -c client_b
--format Output as TABLE, JSON, JSON_EXT, CSV or PLAIN --format JSON
-D, --variable Fills a <% name %> placeholder before the query is sent -D "database=dev"
--single-transaction All statements succeed or none apply snow sql -f load.sql --single-transaction

A few patterns we use all the time:

# A quick check
snow sql -c client_a -q "select current_role()"

# A setup script, with the database name passed in
snow sql -c client_a -f grants.sql -D "database=ANALYTICS_DEV"

# JSON output for a script to read
snow sql -c client_a -q "show warehouses" --format JSON

Several statements in one -q string come back as several result sets, per Snowflake's guide to running SQL.

Why use one named connection per client or environment?

Named connections make the target explicit in every command. When the connection name is in the command, you can read a script and see exactly which account and role it touches.

We keep one connection per client, each with its own service user, key file and least-privilege role. A typo in a connection name fails loudly instead of running against the wrong account.

Two habits help:

  • Don't set a default connection on a shared machine. Without default_connection_name or snow connection set-default, every command has to say -c.
  • Give each connection the smallest role that does the job. A read-only role for reporting checks, and a separate one for changes. The same idea is behind giving analysts safe AI access to Snowflake.

What does Snowflake CLI cost to run?

The CLI is free, but every query it runs uses a warehouse, and warehouses bill credits while they run. Auto-suspend matters too: a warehouse that never goes idle keeps billing. Snowflake bills per second with a 60-second minimum each time a warehouse starts.

An X-Small warehouse uses 1 credit per hour. A one-second select current_role() that wakes a suspended X-Small warehouse still bills 60 seconds. To see what your warehouse settings cost over a month, try the Snowflake cost calculator.

What else connects to Snowflake the same way?

The same habits carry over to other tools: a named user, the smallest role that works, and a default warehouse you chose on purpose. Excel can use the same kind of key pair over ODBC.

What to do next

Install the CLI, add one connection with a key pair, and run snow connection test. Then read how I set up a new Snowflake account so the service user behind that connection has the right role and warehouse. If you want help setting up service users and access across several accounts, book a call.

Frequently asked questions

How do I install Snowflake CLI?

Use the standalone installer, brew install snowflake-cli, or pipx install snowflake-cli with Python 3.11 or later, then run snow --version in a new terminal. Snowflake's installation page lists every method.

How do I run a SQL query from Snowflake CLI?

Run snow sql -c <connection> -q "select ..." for a query string, or snow sql -c <connection> -f file.sql for a file. Add --format JSON or --format CSV when another program reads the output.

Where is the Snowflake CLI config file?

It is config.toml in ~/.snowflake if that folder exists, otherwise in your OS's default config folder, with connections optionally in a connections.toml next to it. Run snow --info and read default_config_file_path to see which file your install uses.

How do I use key-pair authentication with Snowflake CLI?

Set authenticator = "SNOWFLAKE_JWT" and private_key_file to your .p8 key in the connection, and put the matching public key on the user with ALTER USER ... SET RSA_PUBLIC_KEY. If the key is encrypted, set the passphrase in PRIVATE_KEY_PASSPHRASE.

Is SnowSQL deprecated?

Snowflake calls SnowSQL a legacy client and adds new features only to Snowflake CLI. SnowSQL 1.5.x is supported through April 16, 2028, per Snowflake's SnowSQL page.

Part of the How to Use Snowflake, a reading path through related articles.

Linus Tse

Founder of Greyfield Data. Built 400+ dashboards. Certified in Sigma, Snowflake, Tableau, and Power BI.

About Linus

โ† All articles