Skip to main content

Command Line Interface

This page walks you through installing and configuring the Coalesce CLI, coa, for Snowflake: system requirements, authentication, access tokens, Environment details, local config, and how source Nodes fit into your workflow.

Supported Platforms

Currently Snowflake is the only supported platform for coa version 7.33 and above.

Local Development vs. Cloud Operations​

coa has two distinct modes of operation, and understanding the difference will help you know which steps in this guide apply to you.

Local Development​

Local development is how you build and iterate on pipelines. You work directly against your warehouse using the files from your version control checkout. You do not need a connection to Coalesce cloud. You edit SQL, preview the generated DDL, create tables, run DML, and check results in your SQL client. This loop is fast because you skip the full plan and deploy cycle entirely while you're still building.

Cloud Operations​

Cloud operations are how you promote a finished pipeline and keep it running. Once your pipeline works the way you want locally, you generate a deployment plan, apply it to a Coalesce Environment, and schedule refreshes through Coalesce cloud. These commands require a Coalesce access token, your domain URL, and an Environment ID.

Most of the setup steps below apply to both modes. Steps that are only needed for cloud operations are marked with a ☁️ Cloud only label.

System Requirements​

Use the minimum table to confirm your workstation can install and run the CLI. Use the recommended table when you want more headroom for larger Projects or parallel work.

Minimum System Requirements​

ComponentRequirement
OS64-bit Windows 10, macOS 11, Linux kernel version 5.0+
ProcessorAWS t2.medium 4X vCPU or equivalent, Apple M1, Intel Core i3-10100 4 Core or better, or AMD Ryzen 3 1200 4 Core or better
RAM8 GB+
Storage1 GB+ free space
NetworkAccess to Snowflake instance; access to Coalesce cloud for cloud operations
Node versionv20.x
ComponentRequirement
OS64-bit Windows 10, macOS 11, Linux kernel version 5.0+
ProcessorApple M1 or newer, AWS t2.medium 8X vCPU or equivalent, Intel i3 8X Core or higher, or AMD Ryzen 3 8X Core or better. Choose Apple M1 or newer when you can.
RAM16 GB+
Storage1 GB+ free space
NetworkAccess to Snowflake instance; access to Coalesce cloud for cloud operations
Node versionv20.x

Before You Begin​

What you need depends on how you use the CLI.

  • Local development - You need your warehouse credentials and a Coalesce Project cloned to your machine.

When you deploy pipelines through Coalesce cloud, complete the following in the Coalesce App before you run coa plan or coa deploy:

  1. Create a Project including configuring a version control provider.
  2. Create a Workspace.
  3. Configure your Environment.
  4. Add a data source.
  5. Commit your project to your repo after completing these steps.

Existing customers can use an existing repository.

Installation​

Use npm to install or update the global CLI package, then confirm the binary is on your PATH:

  • To install: npm install -g @coalescesoftware/coa
  • To update: npm upgrade -g @coalescesoftware/coa
  • To verify: coa --version

Authentication​

The Coalesce CLI supports Snowflake Key Pair Authentication and Basic Auth. You'll also need a Coalesce access token for cloud operations.

Snowflake​

  1. Go through the steps in Key Pair Authentication to generate your keys.
  2. Save the private key file path. You'll need it for the CLI config and the Coalesce App.
  3. Generate your public key using the private key.
  4. Assign the public key to your Snowflake user.
  5. ☁️ Cloud only - Add your key pair to your Environment.
Adding Your Private Key

When entering your private key, include the full PEM block including the BEGIN ENCRYPTED PRIVATE KEY and END ENCRYPTED PRIVATE KEY lines. Escape special characters with \. For example:

  • Original passphrase: hnw6a#n
  • Escaped passphrase: hnw6a\#n

Be sure to escape # pound signs and : semicolons.

-----BEGIN ENCRYPTED PRIVATE KEY-----
...hnw6a\#n....
-----END ENCRYPTED PRIVATE KEY-----

☁️ Cloud Only: Coalesce Access Token​

You need a Coalesce access token to run coa plan, coa deploy, coa refresh, and any API-style commands. Local development commands (coa create, coa run, coa validate, coa doctor) do not require a token.

Go to the Deploy tab and click Generate Access Token.

Generate Coalesce access token

If you sign in to the Coalesce App with SSO, plan on generating a new access token for each new Environment you create.

☁️ Cloud Only: Get Your Environment ID​

Get your Environment ID with coa environments list.

☁️ Cloud Only: Get Your Domain URL​

Your domain is the base URL you use to sign in to Coalesce. The value is the same one you use in your CLI domain field. Examples:

  • https://<company-name>.coalescesoftware.io
  • https://<company-name>.pp.us-east-2.aws.coalescesoftware.io
  • https://app.eu.coalescesoftware.io
  • https://<your-private-link-url>

Creating Your CLI Config File​

Create ~/.coa/config without a file extension inside a .coa folder in your home directory:

~/
└── .coa/
    └── config

For local development, you only need your warehouse credentials. The token, domain, and environmentID fields are only required when you run cloud commands.

[default]
snowflakeAuthType=KeyPair
snowflakeAccount=your-account.region.cloud
snowflakeKeyPairKey=file_path_to_private_key
snowflakeKeyPairPass=private_key_passphrase_if_applicable
snowflakeRole=snowflake_user_role
snowflakeUsername=snowflake_user_name
snowflakeWarehouse=snowflake_warehouse

# ☁️ Cloud only: add these when you're ready to deploy
environmentID=your_environment_id
token=your_access_token
domain=your_domain_url

With warehouse credentials in place, you're ready to build pipelines locally. Add the cloud fields when you're ready to deploy.

Profiles​

Profiles let you run commands against different configurations, for example, a local development warehouse, a staging environment, and production. Pass --profile <name> on any command to select a profile. If no profile is specified, coa uses [default].

coa plan --profile snowflakeAdmin

The [default] profile is required. For cloud operations it must contain token and environmentID.

Example config with multiple profiles
[default]
token=<Coalesce API Token>
environmentID=<Coalesce ENV ID>
domain=<Coalesce APP URL>

[snowflake-key-pair]
platformKind=Snowflake
snowflakeAuthType=KeyPair
snowflakeAccount=your-account.region.cloud
snowflakeKeyPairKey=<Snowflake Key Pair Key or File Path>
snowflakeRole=<Snowflake Role>
snowflakeUsername=<Snowflake User Name>
snowflakeWarehouse=<Snowflake Warehouse>
environmentID=<Coalesce ENV ID>

[snowflake-basic]
platformKind=Snowflake
snowflakeAuthType=Basic
snowflakeAccount=your-account.region.cloud
snowflakeUsername=<Snowflake Account Username>
snowflakePassword=<Snowflake Account Password>
snowflakeWarehouse=<Snowflake Warehouse>
snowflakeRole=<Snowflake User Role>
environmentID=<Coalesce ENV ID>

Configure HTTP and HTTPS Forward Proxies​

The CLI configures its default HTTP client for Coalesce API traffic using standard proxy environment variables when the process starts. Set variables in the same shell or job definition you use to run coa, or set them at the machine level if your organization requires it.

Set HTTP_PROXY and HTTPS_PROXY​

set HTTP_PROXY=http://your-proxy-address:port
set HTTPS_PROXY=http://your-proxy-address:port

If specific hosts must bypass the proxy, set NO_PROXY to a comma-separated list of host names or CIDR ranges your organization uses for direct routing. Some shells expect the lowercase variable name instead, so use the spelling your environment documents.

Optional Proxy Credentials​

Embed a username and password directly in the proxy URL:

set HTTP_PROXY=http://username:password@your-proxy-address:port
set HTTPS_PROXY=http://username:password@your-proxy-address:port

Proxy URLs that include passwords can appear in process listings and logs on some systems. Prefer proxy accounts designed for automation, URL-encode special characters in credentials when required, and use secret stores your platform supports.

Test Connectivity Before You Run coa​

Confirm HTTPS connectivity through the proxy with curl, substituting your Coalesce domain:

curl -x http://your-proxy-address:port https://your-coalesce-domain.example/

If curl succeeds but coa does not, compare environment variables between the two sessions and review proxy or TLS policies with your network team.

What Proxy Settings Apply To​

Proxy environment variables configure the standard HTTP client the CLI uses for Coalesce API calls. Other libraries or drivers your workload touches may use different networking stacks. Validate full deploy and refresh paths in your own environment when proxies, custom certificate authorities, or TLS inspection are in use.

Network Connectivity​

Which services coa connects to depends on the command you run. Treat network requirements as path-specific: allow Coalesce cloud endpoints for cloud operations, and allow your warehouse endpoints for all commands that execute SQL.

CommandConnects to Coalesce CloudConnects to Warehouse
coa create, coa runNo (most workflows)Yes
coa validate, coa doctorNo (most workflows)Yes
coa planYesYes
coa deployYesYes
coa refresh, coa rerun, coa cancelYesYes
coa environments, coa nodes, coa runsYesNo
coa workspace-nodesYesNo

What's Next?​

Continue with the rest of the CLI documentation when you need workflows, detailed command syntax, or troubleshooting help.