What is SnowConvert CLI?¶

Prerequisites¶

• macOS, Windows, or Linux

• SnowflakeCLI: recommended for Snowflake connection configuration SnowCLI Install Guide

• A source database to extract from, or a set of code to use

Snowflake Connection Setup¶

The SnowConvert AI CLI (scai) reuses your Snowflake CLI connection configuration. The connection is used for functionality in ai-convert, deploy, and the cloud versions of data migration and validation. Your Snowflake account also authenticates you for SnowConvert, skipping the need for an access code that was necessary in prior versions.*

Snowflake Account Requirement

Before using scai init, scai code convert, scai code extract, scai ai-convert, or scai code deploy, ensure that you:

Can connect to Snowflake with snow connection test Your Snowflake CLI has a default connection configured (this is used when you don’t specify a name).

To configure a Snowflake connection:

# Add a new connection using Snowflake CLI
snow connection add

# Set it as the default
snow connection set-default <connection_name>

# Test your connection
snow connection test

Once this is configured, commands needing a connection to Snowflake will use your Snowflake CLI connection automatically.

Installation¶

Homebrew Installation

If you do not have homebrew installed, follow the instructions here.

There are two public channels for builds, Preview and GA.

Stable Version (recommended)

Install the stable production (GA) release:

brew tap snowflakedb/snowconvert-ai
brew install --cask snowconvert-ai

Preview Version

Install the Preview (pr) version with pre-release features from the beta/staging environment:

brew tap snowflakedb/snowconvert-ai
brew install --cask snowconvert-ai-pr

Usage

After installation, you can use the SnowConvert CLI:

scai --help

Managing Installations

View installed Version

brew info --cask snowconvert-ai
# or
brew info --cask snowconvert-ai-pr

Switch between versions

# Uninstall current version
brew uninstall --cask snowconvert-ai #or snowconvert-ai-pr

# Install another version
brew install --cask snowconvert-ai
# or
brew install --cask snowconvert-ai-pr

Update to latest version Important: you must run brew update first to sync the tap with the latest cask definitions:

# Update tap definitions and upgrade to latest version
brew update && brew upgrade --cask snowconvert-ai

# For preview version
brew update && brew upgrade --cask snowconvert-ai-pr

Why both commands? brew update synchronizes your local tap with the latest cask definitions from GitHub. Without it, brew upgrade won’t see new versions even if they exist on the server.

Installer Packages:¶

GA Releases

Preview Releases

Accept Terms and Conditions¶

Issusing the following command will display the license terms for using the SnowConvert AI CLI. It is required that you do this in order to use the product.

# display the scai terms and conditions
scai terms 

#displays terms and allows you to accept them
scai terms accept 

Understanding Projects¶

A project is required before you can use any other scai command. This is similar to how Git requires you to run git init before using other Git commands.

A project:

• Organizes your migration work in a dedicated folder structure

• Tracks your source dialect (Oracle, SQL Server, Teradata, etc.)

• Stores configuration, source code, converted code, and reports

When you run scai init, it creates this folder structure in the target directory.

• If you pass a PATH, scai will create that folder (if it doesn’t exist) and initialize the project inside it.

• If you omit PATH, scai initializes the current directory (which must be empty).

The following folder structure:

project/
├── .git/
├── .gitignore
├── .scai/
│   ├── config/
│   │   ├── project.yml                        ← Team-shared config (Git)
│   │   ├── project.local.yml                  ← Personal config (gitignored)
│   │   └── conversion-context/
│   │       └── MigrationContext.json
│   └── registry/
│       ├── {uuid1}.json
│       ├── {uuid2}.json
│       ├── {uuid3}.json
│       └── .locks/                            ← SCRIPT STATE (Git)
│           └── registry.lock
├── settings/                ← User-managed settings (not created by default)
│   ├── extraction.yml
│   ├── deployment.yml
│   └── ai-verification.yml
├── source/                                    ← Source code Database objects
│   └── db1/
│       └── retail/                            -- schema1
│           ├── Tables/
│           │   ├── table_customers.sql
│           │   └── table_orders.sql
│           └── Stored Procedures/
│               └── proc_calculate.sql
├── snowflake/                                ← Working directory of converted code (may have manual edits, should not get overwritten)
│   ├── db1/
│   │   └── retail/                            -- schema1
│   │       ├── Tables/
│   │       │   ├── table_customers.sql
│   │       │   └── table_orders.sql
│   │       └── Stored Procedures/
│   │           └── proc_calculate.sql
│   └── dbt/                                   ← Converted scripts (optional)
│       └── models/
│           └── staging/
│               └── stg_customer_daily.sql
├── artifacts/                                 ← All artifacts related to objects
│   ├── source_raw/                            ← Original source code without changes
│   ├── db1/
│   │   ├── retail/                            -- schema1
│   │   │   └── table/             -- one folder per object kind
│   │   │       └── products/
│   │   │           ├── deterministic/         -- different runs from deterministic engine
│   │   │           │   ├── 20261201.350956/
│   │   │           │   │   └── proc_calculate.sql
│   ├── UDF Helpers/
│   └── ETL/
│   │     ├── DWH_EXAMPLE
│   │     │     ├── DWH_EXAMPLE.sql
├── reports/                                   ← Generated reports (optional in Git)
│   ├── SnowConvert/
│   │   ├── ObjectReferences.<timestamp>.csv
│   │   ├── TopLevelCodeUnits.csv
│   │   └── Issues.csv
│   ├── GenericScanner/
│   │   └── GenericScannerOutput/
│   │       ├── line_counts.pam
│   │       ├── files.pam
│   │       ├── FilesInventory.csv
│   │       ├── word_counts.pam
│   │       ├── KeywordCounts.csv
│   │       └── tool_execution.pam
│   └── ...
├── logs/
│   ├── GenericInfrastructureController/
│   ├── GenericScanner/
│   └── Snowconvert/
└── results/
    └── DataValidation/

Important: after creating a project, run all subsequent scai commands from within the project folder (where the .scai directory is).

CLI Logs are written to ~/.scai/logs/jobs.log by default

Quick Start: Code Conversion Only¶

Use this workflow when you have existing SQL files to convert. Works with all supported dialects.

[!IMPORTANT] You must already be in an empty directory to create a project.

#1. Create a project folder and initialize it (project name is inferred from folder name)

scai init my-project -l Oracle
cd my-project

#2. Add your source code

scai code add -i /path/to/your/sql/files

#3. Convert to Snowflake SQL

scai code convert

#4. Deploy to Snowflake

scai code deploy

Your converted code will be in the snowflake/ folder, and conversion reports in reports/.

Quick Start: End-to-End Migration¶

Use this workflow to extract code directly from your source database. Only available for SQL Server and Redshift.

Step 1: Create Project # Create a project folder and initialize it (project name is inferred from folder name)

scai init my-project -l SqlServer # or Redshift
cd my-project

Step 2: Configure Source Connection

#SQL Server (interactive mode - recommended)
scai connection add-sql-server

#Redshift (interactive mode - recommended)
scai connection add-redshift

The interactive mode will prompt you for connection details.

Set a default source connection (used with scai code extract runs without -source-connection)

scai connection set-default -l sqlserver --connection <NAME>

Or

scai connection set-default -l redshift --connection <NAME>

Step 3: Extract, Convert, Deploy

#extract code from source database

scai code extract

#convert to Snowflake SQL

scai code convert

#deploy to Snowflake

scai code deploy

Filtering Objects with the --where Clause¶

Many scai commands operate on the Code Unit Registry – a local index of every code unit (table, view, procedure, function, etc.) in your project. The --where flag lets you filter which objects a command acts on, using a SQL-like expression against that registry.

This section covers how the WHERE clause works, which commands support it, and how to use it effectively.

scai code where

# Show all code units in the registry
scai code find

# Test a WHERE filter
scai code find --where "target.objectType = 'table'"

# Show all results (default caps at 100)
scai code find --where "source.schema = 'dbo'" --no-limit

scai code where          (learn the fields)
        ↓
scai code find --where   (preview what matches)
        ↓
scai <command> --where   (run the operation)

scai code find --where <WHERE_CLAUSE> [--no-limit]

# Find all code units (no filter)
scai code find

# Find a specific object by name
scai code find --where "source.name = 'my_table'"

# Find all procedures in a schema
scai code find --where "source.schema = 'dbo' AND source.objectType = 'procedure'"

# Find objects that failed conversion
scai code find --where "codeStatus.conversion.status = 'failed'"

# Find objects not yet AI-verified
scai code find --where "codeStatus.aiVerification.status = 'pending'"

scai code convert --where <WHERE_CLAUSE> [OPTIONS]

# Convert only procedures
scai code convert --where "source.objectType = 'procedure'"

# Convert objects in a single schema
scai code convert --where "source.schema = 'dbo'"

# Convert only tables and views
scai code convert --where "source.objectType IN ('table', 'view')"

scai code deploy --where <WHERE_CLAUSE> [--include-dependencies] [OPTIONS]

# Deploy only tables
scai code deploy --where "target.objectType = 'table'"

# Deploy procedures and their dependencies (e.g. tables they reference)
scai code deploy --where "target.objectType = 'procedure'" --include-dependencies

# Deploy objects from a single schema
scai code deploy --where "source.schema = 'sales'"

# Deploy a specific object by name
scai code deploy --where "source.name = 'calculate_totals'"

scai ai-convert start --where <WHERE_CLAUSE> [OPTIONS]

# AI-convert only tables
scai ai-convert start --where "target.objectType = 'table'"

# AI-convert objects from a specific schema
scai ai-convert start --where "source.schema = 'dbo'"

# AI-convert a single object by name
scai ai-convert start --where "source.name = 'calculate_totals'"

# Combine with other flags
scai ai-convert start --where "target.objectType = 'procedure'" -w -y
scai ai-convert start --where "source.schema = 'reporting'" -i config/instructions.yml

scai code accept --where <WHERE_CLAUSE>

# Accept only tables
scai code accept --where "source.objectType = 'table'"

# Accept objects from a specific schema
scai code accept --where "source.schema = 'dbo'"

# Accept only successfully converted objects
scai code accept --where "codeStatus.conversion.status = 'completed'"

scai ai-convert accept [JOB_ID] --where <WHERE_CLAUSE> [OPTIONS]

# Preview AI fixes for tables only
scai ai-convert accept --summary --where "source.objectType = 'table'"

# Accept all AI fixes for a specific schema
scai ai-convert accept --all --where "source.schema = 'sales'"

# Interactively review AI fixes for procedures
scai ai-convert accept -i --where "source.objectType = 'procedure'"

scai data migrate --where <WHERE_CLAUSE> [OPTIONS]

# Migrate only tables in the 'public' schema
scai data migrate --where "source.schema = 'public'"

# Migrate a specific table
scai data migrate --where "source.name = 'customers'"

# Migrate tables from a specific database
scai data migrate --where "source.database = 'retail_db'" --source-connection my-redshift

scai data validate --where <WHERE_CLAUSE> [OPTIONS]

# Validate tables in the 'public' schema
scai data validate --where "source.schema = 'public'"

# Validate a specific table after migration
scai data validate --where "source.name = 'customers'"

# Validate with name mappings
scai data validate --where "source.schema = 'dbo'" --db-mapping "mydb:MY_DB" --schema-mapping "dbo:PUBLIC"

# First, see which objects failed
scai code find --where "codeStatus.conversion.status = 'failed'"

# Send only the failed ones for AI conversion
scai ai-convert start --where "codeStatus.conversion.status = 'failed'" -w

# Find objects that haven't gone through AI verification
scai code find --where "codeStatus.aiVerification.status = 'pending'"

# Convert just those
scai ai-convert start --where "codeStatus.aiVerification.status = 'pending'" -w

# Preview: all procedures in the dbo schema
scai code find --where "source.schema = 'dbo' AND source.objectType = 'procedure'"

# Run AI conversion on them
scai ai-convert start --where "source.schema = 'dbo' AND source.objectType = 'procedure'" -w

# Deploy tables first
scai code deploy --where "target.objectType = 'table'"

# Then deploy procedures, pulling in any remaining dependencies
scai code deploy --where "target.objectType = 'procedure'" --include-dependencies

# Deploy everything in the 'sales' schema
scai code deploy --where "source.schema = 'sales'"

AI Convert Quick Guide¶

Use scai ai-convert to improve your converted code with AI. It uploads your converted SQL to Snowflake, analyzes it for functional equivalence issues, generates regression tests, and produces improved code.

Supported languages: SQL Server, Redshift, BigQuery, PostgreSQL

# Convert all objects (default behavior)
scai ai-convert start

# Convert and wait for it to finish (can take minutes to hours depending on code size)
scai ai-convert start -w

# Skip the disclaimer prompt (handy for CI/CD)
scai ai-convert start -y -w

# Convert only specific objects by name
scai ai-convert start -o MY_PROC,MY_VIEW

# Use an instructions file for source system verification
scai ai-convert start -i config/instructions.yml

# Check the last job's status
scai ai-convert status

# Check a specific job
scai ai-convert status JOB_20260310_ABC

# Wait for a job to finish and download results
scai ai-convert status -w

# List all jobs for this project
scai ai-convert list

# Cancel a running job
scai ai-convert cancel

# Preview what changed (default -- no files modified)
scai ai-convert accept --summary

# Review each fix interactively (accept, skip, or diff)
scai ai-convert accept -i

# Accept everything at once
scai ai-convert accept --all

# JSON output for automation
scai ai-convert accept --summary --json

ai-converted/
  └── JOB_<timestamp>_<id>/
      ├── fixed/           AI-improved SQL files organized by object type/schema
      └── tests_sql/       Generated regression tests organized by database/schema

Workflow Examples¶

# Create project
scai init oracle-migration -l Oracle
cd oracle-migration

# Add your PL/SQL files
scai code add -i ./oracle-procs/

# Convert
scai code convert

# Review converted code in converted/ folder, then deploy
scai code deploy --all

# Create project
scai init sqlserver-migration -l SqlServer
cd sqlserver-migration

# Add connection
scai connection add-sql-server

# Extract only the 'sales' schema
scai code extract --schema sales

# Convert
scai code convert

# Deploy
scai code deploy

# Create project
scai init ai-convert-demo -l SqlServer
cd ai-convert-demo

# Add connection
scai connection add-sql-server

# Extract and convert
scai code extract
scai code convert

# Start AI code conversion and wait for completion
scai ai-convert start -w

# Review last executed job results
scai ai-convert status

# Review executed job list
scai ai-convert list

# Create project and convert
scai init selective-demo -l SqlServer
cd selective-demo
scai connection add-sql-server
scai code extract
scai code convert

# Preview what failed conversion
scai code find --where "issues IS NOT NULL AND issues != '[]'"

# Send failed objects through AI conversion
scai ai-convert start --where "issues IS NOT NULL AND issues != '[]'" -w -y

# Deploy only tables first
scai code deploy --where "target.objectType = 'table'"

# Deploy procedures with their dependencies
scai code deploy --where "target.objectType = 'procedure'" --include-dependencies

Getting Help¶

Use –help with any command to see available options:

scai --help
scai init --help
scai code convert --help
scai code where
scai connection add-redshift --help

Troubleshooting¶

“Project file not found” You must run commands from within a project directory. Navigate to your project folder (where the .scai/ directory exists) before running commands:

cd <project-folder>
scai code convert

“Connection not found” (source database)

1. List your connections: scai connection list -l <language>

2. Add a connection if needed: scai connection add-sql-server or scai connection add-redshift

3. Or set a default: scai connection set-default -l <language> –connection-name <name>

“Authentication failed” for Snowflake

The SCAI CLI uses your Snowflake CLI configuration. Ensure your connection is working:

Make sure you have a default Snowflake connection configured in the Snowflake CLI (used when no connection name is specified).

# List available Snowflake connections
snow connection list

# Test your connection
snow connection test

# Add a new connection if needed
snow connection add

“Registry not found” when using --where

The --where flag requires a Code Unit Registry, which is created when you run scai code add or scai code extract. Make sure you’ve run one of those commands before using --where:

# For file-based projects
scai code add -i /path/to/source

# For SQL Server / Redshift extraction
scai code extract

Supported Source Dialects¶

Complete CLI Reference¶

For quick reference, here is every top-level command and subcommand available in the scai CLI: