Nuvia Code

AI-powered command-line tool for Snowflake Cortex

Installation • Quick Start • Features • Documentation

Nuvia Code is a powerful command-line AI workflow tool forked from Qwen Code, specifically optimized to use Snowflake Cortex for LLM inference. It enhances your development workflow with advanced code understanding, automated tasks, and intelligent assistance powered by Snowflake's enterprise-grade AI platform.

💡 Why Nuvia Code?

• Enterprise-Ready: Leverage Snowflake Cortex's secure, scalable infrastructure
• Multiple Models: Access Claude, Mistral, Llama, Reka, and more through a single interface
• Flexible Authentication: Support for JWT (key-pair), OAuth, and access tokens
• Data Governance: Keep your data secure within your Snowflake environment
• Cost-Effective: Pay only for what you use with Snowflake's consumption-based pricing

Key Features

• Code Understanding & Editing - Query and edit large codebases with Snowflake Cortex models
• Workflow Automation - Automate operational tasks like handling pull requests and complex rebases
• Multi-Model Support - Choose from Claude 3.7 Sonnet, Mistral Large 2, Llama 3.1, and more
• Secure Authentication - Multiple authentication methods including JWT and OAuth

Installation

Prerequisites

Ensure you have Node.js version 20 or higher installed.

curl -qL https://www.npmjs.com/install.sh | sh

Install from npm

npm install -g @dontizi/nuvia-code@latest
nuvia --version

Install from source

git clone https://github.com/YOUR_USERNAME/cortex-code.git
cd cortex-code
npm install
npm install -g .

Quick Start

1. Configure Snowflake Authentication

Nuvia Code supports three authentication methods:

Method 1: JWT Authentication (Key Pair) - Recommended

# Set your Snowflake account and credentials
export SNOWFLAKE_ACCOUNT="myorg-myaccount"
export SNOWFLAKE_USER="myusername"
export SNOWFLAKE_PRIVATE_KEY_PATH="/path/to/private_key.pem"
export SNOWFLAKE_PRIVATE_KEY_PASSPHRASE="your_passphrase"  # Optional

# Optional: Configure warehouse, role, etc.
export SNOWFLAKE_WAREHOUSE="MY_WAREHOUSE"
export SNOWFLAKE_ROLE="MY_ROLE"
export SNOWFLAKE_MODEL="mistral-large2"  # Default model

Method 2: Access Token (JWT or PAT)

export SNOWFLAKE_ACCOUNT="myorg-myaccount"
export SNOWFLAKE_ACCESS_TOKEN="your_jwt_or_pat_token"
export SNOWFLAKE_MODEL="claude-3-7-sonnet"

Method 3: OAuth Token

export SNOWFLAKE_ACCOUNT="myorg-myaccount"
export SNOWFLAKE_OAUTH_TOKEN="your_oauth_token"
export SNOWFLAKE_MODEL="mistral-large2"

2. Start Nuvia Code

nuvia

3. Start Coding!

# Example commands
> Explain this codebase structure
> Help me refactor this function
> Generate unit tests for this module

Available Models

Nuvia Code supports all Snowflake Cortex LLM models:

| Model | Context Window | Max Output | Best For | |-------|----------------|------------|----------| | claude-3-7-sonnet | 200K tokens | 8K tokens | Complex reasoning, code generation | | claude-3.5-sonnet | 200K tokens | 8K tokens | Balanced performance | | claude-3.5-haiku | 200K tokens | 8K tokens | Fast responses | | mistral-large2 | 128K tokens | 8K tokens | General purpose (default) | | llama3.1-70b | 128K tokens | 4K tokens | Open-source alternative | | reka-core | 128K tokens | 8K tokens | Multilingual support | | snowflake-arctic | 128K tokens | 4K tokens | Snowflake-optimized | | jamba-1.5-large | 256K tokens | 16K tokens | Long context tasks |

Configuration

Environment Variables

Create a .env file in your project root or set environment variables:

# Required
SNOWFLAKE_ACCOUNT=myorg-myaccount          # Your Snowflake account identifier

# Authentication (choose one method)
SNOWFLAKE_PRIVATE_KEY_PATH=/path/to/key.pem
SNOWFLAKE_USER=myusername
# OR
SNOWFLAKE_ACCESS_TOKEN=your_token
# OR
SNOWFLAKE_OAUTH_TOKEN=your_oauth_token

# Optional
SNOWFLAKE_WAREHOUSE=MY_WAREHOUSE            # Warehouse to use for queries
SNOWFLAKE_ROLE=MY_ROLE                      # Role for authentication
SNOWFLAKE_DATABASE=MY_DATABASE              # Default database
SNOWFLAKE_SCHEMA=MY_SCHEMA                  # Default schema
SNOWFLAKE_MODEL=mistral-large2              # Default: mistral-large2

Generating Key Pair for JWT Authentication

1. Generate a private key:

openssl genrsa 2048 | openssl pkcs8 -topk8 -inform PEM -out rsa_key.p8 -nocrypt

2. Generate public key:

openssl rsa -in rsa_key.p8 -pubout -out rsa_key.pub

3. Add the public key to your Snowflake user:

ALTER USER myusername SET RSA_PUBLIC_KEY='MIIBIjANBg...';

4. Configure Nuvia Code:

export SNOWFLAKE_PRIVATE_KEY_PATH="/path/to/rsa_key.p8"
export SNOWFLAKE_USER="myusername"
export SNOWFLAKE_ACCOUNT="myorg-myaccount"

MCP Snowflake Integration

Nuvia Code supports Model Context Protocol (MCP) integration with Snowflake, allowing you to access Snowflake agents, execute SQL queries, and interact with Cortex services directly from the CLI.

Prerequisites for MCP Setup

1. Snowflake Account with Cortex access
2. Appropriate Roles and Permissions (see below)
3. MCP Server configured in Snowflake
4. Agents (optional) for specialized tasks

Step 1: Configure Snowflake Permissions

Required Privileges for MCP Server

-- Create a role for MCP operations (as ACCOUNTADMIN)
USE ROLE ACCOUNTADMIN;
CREATE ROLE MCP_AGENT_ADMIN;

-- Grant global privileges
GRANT CREATE AGENT ON ACCOUNT TO ROLE MCP_AGENT_ADMIN;
GRANT USAGE ON WAREHOUSE COMPUTE_WH TO ROLE MCP_AGENT_ADMIN;

-- Grant database and schema privileges
GRANT USAGE ON DATABASE <your_database> TO ROLE MCP_AGENT_ADMIN;
GRANT USAGE ON SCHEMA <your_database>.<your_schema> TO ROLE MCP_AGENT_ADMIN;
GRANT CREATE MCP SERVER ON SCHEMA <your_database>.<your_schema> TO ROLE MCP_AGENT_ADMIN;

-- Assign role to user
GRANT ROLE MCP_AGENT_ADMIN TO USER <your_username>;

Privileges for Agents (if using Cortex Agents)

-- Grant privileges on existing agents
GRANT USAGE ON AGENT <database>.<schema>.<agent_name> TO ROLE MCP_AGENT_ADMIN;
GRANT MONITOR ON AGENT <database>.<schema>.<agent_name> TO ROLE MCP_AGENT_ADMIN;

Step 2: Create MCP Server in Snowflake

Create an MCP server that exposes tools and agents:

CREATE OR REPLACE MCP SERVER <your_database>.<your_schema>.<server_name>
  FROM SPECIFICATION $
    tools:
      # SQL Execution Tool
      - title: "SQL Execution Tool"
        name: "sql_exec_tool"
        type: "SYSTEM_EXECUTE_SQL"
        description: "Execute SQL queries against the Snowflake database for data retrieval, analysis, and manipulation."
      
      # Cortex Agent (if you have one)
      - title: "Snowflake Documentation Agent"
        name: "snowflake_doc_agent"
        type: "CORTEX_AGENT_RUN"
        identifier: "<database>.<schema>.<agent_name>"
        description: "Agent expert en documentation Snowflake pour répondre aux questions techniques"
      
      # Cortex Search Service (optional)
      - title: "Document Search"
        name: "document_search"
        type: "CORTEX_SEARCH_SERVICE_QUERY"
        identifier: "<database>.<schema>.<search_service_name>"
        description: "Search through documents using Cortex Search"
      
      # Cortex Analyst (optional)
      - title: "Business Analyst"
        name: "business_analyst"
        type: "CORTEX_ANALYST_MESSAGE"
        identifier: "<database>.<schema>.<semantic_model>"
        description: "Business intelligence and analytics queries"
  $;

Step 3: Configure Nuvia Code MCP Settings

Global Configuration

Add MCP server configuration to ~/.nuvia/settings.json:

{
  "mcpServers": {
    "snowflake-mcp": {
      "httpUrl": "https://<account>.snowflakecomputing.com/api/v2/databases/<database>/schemas/<schema>/mcp-servers/<server_name>",
      "headers": {
        "Authorization": "Bearer <your_access_token>",
        "X-Snowflake-Role": "MCP_AGENT_ADMIN",
        "X-Snowflake-Warehouse": "COMPUTE_WH"
      },
      "timeout": 30000,
      "description": "Snowflake MCP server for SQL execution and agent access",
      "trust": false
    }
  }
}

Project-Level Configuration

Alternatively, create .mcp.json in your project root:

{
  "mcpServers": {
    "snowflake-project": {
      "url": "https://<account>.snowflakecomputing.com/api/v2/databases/<database>/schemas/<schema>/mcp-servers/<server_name>",
      "headers": {
        "Authorization": "Bearer <your_access_token>",
        "X-Snowflake-Role": "MCP_AGENT_ADMIN",
        "X-Snowflake-Warehouse": "COMPUTE_WH"
      },
      "timeout": 30000,
      "trust": false
    }
  }
}

Step 4: Authentication Token Setup

Option 1: Use Existing Access Token

If you already have a Snowflake access token:

export SNOWFLAKE_ACCESS_TOKEN="your_jwt_or_pat_token"

Option 2: Generate JWT Token

For JWT authentication, Nuvia Code will automatically generate tokens using your configured credentials:

export SNOWFLAKE_ACCOUNT="myorg-myaccount"
export SNOWFLAKE_USER="myusername"
export SNOWFLAKE_PRIVATE_KEY_PATH="/path/to/private_key.p8"
export SNOWFLAKE_ROLE="MCP_AGENT_ADMIN"
export SNOWFLAKE_WAREHOUSE="COMPUTE_WH"

Step 5: Verify MCP Setup

Start Nuvia Code and test the MCP integration:

nuvia

# Test SQL execution
> Execute this SQL query: SELECT CURRENT_VERSION()

# Test agent (if configured)
> Ask the Snowflake documentation agent: How do I create a table?

# List available MCP tools
> What MCP tools are available?

Available MCP Tool Types

| Tool Type | Description | Example Use Case | |-----------|-------------|------------------| | SYSTEM_EXECUTE_SQL | Execute SQL queries | Data analysis, schema exploration | | CORTEX_AGENT_RUN | Run Cortex agents | Documentation help, specialized Q&A | | CORTEX_SEARCH_SERVICE_QUERY | Search services | Document search, knowledge retrieval | | CORTEX_ANALYST_MESSAGE | Business analytics | BI queries, semantic analysis | | CUSTOM | Custom UDF/procedures | Specialized business logic |

Example: Setting up Documentation Agent

1. Create the agent in Snowflake:

-- This is typically done by Snowflake for system agents
-- For custom agents, use CREATE AGENT command

2. Add to MCP server:

CREATE OR REPLACE MCP SERVER MY_DB.PUBLIC.MY_SERVER
  FROM SPECIFICATION $
    tools:
      - title: "Snowflake Documentation Agent"
        name: "snowflake_doc_agent"
        type: "CORTEX_AGENT_RUN"
        identifier: "SNOWFLAKE_INTELLIGENCE.AGENTS.SNOWFLAKE_DOCS"
        description: "Expert agent for Snowflake documentation questions"
  $;

3. Grant permissions:

GRANT USAGE ON AGENT SNOWFLAKE_INTELLIGENCE.AGENTS.SNOWFLAKE_DOCS TO ROLE MCP_AGENT_ADMIN;

4. Test in Nuvia Code:

> Ask the documentation agent: What are the best practices for warehouse sizing?

Troubleshooting MCP Setup

Issue: "MCP server not found"

• Verify the server URL format and credentials
• Check that the MCP server exists: SHOW MCP SERVERS IN SCHEMA <schema>;

Issue: "Agent access denied"

• Ensure USAGE privilege is granted on the agent
• Verify the agent identifier is correct
• Check that your role has the necessary permissions

Issue: "Tool not available"

• Confirm the tool is defined in the MCP server specification
• Restart Nuvia Code to refresh MCP tool discovery
• Check MCP server configuration with DESCRIBE MCP SERVER <server_name>;

Security Considerations

1. Use least privilege: Grant only necessary permissions to MCP roles
2. Rotate tokens: Regularly refresh access tokens
3. Network security: Ensure secure connections to Snowflake
4. Audit access: Monitor MCP tool usage through Snowflake query history
5. Trust settings: Set "trust": false for additional confirmation prompts

Session Management

Control your token usage with configurable session limits:

Configure Session Token Limit

Create or edit .nuvia/settings.json in your home directory:

{
  "sessionTokenLimit": 32000
}

Session Commands

• /compress - Compress conversation history to continue within token limits
• /clear - Clear all conversation history and start fresh
• /stats - Check current token usage and limits

Usage Examples

🔍 Explore Codebases

cd your-project/
nuvia

# Architecture analysis
> Describe the main pieces of this system's architecture
> What are the key dependencies and how do they interact?
> Find all API endpoints and their authentication methods

💻 Code Development

# Refactoring
> Refactor this function to improve readability and performance
> Convert this class to use dependency injection

# Code generation
> Create a REST API endpoint for user management
> Generate unit tests for the authentication module

🔄 Automate Workflows

# Git automation
> Analyze git commits from the last 7 days
> Create a changelog from recent commits

# File operations
> Rename all test files to follow the *.test.ts pattern
> Find and remove all console.log statements

Commands & Shortcuts

Session Commands

• /help - Display available commands
• /clear - Clear conversation history
• /compress - Compress history to save tokens
• /stats - Show current session information
• /exit or /quit - Exit Nuvia Code

Keyboard Shortcuts

• Ctrl+C - Cancel current operation
• Ctrl+D - Exit (on empty line)
• Up/Down - Navigate command history

Architecture

Nuvia Code is built on a modular architecture:

• CLI Package (packages/cli) - User-facing interface
• Core Package (packages/core) - Backend logic and tool orchestration
• Snowflake Module (packages/core/src/snowflake) - Snowflake Cortex integration
  • Authentication (JWT, OAuth, PAT)
  • Token management
  • Provider implementation

For detailed architecture documentation, see CLAUDE.md.

Development

Build from Source

# Install dependencies
npm install

# Build the project
npm run build

# Run from source
npm start

Testing

# Unit tests
npm run test

# Integration tests
npm run test:e2e

# Linting
npm run lint
npm run lint:fix

# Type checking
npm run typecheck

Troubleshooting

Authentication Errors

Issue: Failed to initialize Snowflake Cortex: No valid authentication method

Solution: Ensure you have set at least one authentication method:

• JWT: Set SNOWFLAKE_PRIVATE_KEY_PATH and SNOWFLAKE_USER
• Access Token: Set SNOWFLAKE_ACCESS_TOKEN
• OAuth: Set SNOWFLAKE_OAUTH_TOKEN

Connection Errors

Issue: Connection timeout or "account not found"

Solution: Verify your SNOWFLAKE_ACCOUNT identifier format:

• Correct: myorg-myaccount or xy12345.us-east-1
• The account identifier can be found in your Snowflake URL

Model Not Found

Issue: Model name not recognized

Solution: Use the exact model names as listed in Available Models. Model names are case-sensitive.

Security Best Practices

1. Never commit credentials: Add .env to your .gitignore
2. Use encrypted keys: Protect your private keys with passphrases
3. Rotate tokens regularly: Refresh OAuth and access tokens periodically
4. Limit permissions: Use Snowflake roles with minimal required permissions
5. Store keys securely: Use secure key management systems in production

Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

License

Apache-2.0

Acknowledgments

This project is forked from Qwen Code, which is based on Google Gemini CLI. We acknowledge and appreciate the excellent work of both teams.

Links

• Snowflake Cortex Documentation
• Snowflake Cortex REST API
• Issue Tracker