### Quick Start Installation

Source: https://nowaikit.com/docs

Commands to install the toolkit globally and initiate the setup wizard.

```bash
$npm install -g nowaikit
$npx nowaikit --setup
```

--------------------------------

### Install and run the interactive setup wizard

Source: https://nowaikit.com/docs/installation

Use npm to install the CLI globally and launch the guided setup process.

```bash
$ npm install -g nowaikit
$ npx nowaikit setup
```

--------------------------------

### Install via npx

Source: https://nowaikit.com/docs/download

Use npx to run the setup wizard without a global installation.

```bash
$ npx nowaikit@latest setup
```

--------------------------------

### Setup Google Gemini Client

Source: https://nowaikit.com/docs/client-setup

Install dependencies for the Gemini integration.

```bash
$ cd clients/gemini
$ pip install google-generativeai python-dotenv
```

--------------------------------

### Install NowAIKit MCP Server

Source: https://nowaikit.com/docs/connected-services

Run this command in your terminal to launch the interactive setup wizard for configuring instance credentials.

```bash
npx nowaikit@latest
```

--------------------------------

### Run NowAIKit Setup Wizard

Source: https://nowaikit.com/docs

Execute the interactive setup wizard to configure instance connection and authentication.

```bash
$ npx nowaikit --setup
```

--------------------------------

### Test with natural language prompt

Source: https://nowaikit.com/docs/installation

Example prompt for verifying the installation in an AI client.

```text
"List my 5 most recent open incidents"
```

--------------------------------

### Setup OpenAI Codex Client

Source: https://nowaikit.com/docs/client-setup

Install required dependencies for the OpenAI integration.

```bash
$ cd clients/codex
$ pip install openai python-dotenv
```

--------------------------------

### Install SDK

Source: https://nowaikit.com/docs/sdk-quickstart

Commands to install the SDK using common package managers.

```bash
npm install nowaikit-sdk
```

```bash
bun add nowaikit-sdk
```

--------------------------------

### Start MCP Server

Source: https://nowaikit.com/docs/oauth-setup

Build and start the MCP server to verify authentication.

```bash
$ cd nowaikit
$ npm run build
$ npm start
```

--------------------------------

### One-line install scripts

Source: https://nowaikit.com/docs/download

Automated installation scripts for macOS/Linux and Windows.

```bash
curl -fsSL https://nowaikit.com/install.sh | bash
```

```powershell
irm https://nowaikit.com/install.ps1 | iex
```

--------------------------------

### Install via Homebrew

Source: https://nowaikit.com/docs/download

Use Homebrew to install NowAIKit on macOS or Linux.

```bash
$ brew tap aartiq/tap
$ brew install nowaikit
```

--------------------------------

### Configure standalone binary on Windows

Source: https://nowaikit.com/docs/installation

Run the setup command after moving the executable to a folder in your PATH.

```powershell
# Move to a folder in your PATH, then run:
> .\nowaikit-Setup-2.4.0.exe setup
```

--------------------------------

### Start HTTP server and call a tool

Source: https://nowaikit.com/docs/installation

Starts the Nowaikit HTTP server and executes a tool call using curl.

```bash
# Terminal 1 — start the server
$ TRANSPORT=http PORT=3000 NOWAIKIT_API_KEY=my-key npx nowaikit

# Terminal 2 — call a tool via REST API
$ curl -X POST http://localhost:3000/api/tool \
  -H 'Authorization: Bearer my-key' \
  -H 'Content-Type: application/json' \
  -d '{"name":"get_incident","arguments":{"number_or_sysid":"INC0010001"}}'
```

--------------------------------

### Install NowAIKit globally

Source: https://nowaikit.com/docs

Install the package globally using npm.

```bash
$ npm install -g nowaikit
```

--------------------------------

### Start NowAIKit with SSE

Source: https://nowaikit.com/docs/installation

Launch the server using SSE transport to enable the web dashboard.

```bash
# Start with SSE transport and open dashboard
$ TRANSPORT=sse npx nowaikit
# Then open http://localhost:3000 in your browser
```

--------------------------------

### Configure package.json

Source: https://nowaikit.com/docs/sdk-quickstart

Example dependency configuration for the SDK.

```json
{
  "dependencies": {
    "nowaikit-sdk": "^2.0.0"
  }
}
```

--------------------------------

### Clone and build the project

Source: https://nowaikit.com/docs/installation

Commands to download the repository, install dependencies, and build the project.

```bash
$ git clone https://github.com/aartiq/nowaikit.git
$ cd nowaikit
$ npm install
$ npm run build
```

--------------------------------

### Configure Authentication Methods

Source: https://nowaikit.com/docs/sdk-quickstart

Examples for setting up the client using Basic Auth, OAuth 2.0, or Token-based authentication.

```typescript
const kit = new NowAIKit({
  instance: 'your-instance.service-now.com',
  auth: {
    type: 'basic',
    username: process.env.SN_USERNAME,
    password: process.env.SN_PASSWORD
  }
});
```

```typescript
const kit = new NowAIKit({
  instance: 'your-instance.service-now.com',
  auth: {
    type: 'oauth',
    clientId: process.env.SN_CLIENT_ID,
    clientSecret: process.env.SN_CLIENT_SECRET,
    username: process.env.SN_USERNAME,
    password: process.env.SN_PASSWORD
  }
});
```

```typescript
const kit = new NowAIKit({
  instance: 'your-instance.service-now.com',
  auth: {
    type: 'token',
    accessToken: process.env.SN_ACCESS_TOKEN
  }
});
```

--------------------------------

### Verify NowAIKit installation

Source: https://nowaikit.com/docs

Check the installed version of the CLI.

```bash
$ nowaikit --version
3.0.0
```

--------------------------------

### Configure Now Assist environment variables

Source: https://nowaikit.com/docs/now-assist

Example .env file configuration for Now Assist development, including instance URL and authentication credentials.

```bash
# .env for Now Assist developer
SERVICENOW_INSTANCE_URL=https://yourinstance.service-now.com
SERVICENOW_AUTH_METHOD=oauth
SERVICENOW_OAUTH_CLIENT_ID=your_client_id
SERVICENOW_OAUTH_CLIENT_SECRET=your_client_secret
SERVICENOW_OAUTH_USERNAME=your_username
SERVICENOW_OAUTH_PASSWORD=your_password

NOW_ASSIST_ENABLED=true
MCP_TOOL_PACKAGE=ai_developer
```

--------------------------------

### Install globally via npm

Source: https://nowaikit.com/docs/download

Install the package globally to access the CLI command directly.

```bash
$ npm install -g nowaikit
$ nowaikit setup
```

--------------------------------

### Install VS Code extension via CLI

Source: https://nowaikit.com/docs/download

Install the NowAIKit Builder extension using the VS Code command line interface.

```bash
code --install-extension aartiq.nowaikit-builder
```

--------------------------------

### Start MCP server

Source: https://nowaikit.com/docs

Launch the MCP server for AI client connectivity, optionally enabling write operations.

```bash
# Start the MCP server (used in AI client configs)
$ npx -y nowaikit

# With write operations enabled
$ npx -y nowaikit --allow-write
```

--------------------------------

### GET /sse

Source: https://nowaikit.com/docs/installation

Establish an SSE connection for real-time streaming.

```APIDOC
## GET /sse

### Description
Establish an SSE connection for real-time streaming.

### Method
GET

### Endpoint
/sse
```

--------------------------------

### Start SSE Transport

Source: https://nowaikit.com/docs/installation

Launch the server with the SSE transport mode enabled.

```bash
$ TRANSPORT=sse npx nowaikit
```

--------------------------------

### Start NowAIKit as an HTTP server

Source: https://nowaikit.com/docs

Launch the application as a streamable HTTP server on a specified port.

```bash
# Start NowAIKit as an HTTP server on port 3000
$ TRANSPORT=http PORT=3000 npx nowaikit

# Output:
# NowAIKit v4.0.0 — Streamable HTTP on http://localhost:3000
# Dashboard:   http://localhost:3000/
# MCP endpoint: http://localhost:3000/mcp
# REST API:    http://localhost:3000/api/*
# A2A:         http://localhost:3000/.well-known/agent.json
```

--------------------------------

### GET /api/instances

Source: https://nowaikit.com/docs/installation

Lists configured ServiceNow instances.

```APIDOC
## GET /api/instances

### Description
List configured ServiceNow instances.

### Method
GET

### Endpoint
/api/instances
```

--------------------------------

### Start Streamable HTTP Transport

Source: https://nowaikit.com/docs/installation

Launch the server with the Streamable HTTP transport mode enabled.

```bash
$ TRANSPORT=http npx nowaikit
```

--------------------------------

### Start the HTTP API Server

Source: https://nowaikit.com/docs

Commands to launch the REST API server for accessing ServiceNow tools via HTTP endpoints.

```bash
$ npm run serve
# or
$ node dist/http-server.js
```

--------------------------------

### Cross-Customer Query Example

Source: https://nowaikit.com/docs/multi-instance

Shows how the AI utilizes the configured instances to perform operations across different customer environments.

```text
AI uses: query_records { "table": "incident", "query": "priority=1^state!=6", "instance": "client_acme" }
AI uses: query_records { "table": "incident", "query": "priority=1^state!=6", "instance": "client_globex" }
# { Acme: 3, Globex: 7 }
```

--------------------------------

### GET /api/prompts

Source: https://nowaikit.com/docs/installation

Lists available prompts.

```APIDOC
## GET /api/prompts

### Description
List available prompts.

### Method
GET

### Endpoint
/api/prompts
```

--------------------------------

### GET /api/tools

Source: https://nowaikit.com/docs/installation

List all available tools.

```APIDOC
## GET /api/tools

### Description
List all available tools.

### Method
GET

### Endpoint
/api/tools
```

--------------------------------

### Check Node.js version

Source: https://nowaikit.com/docs/installation

Command to verify the installed Node.js version meets the minimum requirement.

```bash
node --version
```

--------------------------------

### Configure Auto-start Sync

Source: https://nowaikit.com/docs/connected-services

Add this setting to your VS Code configuration to automatically start the sync bridge upon instance connection.

```json
"nowaikit-builder.syncAutoStart": true
```

--------------------------------

### GET /api/tools

Source: https://nowaikit.com/docs

Lists all available tools provided by the NowAIKit instance.

```APIDOC
## GET /api/tools

### Description
Retrieves a list of all tools available for execution.

### Method
GET

### Endpoint
/api/tools

### Parameters
#### Headers
- **Authorization** (string) - Required - Bearer token for authentication.
```

--------------------------------

### Start Script Sync Bridge

Source: https://nowaikit.com/docs/connected-services

Execute this command in the VS Code Command Palette to enable the WebSocket bridge for script synchronization.

```text
NowAIKit: Start Script Sync
```

--------------------------------

### Invoke build-atf-suite Capability

Source: https://nowaikit.com/docs/atf-testing

Example conversation prompt to trigger the automated test suite generation workflow.

```text
# Ask your AI assistant:
Build an ATF suite for the incident management process with standard coverage

# The assistant will walk through each step, asking for input
# and generating tests along the way. At the end, the suite
# is created on your instance via run_atf_suite / create tools.
```

--------------------------------

### Run NowAIKit via npx

Source: https://nowaikit.com/docs

Execute NowAIKit without global installation using npx.

```bash
$ npx -y nowaikit
```

--------------------------------

### Extended ATF Configuration

Source: https://nowaikit.com/docs/atf-testing

Configuration example including the MCP tool package for platform development.

```env
ATF_ENABLED=true
WRITE_ENABLED=true
MCP_TOOL_PACKAGE=platform_developer
```

--------------------------------

### Execute Fluent Queries in TypeScript

Source: https://nowaikit.com/docs/sdk-api-reference

Examples of standard record retrieval, aggregate calculations, and complex OR filtering using the fluent interface.

```typescript
const results = await kit.fluent('incident')
  .where('active', true)
  .where('priority', '<=', 2)
  .orderByDesc('sys_created_on')
  .limit(25)
  .select('number', 'short_description', 'state');

// Aggregate query
const counts = await kit.fluent('incident')
  .where('active', true)
  .groupBy('category')
  .aggregate('COUNT');

// With OR conditions
const urgent = await kit.fluent('incident')
  .where('active', true)
  .orWhere('priority', 1)
  .orWhere('impact', 1)
  .select('number', 'short_description', 'priority', 'impact')
  .limit(50);
```

--------------------------------

### GET /a2a/tasks/:id

Source: https://nowaikit.com/docs/installation

Gets the status or result of a specific task.

```APIDOC
## GET /a2a/tasks/:id

### Description
Get the status/result of a task.

### Method
GET

### Endpoint
/a2a/tasks/:id

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the task.
```

--------------------------------

### fluent_init

Source: https://nowaikit.com/docs/sdk-fluent

Scaffolds a new Fluent project directory with all required configuration and starter templates.

```APIDOC
## fluent_init

### Description
Scaffolds a new Fluent project directory with all required configuration and starter templates.

### Request Body
- **name** (string) - Required - The name of the project
- **scope** (string) - Required - The project scope
- **instance** (string) - Required - The service instance URL
- **template** (string) - Required - The template type to use

### Request Example
{
  "name": "my-fluent-app",
  "scope": "x_myapp",
  "instance": "your-instance.service-now.com",
  "template": "workspace"
}
```

--------------------------------

### Scaffold a project with fluent_init

Source: https://nowaikit.com/docs/sdk-fluent

Initializes a new Fluent project directory with the specified configuration.

```json
{
  "name": "my-fluent-app",
  "scope": "x_myapp",
  "instance": "your-instance.service-now.com",
  "template": "workspace"
}
```

--------------------------------

### GET /

Source: https://nowaikit.com/docs/installation

Access the web dashboard.

```APIDOC
## GET /

### Description
Access the web dashboard.

### Method
GET

### Endpoint
/
```

--------------------------------

### service_mapping_summary

Source: https://nowaikit.com/docs/tools-reference

Get service mapping data.

```APIDOC
## service_mapping_summary

### Description
Get service mapping data.
```

--------------------------------

### Configure environment variables

Source: https://nowaikit.com/docs/installation

Commands to initialize the environment file and the required configuration keys.

```bash
$ cp .env.example .env
```

```text
SERVICENOW_INSTANCE_URL=https://yourcompany.service-now.com
SERVICENOW_AUTH_METHOD=basic
SERVICENOW_BASIC_USERNAME=your_username
SERVICENOW_BASIC_PASSWORD=your_password
```

--------------------------------

### Configure Single Instance (Backwards-Compatible)

Source: https://nowaikit.com/docs/multi-instance

Use legacy environment variables to register a single instance as the default.

```text
SERVICENOW_INSTANCE_URL=https://yourinstance.service-now.com
SERVICENOW_AUTH_METHOD=basic
SERVICENOW_BASIC_USERNAME=admin
SERVICENOW_BASIC_PASSWORD=password
```

--------------------------------

### GET /api/resources

Source: https://nowaikit.com/docs/installation

Lists available resources.

```APIDOC
## GET /api/resources

### Description
List available resources.

### Method
GET

### Endpoint
/api/resources
```

--------------------------------

### Configure Multiple Instances via Environment Variables

Source: https://nowaikit.com/docs/multi-instance

Define multiple instances using the SN_INSTANCE_<NAME>_* prefix pattern in your .env file.

```text
# Dev instance
SN_INSTANCE_DEV_URL=https://yourcompany-dev.service-now.com
SN_INSTANCE_DEV_AUTH=basic
SN_INSTANCE_DEV_USERNAME=admin
SN_INSTANCE_DEV_PASSWORD=dev_password

# Staging instance
SN_INSTANCE_STAGING_URL=https://yourcompany-stg.service-now.com
SN_INSTANCE_STAGING_AUTH=oauth
SN_INSTANCE_STAGING_CLIENT_ID=your_client_id
SN_INSTANCE_STAGING_CLIENT_SECRET=your_secret
SN_INSTANCE_STAGING_USERNAME=svc_account
SN_INSTANCE_STAGING_PASSWORD=svc_password

# Production instance
SN_INSTANCE_PROD_URL=https://yourcompany.service-now.com
SN_INSTANCE_PROD_AUTH=oauth
SN_INSTANCE_PROD_CLIENT_ID=prod_client_id
SN_INSTANCE_PROD_CLIENT_SECRET=prod_secret
SN_INSTANCE_PROD_USERNAME=svc_prod
SN_INSTANCE_PROD_PASSWORD=prod_password

# Set default active instance
SN_DEFAULT_INSTANCE=dev
```

--------------------------------

### Configure .env file

Source: https://nowaikit.com/docs/oauth-setup

Add your ServiceNow instance URL and OAuth credentials to the .env file.

```text
# ServiceNow Instance
SERVICENOW_INSTANCE_URL=https://dev12345.service-now.com

# OAuth Authentication
SERVICENOW_AUTH_METHOD=oauth
SERVICENOW_CLIENT_ID=a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6
SERVICENOW_CLIENT_SECRET=z9y8x7w6v5u4t3s2r1q0p9o8n7m6l5k4
SERVICENOW_USERNAME=your_username
SERVICENOW_PASSWORD=your_password

# Security Settings
WRITE_ENABLED=false
SCRIPTING_ENABLED=false
```

--------------------------------

### GET /api/now/ai_search/search

Source: https://nowaikit.com/docs/now-assist

Performs semantic search.

```APIDOC
## GET /api/now/ai_search/search

### Description
Performs semantic search.

### Method
GET

### Endpoint
/api/now/ai_search/search
```

--------------------------------

### GET /api/now/reporting

Source: https://nowaikit.com/docs/reporting

Searches for saved reports.

```APIDOC
## GET /api/now/reporting

### Description
Searches for saved reports.

### Method
GET

### Endpoint
/api/now/reporting
```

--------------------------------

### cmdb_health_dashboard

Source: https://nowaikit.com/docs/tools-reference

Get CMDB health metrics overview.

```APIDOC
## cmdb_health_dashboard

### Description
Get CMDB health metrics overview.
```

--------------------------------

### get_cmdb_ci

Source: https://nowaikit.com/docs/tools-reference

Get full CI details by sys_id.

```APIDOC
## get_cmdb_ci

### Description
Get full CI details by sys_id.
```

--------------------------------

### get_table_schema

Source: https://nowaikit.com/docs/tools-reference

Get table structure and field metadata.

```APIDOC
## get_table_schema

### Description
Get table structure and field metadata.
```

--------------------------------

### List Configured Instances

Source: https://nowaikit.com/docs/multi-instance

Use the list_instances tool to view all configured instances and identify the active one.

```json
You: "Which instances are configured?"
AI uses: list_instances
# { "current": "dev", "instances": [
#     { "name": "dev", "url": "https://yourcompany-dev.service-now.com", "active": true },
#     { "name": "prod", "url": "https://yourcompany.service-now.com", "active": false }
#   ]}
```

--------------------------------

### GET /api/health

Source: https://nowaikit.com/docs/installation

Retrieve health status and instance information.

```APIDOC
## GET /api/health

### Description
Retrieve health status and instance information.

### Method
GET

### Endpoint
/api/health
```

--------------------------------

### Connect to ServiceNow Instance

Source: https://nowaikit.com/docs/connected-services

Run this command in the VS Code Command Palette to initiate the connection to a ServiceNow instance.

```text
NowAIKit: Connect to Instance
```

--------------------------------

### GET /api/now/table/sys_report

Source: https://nowaikit.com/docs/reporting

Retrieves report definitions from the sys_report table.

```APIDOC
## GET /api/now/table/sys_report

### Description
Retrieves report definitions.

### Method
GET

### Endpoint
/api/now/table/sys_report
```

--------------------------------

### Configure standalone binary on macOS/Linux

Source: https://nowaikit.com/docs/installation

Commands to make the downloaded binary executable and move it to the system PATH.

```bash
# Make executable and move to PATH
$ chmod +x nowaikit-macos-arm64
$ sudo mv nowaikit-macos-arm64 /usr/local/bin/nowaikit
$ nowaikit setup
```

--------------------------------

### GET /api/now/table/sys_atf_result

Source: https://nowaikit.com/docs/atf-testing

Retrieves results from ATF test runs.

```APIDOC
## GET /api/now/table/sys_atf_result

### Description
Retrieves the results of ATF test executions.

### Method
GET

### Endpoint
/api/now/table/sys_atf_result
```

--------------------------------

### Configure Multi-Instance Environment Variables

Source: https://nowaikit.com/docs

Define primary and secondary ServiceNow instances using numbered environment variables in your .env file.

```text
# Primary instance (default)
SN_INSTANCE_URL=https://prod.service-now.com
SN_USERNAME=svc-account
SN_PASSWORD=prod-password

# Secondary instance
SN_INSTANCE_2_URL=https://dev12345.service-now.com
SN_INSTANCE_2_USERNAME=svc-account
SN_INSTANCE_2_PASSWORD=dev-password
SN_INSTANCE_2_NAME=Development
```

--------------------------------

### Initialize NowAIKit and perform API operations

Source: https://nowaikit.com/docs/sdk-quickstart

Demonstrates client initialization and basic usage for querying incidents and creating change requests.

```typescript
import { NowAIKit } from 'nowaikit-sdk';

const kit = new NowAIKit({
  instance: 'your-instance.service-now.com',
  auth: { type: 'basic', username: 'admin', password: 'password' }
});

// Query incidents
const incidents = await kit.incident.query({
  active: true,
  priority: 1,
  limit: 10
});

// Create a change request
const change = await kit.change.create({
  short_description: 'Deploy v2.1 to production',
  type: 'normal',
  risk: 'moderate'
});

console.log(`Found ${incidents.length} P1 incidents`);
console.log(`Created change: ${change.number}`);
```

--------------------------------

### GET /.well-known/agent.json

Source: https://nowaikit.com/docs/installation

Retrieves the agent card containing discovery metadata.

```APIDOC
## GET /.well-known/agent.json

### Description
Agent card (discovery metadata).

### Method
GET

### Endpoint
/.well-known/agent.json
```

--------------------------------

### GET /api/now/table/sys_atf_test_suite

Source: https://nowaikit.com/docs/atf-testing

Retrieves a list of available ATF test suites.

```APIDOC
## GET /api/now/table/sys_atf_test_suite

### Description
Lists all available ATF test suites.

### Method
GET

### Endpoint
/api/now/table/sys_atf_test_suite
```

--------------------------------

### GET /health

Source: https://nowaikit.com/docs/installation

Health check endpoint for SSE and HTTP transports (unauthenticated).

```APIDOC
## GET /health

### Description
Health check endpoint for SSE and HTTP transports (unauthenticated).

### Method
GET

### Endpoint
/health
```

--------------------------------

### fluent_explain

Source: https://nowaikit.com/docs/sdk-fluent

Retrieves documentation for any Fluent SDK concept, type, or pattern.

```APIDOC
## fluent_explain

### Description
Retrieves documentation for any Fluent SDK concept, type, or pattern. Useful for interactive AI assistance.

### Request Body
- **topic** (string) - Required - The concept or pattern to explain

### Request Example
{
  "topic": "FluentComponent lifecycle hooks"
}
```

--------------------------------

### GET /api/now/pa/widget/{sys_id}

Source: https://nowaikit.com/docs/reporting

Retrieves performance analytics data for a specific widget.

```APIDOC
## GET /api/now/pa/widget/{sys_id}

### Description
Retrieves performance analytics data for a specified widget.

### Method
GET

### Endpoint
/api/now/pa/widget/{sys_id}

### Parameters
#### Path Parameters
- **sys_id** (string) - Required - The unique identifier of the PA widget.
```

--------------------------------

### Manage instances and authentication

Source: https://nowaikit.com/docs/installation

Additional CLI commands for managing multiple ServiceNow instances and user authentication.

```bash
$ nowaikit setup --add         # Add a second instance
$ nowaikit instances list      # List configured instances
$ nowaikit instances remove dev # Remove an instance
$ nowaikit auth login          # Per-user OAuth login
$ nowaikit auth whoami         # Show active ServiceNow user
```

--------------------------------

### Run Google Gemini Client

Source: https://nowaikit.com/docs/client-setup

Execute the Gemini client script.

```bash
$ python servicenow_gemini_client.py
```

--------------------------------

### GET /api/now/pa/widget/{sys_id}

Source: https://nowaikit.com/docs/reporting

Retrieves Performance Analytics scorecard data for a specific widget.

```APIDOC
## GET /api/now/pa/widget/{sys_id}

### Description
Retrieves PA scorecard data for a specific widget.

### Method
GET

### Endpoint
/api/now/pa/widget/{sys_id}

### Parameters
#### Path Parameters
- **sys_id** (string) - Required - The unique identifier of the widget.
```

--------------------------------

### Retrieve documentation with fluent_explain

Source: https://nowaikit.com/docs/sdk-fluent

Queries documentation for specific Fluent SDK concepts or patterns.

```json
{
  "topic": "FluentComponent lifecycle hooks"
}
```

--------------------------------

### Configure Environment Variable

Source: https://nowaikit.com/docs/now-assist

Set the environment variable to enable Now Assist features.

```text
NOW_ASSIST_ENABLED=true
```

--------------------------------

### Configure Claude Desktop for NowAIKit

Source: https://nowaikit.com/docs

Add the NowAIKit MCP server to the Claude Desktop configuration file. Ensure the file is saved and Claude Desktop is restarted after modification.

```json
{
  "mcpServers": {
    "nowaikit": {
      "command": "npx",
      "args": ["-y", "nowaikit"],
      "env": {
        "SN_INSTANCE_URL": "https://your-instance.service-now.com",
        "SN_USERNAME":     "your-username",
        "SN_PASSWORD":     "your-password"
      }
    }
  }
}
```

```json
{
  "mcpServers": {
    "nowaikit": {
      "command": "npx",
      "args": [
        "-y", "nowaikit",
        "--allow-write",
        "--allow-cmdb"
      ],
      "env": {
        "SN_INSTANCE_URL": "https://your-instance.service-now.com",
        "SN_USERNAME":     "your-username",
        "SN_PASSWORD":     "your-password"
      }
    }
  }
}
```

--------------------------------

### GET /api/now/ai_search/search

Source: https://nowaikit.com/docs/now-assist

Performs semantic search across knowledge base, catalog, incidents, and other sources.

```APIDOC
## GET /api/now/ai_search/search

### Description
Performs semantic search across knowledge base, catalog, incidents, and other sources.

### Method
GET

### Endpoint
/api/now/ai_search/search
```

--------------------------------

### Configure Basic Authentication

Source: https://nowaikit.com/docs

Use a dedicated service account for Basic Authentication by setting these variables in your .env file.

```text
SN_INSTANCE_URL=https://your-instance.service-now.com
SN_USERNAME=your-service-account
SN_PASSWORD=your-password
```

--------------------------------

### Initialize NowAIKit Client

Source: https://nowaikit.com/docs/sdk-api-reference

Configure the client instance with authentication credentials, connection settings, and request behavior.

```TypeScript
import { NowAIKit } from 'nowaikit-sdk';

const kit = new NowAIKit({
  instance: 'your-instance.service-now.com',
  auth: {
    type: 'oauth',
    clientId: process.env.SN_CLIENT_ID,
    clientSecret: process.env.SN_CLIENT_SECRET,
    username: process.env.SN_USERNAME,
    password: process.env.SN_PASSWORD
  },
  timeout: 30000,
  retries: 3,
  proxy: 'http://proxy.corp.com:8080',
  debug: false
});
```

--------------------------------

### Troubleshooting Commands

Source: https://nowaikit.com/docs/client-setup

Common CLI commands used to verify environment and build status.

```bash
npm run build
```

```bash
node --version
```

--------------------------------

### kit.{module}.create(data)

Source: https://nowaikit.com/docs/sdk-api-reference

Create a new record.

```APIDOC
## kit.{module}.create(data)

### Description
Create a new record. Returns the created record with its sys_id and auto-generated fields.

### Parameters
- **data** (object) - Required - The record fields to create

### Response
- **Returns** (IncidentRecord) - The created record
```

--------------------------------

### Execute Batch GET Operations in TypeScript

Source: https://nowaikit.com/docs/sdk-api-reference

Fetches data from multiple tables simultaneously to reduce network round-trips.

```TypeScript
// Fetch data from 3 tables in one HTTP call
const results = await kit.batch([
  { id: 'incidents', method: 'GET', table: 'incident', query: { active: true, priority: 1 }, limit: 10 },
  { id: 'changes', method: 'GET', table: 'change_request', query: { state: 2 }, limit: 10 },
  { id: 'problems', method: 'GET', table: 'problem', query: { active: true }, limit: 10 }
]);

console.log(results.incidents);  // IncidentRecord[]
console.log(results.changes);    // ChangeRecord[]
console.log(results.problems);   // ProblemRecord[]
```

--------------------------------

### Configure VS Code Settings

Source: https://nowaikit.com/docs/connected-services

Settings for managing the WebSocket bridge port and automatic startup behavior in VS Code.

```json
"nowaikit-builder.syncPort": 8765
```

```json
"nowaikit-builder.syncAutoStart": true
```

--------------------------------

### Fetch breached SLAs with batch_request

Source: https://nowaikit.com/docs/sdk-fluent

Execute parallel GET requests to retrieve breached incidents and change requests.

```json
# Fetch breached SLAs for incidents and changes in parallel
{
  "operations": [
    {
      "id": "breached_incidents",
      "method": "GET",
      "url": "/api/now/table/task_sla?sysparm_query=has_breached=true^task.sys_class_name=incident^task.active=true&sysparm_fields=task.number,task.short_description,sla.name,business_percentage&sysparm_limit=50"
    },
    {
      "id": "breached_changes",
      "method": "GET",
      "url": "/api/now/table/task_sla?sysparm_query=has_breached=true^task.sys_class_name=change_request^task.active=true&sysparm_fields=task.number,task.short_description,sla.name,business_percentage&sysparm_limit=50"
    }
  ]
}
```

--------------------------------

### Define ServiceNow instances in JSON

Source: https://nowaikit.com/docs/multi-instance

Create an instances.json file to store connection details for multiple environments, including basic and OAuth authentication methods.

```json
{
  "default_instance": "dev",
  "instances": {
    "dev": {
      "instance_url": "https://yourcompany-dev.service-now.com",
      "auth_method": "basic",
      "username": "admin",
      "password": "your_dev_password"
    },
    "staging": {
      "instance_url": "https://yourcompany-stg.service-now.com",
      "auth_method": "oauth",
      "client_id": "your_client_id",
      "client_secret": "your_client_secret",
      "username": "svc_account",
      "password": "svc_password"
    },
    "prod": {
      "instance_url": "https://yourcompany.service-now.com",
      "auth_method": "oauth",
      "client_id": "your_client_id",
      "client_secret": "your_client_secret",
      "username": "svc_prod",
      "password": "svc_password"
    },
    "customer_a": {
      "instance_url": "https://customera.service-now.com",
      "auth_method": "basic",
      "username": "admin",
      "password": "password"
    }
  }
}
```

--------------------------------

### GET /api/now/table/sys_atf_failure_insight

Source: https://nowaikit.com/docs/atf-testing

Retrieves failure analysis metadata comparing the last successful run to the current failed run.

```APIDOC
## GET /api/now/table/sys_atf_failure_insight

### Description
Provides insights into why an ATF test failed by comparing metadata against the last successful run.

### Method
GET

### Endpoint
/api/now/table/sys_atf_failure_insight

### Response
#### Response Example
{
  "changes_since_last_pass": [
    {
      "type": "role_change",
      "user": "atf_test_user",
      "removed_role": "itil",
      "changed_at": "2025-03-15T10:23:00Z"
    },
    {
      "type": "field_change",
      "table": "sys_properties",
      "field": "glide.authenticate.multifactor",
      "old_value": "false",
      "new_value": "true"
    }
  ]
}
```

--------------------------------

### Register NowAIKit in Cursor

Source: https://nowaikit.com/docs/client-setup

Configure the MCP server settings in the .cursor/mcp.json file.

```json
{
  "mcpServers": {
    "servicenow": {
      "command": "node",
      "args": ["/absolute/path/to/nowaikit/dist/server.js"],
      "env": {
        "SERVICENOW_INSTANCE_URL":   "https://yourinstance.service-now.com",
        "SERVICENOW_AUTH_METHOD":     "basic",
        "SERVICENOW_BASIC_USERNAME": "your_username",
        "SERVICENOW_BASIC_PASSWORD": "your_password",
        "WRITE_ENABLED":             "false"
      }
    }
  }
}
```

--------------------------------

### Use SSE transport with curl

Source: https://nowaikit.com/docs/installation

Starts an SSE server and interacts with it using long-lived connections and JSON-RPC messages.

```bash
# Start SSE server
$ TRANSPORT=sse PORT=3000 npx nowaikit

# Connect to SSE stream (long-lived connection)
$ curl -N http://localhost:3000/sse

# Send an MCP message
$ curl -X POST http://localhost:3000/messages \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'
```

--------------------------------

### Execute mixed read and write operations

Source: https://nowaikit.com/docs/sdk-fluent

Combines GET requests for dashboard data with a POST request to update user preferences.

```json
{
  "operations": [
    {
      "id": "my_tasks",
      "method": "GET",
      "url": "/api/now/table/task?sysparm_query=assigned_to=javascript:gs.getUserID()^active=true&..."
    },
    {
      "id": "team_workload",
      "method": "GET",
      "url": "/api/now/stats/incident?sysparm_query=active=true&sysparm_count=true&sysparm_group_by=assignment_group"
    },
    {
      "id": "update_preference",
      "method": "POST",
      "url": "/api/now/table/sys_user_preference",
      "body": { "name": "dashboard.last_refresh", "value": "2025-12-01 09:00:00" }
    }
  ]
}
```

--------------------------------

### Multi-Customer instances.json Configuration

Source: https://nowaikit.com/docs/multi-instance

Defines the structure for the instances.json file used to manage multiple customer ServiceNow tenants.

```json
{
  "default_instance": "internal",
  "instances": {
    "internal": { "instance_url": "https://mycompany.service-now.com", ... },
    "client_acme": { "instance_url": "https://acme.service-now.com", ... },
    "client_globex": { "instance_url": "https://globex.service-now.com", ... }
  }
}
```

--------------------------------

### GET /api/now/stats/{table}

Source: https://nowaikit.com/docs/reporting

Retrieves aggregate statistics for a specified table, supporting operations like GROUP BY, SUM, COUNT, and AVG.

```APIDOC
## GET /api/now/stats/{table}

### Description
Retrieves aggregate statistics for a specified table.

### Method
GET

### Endpoint
/api/now/stats/{table}

### Parameters
#### Path Parameters
- **table** (string) - Required - The name of the table to aggregate.
```

--------------------------------

### Create and Schedule a Script Job

Source: https://nowaikit.com/docs/reporting

Workflow for creating, verifying, testing, and monitoring a daily scheduled script job.

```bash
# 1. Create a new daily script job
create_scheduled_job
  name="Nightly Cleanup"
  script="gs.info('running');"
  run_type="daily"
  run_time="02:00:00"

# 2. Verify the job was created
get_scheduled_job sys_id="<sys_id>"

# 3. Trigger immediately to test
trigger_scheduled_job sys_id="<sys_id>"

# 4. Check execution history
list_job_run_history job_sys_id="<sys_id>"
```

--------------------------------

### fluent_build

Source: https://nowaikit.com/docs/sdk-fluent

Compiles the Fluent project into deployable artifacts.

```APIDOC
## fluent_build

### Description
Compiles the Fluent project into deployable artifacts. Supports minification, source maps, and output directory configuration.

### Request Body
- **projectDir** (string) - Required - The directory of the project to build
- **outDir** (string) - Optional - The output directory for artifacts
- **minify** (boolean) - Optional - Whether to minify the output
- **sourceMaps** (boolean) - Optional - Whether to generate source maps

### Request Example
{
  "projectDir": "./my-fluent-app",
  "outDir": "./dist",
  "minify": true,
  "sourceMaps": true
}
```

--------------------------------

### Configure Basic Authentication

Source: https://nowaikit.com/docs/oauth-setup

Use these environment variables to enable Basic Authentication if OAuth is unavailable.

```text
SERVICENOW_AUTH_METHOD=basic
SERVICENOW_BASIC_USERNAME=your_username
SERVICENOW_BASIC_PASSWORD=your_password
```

--------------------------------

### Configure Basic Authentication for Claude Desktop

Source: https://nowaikit.com/docs/client-setup

Use this configuration block to connect to ServiceNow using basic credentials. Ensure the command path points to the absolute location of the server.js file.

```json
{
  "mcpServers": {
    "servicenow": {
      "command": "node",
      "args": ["/absolute/path/to/nowaikit/dist/server.js"],
      "env": {
        "SERVICENOW_INSTANCE_URL": "https://yourinstance.service-now.com",
        "SERVICENOW_AUTH_METHOD":  "basic",
        "SERVICENOW_BASIC_USERNAME": "your_username",
        "SERVICENOW_BASIC_PASSWORD": "your_password",
        "WRITE_ENABLED":           "false",
        "MCP_TOOL_PACKAGE":        "service_desk"
      }
    }
  }
}
```

--------------------------------

### Per-Call Instance Override

Source: https://nowaikit.com/docs/multi-instance

Demonstrates how to specify an instance directly within a tool call to target different environments without changing global settings.

```json
AI uses: get_incident {
  "number_or_sysid": "INC0001234",
  "instance": "prod"
}

AI uses: query_records {
  "table": "incident",
  "query": "priority=1^state!=6",
  "instance": "staging"
}
```

--------------------------------

### NowAIKit Constructor

Source: https://nowaikit.com/docs/sdk-api-reference

The NowAIKit constructor initializes the SDK client with instance details, authentication credentials, and request configuration.

```APIDOC
## NowAIKit Constructor

### Description
Initializes a new instance of the NowAIKit SDK to interact with a ServiceNow instance.

### Signature
`new NowAIKit(options: ClientOptions)`

### Parameters
- **instance** (string) - Required - ServiceNow instance hostname.
- **auth** (AuthConfig) - Required - Authentication configuration.
- **timeout** (number) - Optional - Request timeout in milliseconds (default: 30000).
- **retries** (number) - Optional - Number of automatic retries on transient failures (default: 3).
- **retryDelay** (number) - Optional - Base delay between retries in ms.
- **proxy** (string) - Optional - HTTP proxy URL.
- **debug** (boolean) - Optional - Enable verbose logging (default: false).
- **apiVersion** (string) - Optional - ServiceNow REST API version namespace (default: 'now').
- **maxConcurrent** (number) - Optional - Maximum concurrent HTTP requests (default: 10).

### Example
```typescript
import { NowAIKit } from 'nowaikit-sdk';

const kit = new NowAIKit({
  instance: 'your-instance.service-now.com',
  auth: {
    type: 'oauth',
    clientId: process.env.SN_CLIENT_ID,
    clientSecret: process.env.SN_CLIENT_SECRET,
    username: process.env.SN_USERNAME,
    password: process.env.SN_PASSWORD
  },
  timeout: 30000,
  retries: 3,
  proxy: 'http://proxy.corp.com:8080',
  debug: false
});
```
```

--------------------------------

### ATF Failure Insight JSON Output

Source: https://nowaikit.com/docs/atf-testing

Example JSON structure returned by the failure insight tool showing metadata changes.

```json
{
  "changes_since_last_pass": [
    {
      "type": "role_change",
      "user": "atf_test_user",
      "removed_role": "itil",
      "changed_at": "2025-03-15T10:23:00Z"
    },
    {
      "type": "field_change",
      "table": "sys_properties",
      "field": "glide.authenticate.multifactor",
      "old_value": "false",
      "new_value": "true"
    }
  ]
}
```

--------------------------------

### Initialize and use A2AClient

Source: https://nowaikit.com/docs/sdk-api-reference

Use this client to communicate with remote agents, discover capabilities, and manage tasks via SSE streaming.

```typescript
import { A2AClient } from 'nowaikit-sdk/a2a';

const a2a = new A2AClient(url: string, options?: A2AClientOptions);

// Discover the agent's capabilities
const agentCard = await a2a.discoverAgent();

// Send a task and get the result
const result = await a2a.sendTask(params: TaskSendParams);

// Send a task with SSE streaming
const stream = a2a.sendTaskStreaming(params: TaskSendParams);
for await (const event of stream) {
  console.log(event);
}

// Cancel a running task
await a2a.cancelTask(taskId: string);

// Get task status
const status = await a2a.getTask(taskId: string);
```

--------------------------------

### Create a Now Assist skill

Source: https://nowaikit.com/docs/now-assist

Defines a new AI skill on the instance. Requires NOW_ASSIST_ENABLED and WRITE_ENABLED to be true.

```yaml
create_now_assist_skill:
  name="Summarize Change Risk",
  description="Analyzes a change request and produces a risk summary",
  skill_type="generative"
```

--------------------------------

### Run OpenAI Codex Client

Source: https://nowaikit.com/docs/client-setup

Execute the OpenAI client script after configuring the .env file.

```bash
$ python servicenow_openai_client.py
```

--------------------------------

### Configure instance path via environment variable

Source: https://nowaikit.com/docs/multi-instance

Set the SN_INSTANCES_CONFIG environment variable to point to your configuration file path.

```bash
SN_INSTANCES_CONFIG=/path/to/instances.json
```