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-cliorpip install snowflake-cli, Python 3.11 or later), then check it withsnow --version. - Connections live in
config.toml, or in a separateconnections.tomlin the same folder. Ifconnections.tomlexists, its connections win and the ones inconfig.tomlare ignored. - For key-pair authentication, set
authenticator = "SNOWFLAKE_JWT"andprivate_key_fileto the path of your.p8key. 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 -qruns a query string,snow sql -fruns a file, and--format JSONor--format CSVchanges 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:
- A file you pass with
--config-file. - The folder in
SNOWFLAKE_HOME, if that variable is set and the folder exists, otherwise~/.snowflakeif it exists. - 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_nameorsnow 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.
- Connect Excel to Snowflake with a private key, with the ODBC errors to expect.
- Connect Claude to Snowflake, with the account identifier, default role and grants.
- Connect ChatGPT to Snowflake, with a least-privilege role and a read-only test query.
- Snowflake to Sigma, for BI on the same warehouse.
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

