Snow-Flow Documentation

Installation

Requirements

• Node.js 18+ - Required runtime
• npm 8.0+ - Package manager
• ServiceNow instance - With OAuth configured
• LLM provider - API key or local Ollama

Install via npm

# Global installation (recommended)
npm install -g snow-flow

# Verify installation
snow-flow --version

Quick Start

1. Start Snow-Flow

# Start the TUI (auto-initializes on first run)
snow-flow

# This automatically creates:
# - .mcp.json (MCP server configuration)
# - CLAUDE.md (AI agent instructions)
# - .env (environment configuration)

2. Authenticate (in TUI)

# In the TUI, type /auth to authenticate
/auth

# This configures:
# - LLM provider (Claude, GPT, Gemini, Ollama)
# - ServiceNow OAuth credentials
# - Enterprise features (optional)

3. Start Building

# Just type your request in natural language:
"Create a widget showing high-priority incidents"

"Show me all incidents from last week"

"Create a business rule for auto-assignment"

Authentication Overview

Snow-Flow uses OAuth 2.0 for secure ServiceNow authentication. Credentials are stored securely and automatically refreshed.

Authentication Priority

Snow-Flow checks credentials in this order:

1. Environment variables - Highest priority
2. auth.json - Auto-loaded from Snow-Flow TUI
3. .mcp.json credentials - Project-specific
4. Interactive login - Via /auth command in TUI

ServiceNow OAuth Setup

Create an OAuth application in your ServiceNow instance:

1. Navigate to System OAuth → Application Registry
2. Click New → Create an OAuth API endpoint for external clients
3. Configure:
   • Name: Snow-Flow
   • Redirect URL: http://localhost:3005/callback
   • Refresh Token Lifespan: 0 (unlimited)
4. Copy the Client ID and Client Secret

Credential Storage

Snow-Flow stores credentials securely at:

~/.local/share/snow-flow/auth.json

This file is:

• Created automatically by /auth command in TUI
• Contains encrypted OAuth tokens
• Tokens are automatically refreshed
• Never synced to cloud or version control

Environment Variables (Alternative)

# ServiceNow credentials
SERVICENOW_INSTANCE_URL=https://your-instance.service-now.com
SERVICENOW_CLIENT_ID=your-client-id
SERVICENOW_CLIENT_SECRET=your-client-secret

# Optional: Pre-configured refresh token
SERVICENOW_REFRESH_TOKEN=your-refresh-token

LLM Providers

Snow-Flow supports 75+ AI providers via Models.dev. Configure via environment variables:

Using Ollama (Free, Local)

# Install Ollama
curl -fsSL https://ollama.com/install.sh | sh

# Pull a model
ollama pull llama3.3

# Configure Snow-Flow
DEFAULT_LLM_PROVIDER=ollama
OLLAMA_BASE_URL=http://localhost:11434
DEFAULT_OLLAMA_MODEL=llama3.3

Commands Reference

CLI Commands

TUI Commands (inside Snow-Flow)

TUI Workflow

The Snow-Flow TUI provides an interactive conversational interface for ServiceNow development:

# Create a widget
"Create a dashboard widget for incident metrics"

# Automate a process
"Create business rule to auto-assign incidents by category"

# Query and analyze
"Analyze incident trends from the past month"

# Complex task with multiple agents
"Build a complete workspace for IT support"

MCP Tools Overview

Snow-Flow provides 385+ MCP tools across 80 functional domains, all accessible through natural language commands via the unified MCP architecture.

Complete Tool Reference

All tools follow the snow_* naming convention. Below is the complete list organized by domain.

Operations (24 tools)

Core CRUD operations and data management.

Security & Compliance (18 tools)

Security policies, vulnerability scanning, and compliance management.

Automation (18 tools)

Script execution, scheduling, and workflow automation.

Integration & MID Server (17 tools)

REST/SOAP integrations, data mapping, external connections, and MID Server management.

CMDB (13 tools)

Configuration Management Database operations.

UI Builder (12 tools)

Next Experience UI Builder pages and components.

Deployment (11 tools)

Artifact deployment and management.

Workspace (10 tools)

Agent Workspace and UX configuration.

Development Assistant (10 tools)

Intelligent development helpers.

Platform Development (12 tools)

Business rules, client scripts, UI policies.

Update Sets (8 tools)

Change management and deployment.

Service Portal (10 tools)

Widgets, pages, and portal configuration.

Virtual Agent (7 tools)

Virtual Agent NLU and conversations.

Mobile (7 tools)

Mobile app configuration.

AI & Machine Learning (8 tools)

Predictive intelligence and ML features.

Asset Management (8 tools)

Asset lifecycle and license management.

Change Management (8 tools)

Change requests and CAB management.

Knowledge Management (7 tools)

Knowledge base articles and management.

Flow Designer (8 tools)

Flow Designer automation.

Reporting & Analytics (8 tools)

Reports, dashboards, and analytics.

Automated Test Framework (6 tools)

Test automation and validation.

Notifications (7 tools)

Notification management and delivery.

MCP Configuration

The .mcp.json file configures MCP servers:

{
  "mcp": {
    "servicenow-unified": {
      "type": "local",
      "command": ["node", "dist/mcp/servicenow-mcp-unified/index.js"],
      "environment": {
        "SERVICENOW_INSTANCE_URL": "{{SNOW_INSTANCE}}",
        "SERVICENOW_CLIENT_ID": "{{SNOW_CLIENT_ID}}",
        "SERVICENOW_CLIENT_SECRET": "{{SNOW_CLIENT_SECRET}}"
      },
      "enabled": true
    }
  }
}

Use With Any AI IDE

Snow-Flow works with any MCP-compatible AI tool. When you start Snow-Flow for the first time, it automatically generates configuration at .mcp.json and syncs to .snow-code/config.json.

Setup for Claude Desktop

Claude Desktop uses a different key (mcpServers) than other tools:

# macOS config location
~/Library/Application Support/Claude/claude_desktop_config.json

# Windows config location
%APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "servicenow-unified": {
      "command": "node",
      "args": ["/path/to/snow-flow/dist/mcp/servicenow-mcp-unified/index.js"],
      "env": {
        "SERVICENOW_INSTANCE_URL": "https://your-instance.service-now.com",
        "SERVICENOW_CLIENT_ID": "your-client-id",
        "SERVICENOW_CLIENT_SECRET": "your-client-secret"
      }
    }
  }
}

Setup for Cursor

# After starting snow-flow once, copy config to Cursor
cp .mcp.json .cursor/mcp.json

# Or create .cursor directory first
mkdir -p .cursor && cp .mcp.json .cursor/mcp.json

Setup for Windsurf

# After starting snow-flow once, copy config to Windsurf
cp .mcp.json mcp_config.json

Setup for Continue.dev

# Continue.dev config location
~/.continue/config.json

Add the MCP servers to your Continue.dev config:

{
  "experimental": {
    "modelContextProtocolServers": [
      {
        "transport": {
          "type": "stdio",
          "command": "node",
          "args": ["/path/to/snow-flow/dist/mcp/servicenow-mcp-unified/index.js"]
        }
      }
    ]
  }
}

# Global npm installation
npm root -g
# Output: /usr/local/lib/node_modules
# Full path: /usr/local/lib/node_modules/snow-flow/dist/mcp/...

# Or use which to find the binary
which snow-flow

ES5 JavaScript Requirement

ES6+ Features That WILL CRASH

// ALL OF THESE BREAK SERVICENOW:
const x = 5;                    // SyntaxError
let items = [];                 // SyntaxError
const fn = () => {};            // SyntaxError
var msg = `Hello ${name}`;      // SyntaxError
for (let item of items) {}    // SyntaxError
var {name, id} = user;          // SyntaxError
array.map(x => x.id);           // SyntaxError
class MyClass {}                // SyntaxError

Correct ES5 Syntax

// THESE WORK IN SERVICENOW:
var x = 5;
var items = [];
function fn() { return 'result'; }
var msg = 'Hello ' + name;
for (var i = 0; i < items.length; i++) {
  var item = items[i];
}
var name = user.name;
var id = user.id;

Update Set Management

Update Sets track ALL changes for deployment between instances. Always create an Update Set before making changes.

Workflow

// 1. Create Update Set FIRST
snow_update_set_manage({
  action: 'create',
  name: "Feature: Incident Dashboard",
  description: "Widget showing incident metrics"
});

// 2. Develop (changes auto-tracked)
snow_create_artifact({...});
snow_create_business_rule({...});

// 3. Complete Update Set
snow_update_set_manage({
  action: 'complete',
  update_set_id: 'sys_id_here'
});

Widget Coherence

ServiceNow widgets require perfect synchronization between Server Script, Client Script, and HTML Template.

The Three-Way Contract

// SERVER SCRIPT - Initialize data
data.message = "Hello";
data.items = [];
if (input.action === 'loadItems') {
  data.items = getItems();
}

// CLIENT SCRIPT - Handle UI interactions
c.loadItems = function() {
  c.server.get({action: 'loadItems'}).then(function() {
    console.log(c.data.items);
  });
};

// HTML TEMPLATE - Display data
<button ng-click="loadItems()">Load</button>
<div ng-repeat="item in data.items">{{item}}</div>

Coherence Checklist

• Every data.property in server is used in HTML/client
• Every ng-click="method()" in HTML has matching c.method in client
• Every c.server.get({action}) in client has matching if(input.action) in server

Enterprise Features Enterprise

Snow-Flow Enterprise adds powerful integrations for team workflows:

Integration Setup

# In the TUI, authenticate with enterprise features
/auth

# Connect Jira
# (Follow prompts to authorize)

# Then in the TUI, complete a Jira story:
"Complete JIRA-1234"