npm package: @sonisoft/now-sdk-ext-cli
Description: A CLI extending the functionality of the ServiceNow SDK.
Author: Chris Nanda
Latest version: 2.3.2

# @sonisoft/now-sdk-ext-cli

[![npm version](https://img.shields.io/npm/v/@sonisoft/now-sdk-ext-cli.svg)](https://www.npmjs.com/package/@sonisoft/now-sdk-ext-cli)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

> A powerful CLI toolkit that extends the ServiceNow SDK with advanced automation capabilities for development, testing, and operations.

## 🚀 Overview

`now-sdk-ext-cli` (command: `nex`) is a comprehensive command-line interface that enhances the official ServiceNow SDK with powerful features for developers and administrators. It provides seamless integration with ServiceNow instances to automate common tasks, execute tests, manage applications, and run scripts remotely.

### Why Use `nex`?

- **💪 Powerful Automation**: Automate ServiceNow operations that would otherwise require manual UI interaction
- **⚡ Fast Development**: Interactive REPL mode for rapid script development and testing
- **🔧 DevOps Ready**: Built for CI/CD with JSON output, exit codes, and scriptable operations
- **🎯 Developer Friendly**: Intuitive commands, autocomplete, and extensive documentation
- **🔒 Secure**: Uses ServiceNow SDK's secure keychain storage for credentials

### Key Features

#### 🧪 ATF Test Automation
Execute individual ATF tests or entire test suites with detailed results, perfect for CI/CD pipelines.

#### 📦 Application Lifecycle Management
- **Install** applications from batch definitions
- **Uninstall** applications programmatically
- **Repository Management**: List and install apps from your company repository
- Automated deployment workflows

#### ⚡ Script Execution (Enhanced)
- **File Mode**: Execute JavaScript files on ServiceNow instances
- **REPL Mode**: Interactive script executor (like node REPL, but for ServiceNow!)
- **Parameterization**: Template scripts with `{placeholder}` replacement
- **Scope-Aware**: Execute in global or custom application scopes

#### 🔍 Query & Search
- **Table Queries**: Query any ServiceNow table with encoded queries, field selection, and display values
- **Application Search**: Find applications by name across your instance
- **Column Discovery**: List and search table columns/fields
- **Syslog Reader**: Query system logs with filtering
- **Code Search**: Search scripts across the platform

#### 📊 Aggregate & Analytics
- **Record Counts**: Count records with optional filters
- **Aggregate Statistics**: Run AVG, MIN, MAX, SUM across table fields
- **Grouped Aggregation**: Group-by queries with multiple fields and HAVING clauses

#### 🏥 Instance Health & Diagnostics
- **Health Check**: Consolidated instance diagnostics — version info, cluster status, stuck jobs, semaphore counts, operational record counts
- **Color-coded** status indicators for quick visual assessment
- **JSON output** for CI/CD monitoring and alerting

#### 🔀 Flow Designer Operations
- **Execute Flows**: Run flows, subflows, and actions in foreground or background mode
- **Monitor Status**: Check flow context status, retrieve outputs, and inspect errors
- **Flow Control**: Cancel running flows and send messages to waiting flows
- **JSON inputs/outputs**: Pass structured inputs and capture flow outputs programmatically

#### 🗑️ Bulk Record Operations
- **Bulk Update**: Update all records matching an encoded query with dry-run safety
- **Bulk Delete**: Delete records matching a query with confirmation and limits
- **Dry-run by default**: Preview affected records before committing changes
- **Progress callbacks**: Real-time progress updates during bulk operations

#### 🎨 Advanced Features
- **Dynamic Autocomplete**: Tab completion that queries your ServiceNow instance for scopes
- **Batch Operations**: Install multiple applications from JSON definitions or batch create/update records
- **Progress Monitoring**: Real-time progress for long-running operations
- **Schema Discovery**: Inspect table schemas and field definitions
- **Script Sync**: Pull and push scripts between local files and ServiceNow
- **Task Management**: Comment, assign, resolve, and close incidents and changes
- **Update Sets**: Create, inspect, clone, and manage update sets
- **Workflow Creation**: Create workflows with activities, transitions, and conditions
- **Scope Management**: Switch application scopes programmatically
- **Store Integration**: Search, install, and update apps from the ServiceNow Store
- **JSON Output**: Perfect for parsing and automation

#### 🔄 CI/CD Integration
- Proper exit codes (0 = success, 1 = failure)
- JSON output mode for all commands
- Environment variable support
- Scriptable and automatable

## 📋 Table of Contents

- [Installation](#-installation)
- [Prerequisites](#-prerequisites)
- [Quick Start](#-quick-start)
- [Core Capabilities](#-core-capabilities)
  - [ATF Testing](#atf-testing)
  - [Application Management](#application-management)
  - [Script Execution with REPL](#script-execution-with-repl)
  - [Company Repository](#company-repository-integration)
  - [Query & Search](#query--search)
  - [Aggregate & Analytics](#aggregate--analytics)
  - [Instance Health Check](#instance-health-check)
  - [Flow Designer](#flow-designer-operations)
  - [Bulk Operations](#bulk-record-operations)
- [All Commands](#-commands)
- [Authentication](#-authentication)
- [Advanced Features](#-advanced-features)
  - [Interactive REPL](#interactive-repl-mode)
  - [Script Parameterization](#script-parameterization)
  - [Shell Autocomplete](#shell-autocomplete)
- [CI/CD Integration](#-cicd-integration)
- [Examples](#-examples)
- [Troubleshooting](#-troubleshooting)
- [Documentation](#-documentation)
- [Support & Contributing](#-support--contributing)

## ⚠️ Breaking Change — v2.0.0 (ServiceNow SDK 4.3.0)

> **If you are upgrading from v1.x, read this first.**
>
> This version upgrades the underlying ServiceNow SDK dependencies from **4.2.x to 4.3.0** and the core library to **@sonisoft/now-sdk-ext-core 3.4.0**. ServiceNow 4.3.0 **changed how credential aliases are stored**, replacing the previous `keytar`-based credential store with a new implementation.
>
> **What this means for you:**
> - Credential aliases created with ServiceNow SDK 4.2.x **cannot be read** by SDK 4.3.x
> - You **must re-create all instance aliases** after upgrading
>
> **Migration steps:**
> ```bash
> # 1. Update the global CLI
> npm install -g @servicenow/sdk@4.3.0
>
> # 2. Re-add each instance alias
> snc configure profile set
> # — or —
> npx @servicenow/sdk auth --add <your-alias>
>
> # 3. Verify your aliases work
> npx @servicenow/sdk auth --list
> ```
>
> All CLI commands and API surfaces remain unchanged — only the underlying authentication storage has changed.

## 💾 Installation

### Global Installation (Recommended)

```bash
npm install -g @sonisoft/now-sdk-ext-cli
```

### Local Installation

```bash
npm install @sonisoft/now-sdk-ext-cli
```

### Verify Installation

```bash
nex --version
nex --help
```

## 📚 Prerequisites

### ServiceNow SDK

**Required**: This CLI extension leverages the official ServiceNow SDK for authentication management. You must install and configure the ServiceNow SDK first.

```bash
npm install -g @servicenow/sdk
```

Verify installation:

```bash
now-sdk --version
```

**Important**: The `now-sdk-ext-cli` does not manage credentials directly. It uses authentication credentials configured via the ServiceNow SDK (`now-sdk auth` command). This provides:
- Secure credential storage in your system's keychain
- Centralized authentication management across ServiceNow tools
- Support for multiple instance profiles
- OAuth and basic authentication methods

### Node.js

- **Minimum Version**: Node.js 18.0.0 or higher
- **Recommended**: Node.js 22.x (LTS) or later

### ServiceNow Instance

- ServiceNow instance with appropriate permissions
- API access enabled
- User account with required roles:
  - `admin` or `atf_test_runner` for ATF operations
  - `admin` or `sn_cicd.sys_ci_automation` for application management
  - Script execution requires appropriate scope access

## 🎯 Quick Start

### 1. Configure Authentication

First, set up your ServiceNow instance credentials using the ServiceNow SDK:

```bash
# Add credentials (interactive - will prompt for username/password)
now-sdk auth --add your-instance.service-now.com --type basic --alias my-dev-instance

# Set as default (optional)
now-sdk auth --use my-dev-instance

# List configured authentication profiles
now-sdk auth --list
```

**Note**: Credentials configured via `now-sdk auth` are automatically available to `nex` commands through the `--auth` flag.

### 2. Run Your First Command

```bash
# Start interactive REPL
nex exec global --auth my-dev-instance

# Execute an ATF test
nex atf --test-id <test-sys-id> --auth my-dev-instance

# List repository applications
nex app:repo-list --auth my-dev-instance

# Install from repository
nex app:repo-install --scope x_my_app --auth my-dev-instance
```

---

## 🎯 Core Capabilities

### ATF Testing

Execute Automated Test Framework tests and suites directly from the command line.

```bash
# Execute a single test
nex atf --test-id f717a8c783103210621e78c6feaad396 --auth dev

# Execute a test suite by ID
nex atf --suite-id e077e00b83103210621e78c6feaad383 --auth dev --wait

# Execute by name with JSON output (perfect for CI/CD)
nex atf --suite-name "Smoke Tests" --auth dev --json > results.json

# Configure browser and performance settings
nex atf --suite-id abc123 --browser chrome --performance --auth dev
```

**Key Features:**
- Execute individual tests or complete suites
- Wait for completion or run async
- JSON output for CI/CD integration
- Browser/OS configuration
- Performance testing mode
- Real-time progress monitoring

### Application Management

Comprehensive application lifecycle management tools.

```bash
# Install applications from batch definition
nex app:install --batch --definitionPath ./apps.json --auth dev

# Uninstall an application
nex app:uninstall -i <sys_id> -s x_my_app --auth dev

# List repository applications (what's available to install)
nex app:repo-list --installable --auth dev

# Install from company repository
nex app:repo-install --scope x_my_app --version 2.1.0 --auth dev

# List installed repository apps
nex app:repo-list --installed --json --auth dev
```

**Key Features:**
- Batch installation from JSON definitions
- Repository browsing and installation
- Progress monitoring with configurable timeouts
- Post-installation verification
- JSON output for automation

### Script Execution with REPL

Execute JavaScript on ServiceNow instances - now with three powerful modes!

#### Mode 1: Execute Script Files
```bash
nex exec global ./cleanup.js --auth dev
nex exec x_my_app ./app-config.js --auth dev
```

#### Mode 2: Interactive REPL ⭐ NEW!
```bash
$ nex exec global --auth dev

sn> var gr = new GlideRecord('sys_user');
... gr.addQuery('active', true);
... gr.query();
... gs.info('Active users: ' + gr.getRowCount());
... .exec

*** Script: Active users: 142

sn> .exit
```

**REPL Features:**
- Multi-line script input
- Execute with `.exec` or Ctrl+D
- Clear buffer with `.clear`
- Command history within session
- Beautiful, intuitive interface

#### Mode 3: Parameterized Scripts ⭐ NEW!
```bash
# Script with placeholders: {username}, {table}
nex exec global ./query-user.js \
  --auth dev \
  --params '{"username":"admin","table":"sys_user"}'
```

**Parameterization Features:**
- `{placeholder}` syntax in scripts
- JSON parameter object
- Multiple parameters supported
- All data types (string, number, boolean)
- Perfect for environment-specific scripts

### Company Repository Integration

Discover and install applications from your company's internal repository.

```bash
# See what's available
nex app:repo-list --auth prod

# Filter for installable apps
nex app:repo-list --installable --json --auth prod

# Install by scope (automatic lookup)
nex app:repo-install --scope x_custom_app --auth prod

# Install specific version
nex app:repo-install --scope x_custom_app --version 1.2.0 --auth prod

# Background installation
nex app:repo-install --scope x_custom_app --no-wait --auth prod
```

**Key Features:**
- Browse company repository applications
- Filter by installation status
- Install by scope name (no need to look up sys_id)
- Version control
- Wait for completion or run async
- Post-installation verification

### Query & Search

Query ServiceNow tables, applications, columns, and system logs directly from the CLI.

```bash
# Query any table with encoded queries
nex query --table incident --query "active=true^priority=1" --fields number,short_description --limit 10 --auth dev

# Search applications by name
nex query app --name "ITSM" --auth dev

# List columns for a table
nex query columns --table incident --search "description" --auth dev

# Query system logs
nex query syslog --query "level=error" --limit 50 --auth dev

# Search platform code
nex search code --term "GlideRecord" --auth dev
```

### Aggregate & Analytics

Run aggregate statistics on ServiceNow tables without downloading individual records.

```bash
# Count records
nex aggregate count --table incident --query "active=true" --auth dev

# Run aggregate statistics (AVG, MIN, MAX, SUM)
nex aggregate query --table incident --avg reassignment_count --min reassignment_count --max reassignment_count --auth dev

# Grouped aggregation with display values
nex aggregate group --table incident --group-by priority --count --auth dev --display-value all

# Multiple group-by fields with HAVING clause
nex aggregate group --table incident --group-by priority --group-by state --count --having "COUNT>5" --auth dev
```

### Instance Health Check

Run consolidated health diagnostics on your ServiceNow instance.

```bash
# Full health check
nex health check --auth dev

# Check only version and stuck jobs
nex health check --include-version --include-stuck-jobs --no-include-cluster --no-include-semaphores --no-include-operational-counts --auth dev

# Health check with custom stuck job threshold (60 minutes)
nex health check --stuck-job-threshold 60 --auth dev

# JSON output for monitoring/alerting
nex health check --json --auth dev
```

**Includes:**
- Instance version and build information
- Cluster node status (online/offline)
- Stuck job detection with configurable threshold
- Active semaphore count
- Operational counts (open incidents, changes, problems)
- Color-coded status indicators

### Flow Designer Operations

Execute and manage Flow Designer flows, subflows, and actions from the CLI.

```bash
# Execute a flow in foreground (waits for completion)
nex flow run --name global.my_flow --auth dev

# Execute with inputs
nex flow run --name global.my_flow --inputs '{"priority":"1","category":"network"}' --auth dev

# Execute a subflow
nex flow subflow --name global.my_subflow --inputs '{"record_id":"abc123"}' --auth dev

# Execute an action
nex flow action --name global.my_action --inputs '{"table":"incident"}' --auth dev

# Check flow status
nex flow status --context-id ctx-abc123 --auth dev

# Retrieve flow outputs
nex flow outputs --context-id ctx-abc123 --json --auth dev

# Check for errors
nex flow error --context-id ctx-abc123 --auth dev

# Cancel a running flow
nex flow cancel --context-id ctx-abc123 --reason "No longer needed" --auth dev

# Send a message to a waiting flow (e.g., approval)
nex flow message --context-id ctx-abc123 --message approved --payload '{"approver":"admin"}' --auth dev
```

**Features:**
- Execute flows, subflows, and actions with structured inputs
- Foreground (wait) or background execution modes
- Query flow context status, outputs, and errors
- Cancel running flows and send messages to paused flows
- JSON output for automation and CI/CD

### Bulk Record Operations

Perform bulk updates and deletes on ServiceNow records matching a query.

```bash
# Dry-run: preview which records would be updated (safe default)
nex bulk update --table incident --query "active=true^priority=4" --data '{"priority":"3"}' --auth dev

# Confirm bulk update (actually modifies records)
nex bulk update --table incident --query "active=true^priority=4" --data '{"priority":"3"}' --confirm --auth dev

# Dry-run: preview which records would be deleted
nex bulk delete --table u_temp_records --query "sys_created_on<2024-01-01" --auth dev

# Confirm bulk delete with limit
nex bulk delete --table u_temp_records --query "sys_created_on<2024-01-01" --confirm --limit 500 --auth dev

# JSON output for scripting
nex bulk update --table incident --query "state=7" --data '{"active":"false"}' --confirm --json --auth dev
```

**Safety Features:**
- **Dry-run by default**: Always previews affected records before modifying
- **Explicit confirmation**: Must pass `--confirm` to execute changes
- **Record limits**: Cap the number of affected records with `--limit`
- **Progress updates**: Real-time feedback during bulk operations

## 📖 Commands

<!-- toc -->
* [@sonisoft/now-sdk-ext-cli](#sonisoftnow-sdk-ext-cli)
* [Add credentials (interactive - will prompt for username/password)](#add-credentials-interactive---will-prompt-for-usernamepassword)
* [Set as default (optional)](#set-as-default-optional)
* [List configured authentication profiles](#list-configured-authentication-profiles)
* [Start interactive REPL](#start-interactive-repl)
* [Execute an ATF test](#execute-an-atf-test)
* [List repository applications](#list-repository-applications)
* [Install from repository](#install-from-repository)
* [Execute a single test](#execute-a-single-test)
* [Execute a test suite by ID](#execute-a-test-suite-by-id)
* [Execute by name with JSON output (perfect for CI/CD)](#execute-by-name-with-json-output-perfect-for-cicd)
* [Configure browser and performance settings](#configure-browser-and-performance-settings)
* [Install applications from batch definition](#install-applications-from-batch-definition)
* [Uninstall an application](#uninstall-an-application)
* [List repository applications (what's available to install)](#list-repository-applications-whats-available-to-install)
* [Install from company repository](#install-from-company-repository)
* [List installed repository apps](#list-installed-repository-apps)
* [Script with placeholders: {username}, {table}](#script-with-placeholders-username-table)
* [See what's available](#see-whats-available)
* [Filter for installable apps](#filter-for-installable-apps)
* [Install by scope (automatic lookup)](#install-by-scope-automatic-lookup)
* [Install specific version](#install-specific-version)
* [Background installation](#background-installation)
* [Query any table with encoded queries](#query-any-table-with-encoded-queries)
* [Search applications by name](#search-applications-by-name)
* [List columns for a table](#list-columns-for-a-table)
* [Query system logs](#query-system-logs)
* [Search platform code](#search-platform-code)
* [Count records](#count-records)
* [Run aggregate statistics (AVG, MIN, MAX, SUM)](#run-aggregate-statistics-avg-min-max-sum)
* [Grouped aggregation with display values](#grouped-aggregation-with-display-values)
* [Multiple group-by fields with HAVING clause](#multiple-group-by-fields-with-having-clause)
* [Full health check](#full-health-check)
* [Check only version and stuck jobs](#check-only-version-and-stuck-jobs)
* [Health check with custom stuck job threshold (60 minutes)](#health-check-with-custom-stuck-job-threshold-60-minutes)
* [JSON output for monitoring/alerting](#json-output-for-monitoringalerting)
* [Execute a flow in foreground (waits for completion)](#execute-a-flow-in-foreground-waits-for-completion)
* [Execute with inputs](#execute-with-inputs)
* [Execute a subflow](#execute-a-subflow)
* [Execute an action](#execute-an-action)
* [Check flow status](#check-flow-status)
* [Retrieve flow outputs](#retrieve-flow-outputs)
* [Check for errors](#check-for-errors)
* [Cancel a running flow](#cancel-a-running-flow)
* [Send a message to a waiting flow (e.g., approval)](#send-a-message-to-a-waiting-flow-eg-approval)
* [Dry-run: preview which records would be updated (safe default)](#dry-run-preview-which-records-would-be-updated-safe-default)
* [Confirm bulk update (actually modifies records)](#confirm-bulk-update-actually-modifies-records)
* [Dry-run: preview which records would be deleted](#dry-run-preview-which-records-would-be-deleted)
* [Confirm bulk delete with limit](#confirm-bulk-delete-with-limit)
* [JSON output for scripting](#json-output-for-scripting)
* [Usage](#usage)
* [Commands](#commands)
* [Global scope](#global-scope)
* [Custom application scope](#custom-application-scope)
* [Development](#development)
* [Production](#production)
* [GitHub Actions](#github-actions)
* [1. Enable autocomplete](#1-enable-autocomplete)
* [2. Follow shell-specific instructions (bash/zsh/fish)](#2-follow-shell-specific-instructions-bashzshfish)
* [3. Reload shell](#3-reload-shell)
* [4. Start using it!](#4-start-using-it)
* [Autocomplete queries ServiceNow and shows:](#autocomplete-queries-servicenow-and-shows)
* [Ready to execute!](#ready-to-execute)
* [Add credentials interactively (will prompt for username/password)](#add-credentials-interactively-will-prompt-for-usernamepassword)
* [For OAuth authentication](#for-oauth-authentication)
* [List all configured authentication profiles](#list-all-configured-authentication-profiles)
* [Set default authentication profile (optional)](#set-default-authentication-profile-optional)
* [Delete an authentication profile](#delete-an-authentication-profile)
* [Use specific authentication profile via --auth flag](#use-specific-authentication-profile-via---auth-flag)
* [Use default profile (if set with --use)](#use-default-profile-if-set-with---use)
* [All commands support the --auth flag](#all-commands-support-the---auth-flag)
* [Set credentials in environment](#set-credentials-in-environment)
* [Add authentication profile (will use environment variables)](#add-authentication-profile-will-use-environment-variables)
* [1. List available repository apps](#1-list-available-repository-apps)
* [2. Install application from repository](#2-install-application-from-repository)
* [3. Configure using REPL](#3-configure-using-repl)
* [4. Run tests](#4-run-tests)
* [5. Deploy to production with parameterized script](#5-deploy-to-production-with-parameterized-script)
* [6. Verify deployment](#6-verify-deployment)
* [Execute a single test](#execute-a-single-test)
* [Execute a test suite and wait for results](#execute-a-test-suite-and-wait-for-results)
* [Execute by name (no need to look up sys_id)](#execute-by-name-no-need-to-look-up-sys_id)
* [Performance test with specific browser](#performance-test-with-specific-browser)
* [CI/CD integration with JSON output](#cicd-integration-with-json-output)
* [Custom polling for long tests](#custom-polling-for-long-tests)
* [Browse company repository](#browse-company-repository)
* [Install from repository](#install-from-repository)
* [Batch install multiple apps](#batch-install-multiple-apps)
* [Uninstall application](#uninstall-application)
* [Execute script file](#execute-script-file)
* [Execute in custom scope](#execute-in-custom-scope)
* [Pipe output](#pipe-output)
* [Start REPL](#start-repl)
* [Execute multi-line scripts interactively](#execute-multi-line-scripts-interactively)
* [Single parameter](#single-parameter)
* [Multiple parameters](#multiple-parameters)
* [From environment variables](#from-environment-variables)
* [daily-tests.sh](#daily-testssh)
* [setup-environment.sh](#setup-environmentsh)
* [Install required apps from repository](#install-required-apps-from-repository)
* [Configure via parameterized script](#configure-via-parameterized-script)
* [Validate with ATF](#validate-with-atf)
* [migrate-data.sh](#migrate-datash)
* [Export from source](#export-from-source)
* [Transform data](#transform-data)
* [Import to target with parameters](#import-to-target-with-parameters)
* [Validate](#validate)
* [List all configured authentication profiles](#list-all-configured-authentication-profiles)
* [Delete and re-add credentials if needed](#delete-and-re-add-credentials-if-needed)
* [Set as default](#set-as-default)
* [Verify installation](#verify-installation)
* [Reinstall if needed](#reinstall-if-needed)
* [Check PATH includes npm global binaries](#check-path-includes-npm-global-binaries)
* [Increase poll interval](#increase-poll-interval)
* [Check instance performance](#check-instance-performance)
* [Check test suite complexity](#check-test-suite-complexity)
* [Review ServiceNow logs](#review-servicenow-logs)
* [Verify user has required roles:](#verify-user-has-required-roles)
* [- atf_test_runner for ATF operations](#--atf_test_runner-for-atf-operations)
* [- admin for app management](#--admin-for-app-management)
* [- appropriate scope access for scripts](#--appropriate-scope-access-for-scripts)
* [General help](#general-help)
* [Command-specific help](#command-specific-help)
* [Command-specific help](#command-specific-help)
* [Enable autocomplete](#enable-autocomplete)
* [Clone the repository](#clone-the-repository)
* [Install dependencies](#install-dependencies)
* [Build](#build)
* [Run tests (960+ tests)](#run-tests-960-tests)
* [Run linter](#run-linter)
* [Test locally](#test-locally)
* [All tests](#all-tests)
* [Specific test file](#specific-test-file)
* [With coverage](#with-coverage)
<!-- tocstop -->

# Usage
<!-- usage -->
```sh-session
$ npm install -g @sonisoft/now-sdk-ext-cli
$ nex COMMAND
running command...
$ nex (--version)
@sonisoft/now-sdk-ext-cli/2.3.2 linux-x64 node-v22.16.0
$ nex --help [COMMAND]
USAGE
  $ nex COMMAND
...
```
<!-- usagestop -->

# Commands
<!-- commands -->
* [`nex aggregate count`](#nex-aggregate-count)
* [`nex aggregate group`](#nex-aggregate-group)
* [`nex aggregate query`](#nex-aggregate-query)
* [`nex app`](#nex-app)
* [`nex app install`](#nex-app-install)
* [`nex app repo-install`](#nex-app-repo-install)
* [`nex app repo-list`](#nex-app-repo-list)
* [`nex app uninstall`](#nex-app-uninstall)
* [`nex atf`](#nex-atf)
* [`nex attachment get`](#nex-attachment-get)
* [`nex attachment list`](#nex-attachment-list)
* [`nex attachment upload`](#nex-attachment-upload)
* [`nex autocomplete [SHELL]`](#nex-autocomplete-shell)
* [`nex batch create`](#nex-batch-create)
* [`nex batch update`](#nex-batch-update)
* [`nex bulk delete`](#nex-bulk-delete)
* [`nex bulk update`](#nex-bulk-update)
* [`nex exec SCOPE [FILE]`](#nex-exec-scope-file)
* [`nex flow action`](#nex-flow-action)
* [`nex flow cancel`](#nex-flow-cancel)
* [`nex flow copy`](#nex-flow-copy)
* [`nex flow details`](#nex-flow-details)
* [`nex flow error`](#nex-flow-error)
* [`nex flow logs`](#nex-flow-logs)
* [`nex flow message`](#nex-flow-message)
* [`nex flow outputs`](#nex-flow-outputs)
* [`nex flow run`](#nex-flow-run)
* [`nex flow status`](#nex-flow-status)
* [`nex flow subflow`](#nex-flow-subflow)
* [`nex flow test`](#nex-flow-test)
* [`nex health check`](#nex-health-check)
* [`nex help [COMMAND]`](#nex-help-command)
* [`nex log`](#nex-log)
* [`nex plugins`](#nex-plugins)
* [`nex plugins add PLUGIN`](#nex-plugins-add-plugin)
* [`nex plugins:inspect PLUGIN...`](#nex-pluginsinspect-plugin)
* [`nex plugins install PLUGIN`](#nex-plugins-install-plugin)
* [`nex plugins link PATH`](#nex-plugins-link-path)
* [`nex plugins remove [PLUGIN]`](#nex-plugins-remove-plugin)
* [`nex plugins reset`](#nex-plugins-reset)
* [`nex plugins uninstall [PLUGIN]`](#nex-plugins-uninstall-plugin)
* [`nex plugins unlink [PLUGIN]`](#nex-plugins-unlink-plugin)
* [`nex plugins update`](#nex-plugins-update)
* [`nex query`](#nex-query)
* [`nex query app`](#nex-query-app)
* [`nex query columns`](#nex-query-columns)
* [`nex query syslog`](#nex-query-syslog)
* [`nex schema`](#nex-schema)
* [`nex schema field`](#nex-schema-field)
* [`nex schema validate-catalog`](#nex-schema-validate-catalog)
* [`nex scope`](#nex-scope)
* [`nex scope set`](#nex-scope-set)
* [`nex script-sync pull`](#nex-script-sync-pull)
* [`nex script-sync push`](#nex-script-sync-push)
* [`nex script-sync sync`](#nex-script-sync-sync)
* [`nex search`](#nex-search)
* [`nex search add-table`](#nex-search-add-table)
* [`nex search groups`](#nex-search-groups)
* [`nex search tables`](#nex-search-tables)
* [`nex store install`](#nex-store-install)
* [`nex store search`](#nex-store-search)
* [`nex store update`](#nex-store-update)
* [`nex store validate`](#nex-store-validate)
* [`nex task approve`](#nex-task-approve)
* [`nex task assign`](#nex-task-assign)
* [`nex task close`](#nex-task-close)
* [`nex task comment`](#nex-task-comment)
* [`nex task find`](#nex-task-find)
* [`nex task resolve`](#nex-task-resolve)
* [`nex update-set`](#nex-update-set)
* [`nex update-set clone`](#nex-update-set-clone)
* [`nex update-set create`](#nex-update-set-create)
* [`nex update-set current`](#nex-update-set-current)
* [`nex update-set inspect`](#nex-update-set-inspect)
* [`nex update-set move`](#nex-update-set-move)
* [`nex workflow create`](#nex-workflow-create)
* [`nex workflow publish`](#nex-workflow-publish)
* [`nex xml export`](#nex-xml-export)
* [`nex xml import`](#nex-xml-import)

## `nex aggregate count`

Count records in a ServiceNow table.

```
USAGE
  $ nex aggregate count -t <value> [-j] [-a <value>] [--log-level debug|warn|error|info|trace] [-q <value>]

FLAGS
  -a, --auth=<value>   Auth alias to use.
  -j, --json           Output results as JSON
  -q, --query=<value>  ServiceNow encoded query string to filter records
  -t, --table=<value>  (required) ServiceNow table name to count records in

GLOBAL FLAGS
  --log-level=<option>  [default: info] Specify level for logging.
                        <options: debug|warn|error|info|trace>

DESCRIPTION
  Count records in a ServiceNow table.

  Uses the Stats API to efficiently count records with optional encoded query filtering.

  Features:
  • Fast record counting via Stats API
  • Optional encoded query filtering
  • JSON output for scripting

EXAMPLES
  Count all incidents

    $ nex aggregate count --table incident --auth dev

  Count active critical incidents

    $ nex aggregate count --table incident --query "active=true^priority=1" --auth dev

  Count as JSON

    $ nex aggregate count --table incident --query "active=true" --json --auth dev
```

_See code: [src/commands/aggregate/count.ts](https://github.com/sonisoft-cnanda/nowsdk-ext-cli/blob/v2.3.2/src/commands/aggregate/count.ts)_

## `nex aggregate group`

Run a grouped aggregate query on a ServiceNow table.

```
USAGE
  $ nex aggregate group -t <value> -g <value>... [-j] [-a <value>] [--log-level debug|warn|error|info|trace] [-q
    <value>] [-c] [--avg <value>...] [--min <value>...] [--max <value>...] [--sum <value>...] [--having <value>] [-d]

FLAGS
  -a, --auth=<value>         Auth alias to use.
  -c, --count                Include record count per group
  -d, --display-value        Return display values for group-by fields
  -g, --group-by=<value>...  (required) Field name(s) to group by
  -j, --json                 Output results as JSON
  -q, --query=<value>        ServiceNow encoded query string to filter records before grouping
  -t, --table=<value>        (required) ServiceNow table name to aggregate
      --avg=<value>...       Comma-separated field names to compute AVG on per group
      --having=<value>       HAVING clause to filter groups (e.g. "count>10")
      --max=<value>...       Comma-separated field names to compute MAX on per group
      --min=<value>...       Comma-separated field names to compute MIN on per group
      --sum=<value>...       Comma-separated field names to compute SUM on per group

GLOBAL FLAGS
  --log-level=<option>  [default: info] Specify level for logging.
                        <options: debug|warn|error|info|trace>

DESCRIPTION
  Run a grouped aggregate query on a ServiceNow table.

  Compute aggregate statistics (COUNT, AVG, MIN, MAX, SUM) grouped by one or more fields using the Stats API. Supports
  HAVING clauses for filtering groups.

  Features:
  • GROUP BY one or more fields
  • Compute AVG, MIN, MAX, SUM per group
  • HAVING clause for group filtering
  • Display values for reference fields
  • JSON output for scripting

EXAMPLES
  Count incidents grouped by priority

    $ nex aggregate group --table incident --group-by priority --count --auth dev

  Average reassignment count grouped by priority and assignment group

    $ nex aggregate group --table incident --group-by priority --group-by assignment_group --avg reassignment_count \
      --count --display-value --auth dev

  Groups with HAVING clause

    $ nex aggregate group --table incident --group-by priority --count --having "count>10" --auth dev
```

_See code: [src/commands/aggregate/group.ts](https://github.com/sonisoft-cnanda/nowsdk-ext-cli/blob/v2.3.2/src/commands/aggregate/group.ts)_

## `nex aggregate query`

Run aggregate statistics on a ServiceNow table.

```
USAGE
  $ nex aggregate query -t <value> [-j] [-a <value>] [--log-level debug|warn|error|info|trace] [-q <value>] [-c]
    [--avg <value>...] [--min <value>...] [--max <value>...] [--sum <value>...]

FLAGS
  -a, --auth=<value>    Auth alias to use.
  -c, --count           Include record count in the result
  -j, --json            Output results as JSON
  -q, --query=<value>   ServiceNow encoded query string to filter records
  -t, --table=<value>   (required) ServiceNow table name to aggregate
      --avg=<value>...  Comma-separated field names to compute AVG on
      --max=<value>...  Comma-separated field names to compute MAX on
      --min=<value>...  Comma-separated field names to compute MIN on
      --sum=<value>...  Comma-separated field names to compute SUM on

GLOBAL FLAGS
  --log-level=<option>  [default: info] Specify level for logging.
                        <options: debug|warn|error|info|trace>

DESCRIPTION
  Run aggregate statistics on a ServiceNow table.

  Compute AVG, MIN, MAX, and SUM on specified fields using the Stats API. Optionally include a record count.

  Features:
  • Compute AVG, MIN, MAX, SUM on any numeric field
  • Optional record count
  • Filter with encoded queries
  • JSON output for scripting

EXAMPLES
  Get average reassignment count for incidents

    $ nex aggregate query --table incident --avg reassignment_count --auth dev

  Get min, max, and average for active incidents

    $ nex aggregate query --table incident --query "active=true" --avg reassignment_count --min reassignment_count \
      --max reassignment_count --count --auth dev

  Get sum as JSON

    $ nex aggregate query --table incident --sum reassignment_count --json --auth dev
```

_See code: [src/commands/aggregate/query.ts](https://github.com/sonisoft-cnanda/nowsdk-ext-cli/blob/v2.3.2/src/commands/aggregate/query.ts)_

## `nex app`

Manage ServiceNow applications: uninstall applications from your instance.

```
USAGE
  $ nex app [--json] [-a <value>] [--log-level debug|warn|error|info|trace] [-u] [-i <value>] [-s <value>]

FLAGS
  -a, --auth=<value>           Auth alias to use.
  -i, --applicationId=<value>  Application sys_id
  -s, --scope=<value>          Scope of application.
  -u, --uninstall              Uninstall the app

GLOBAL FLAGS
  --json                Format output as json.
  --log-level=<option>  [default: info] Specify level for logging.
                        <options: debug|warn|error|info|trace>

DESCRIPTION
  Manage ServiceNow applications: uninstall applications from your instance.

  This command provides programmatic control over ServiceNow applications, allowing you to uninstall applications
  remotely. This is useful for automated environment cleanup, testing workflows, and application lifecycle management.

  Features:
  • Uninstall applications by sys_id and scope
  • Automated application removal in CI/CD pipelines
  • Proper cleanup and rollback handling
  • Detailed logging and error reporting

  Requirements:
  • User must have admin role
  • Application must be in a removable state
  • Both application sys_id and scope are required

EXAMPLES
  Uninstall an application by sys_id and scope

    $ nex app --uninstall --applicationId a1b2c3d4e5f6 --scope x_my_custom_app --auth dev-instance

  Uninstall with enhanced debug logging

    $ nex app -u -i a1b2c3d4e5f6 -s x_my_custom_app --auth dev-instance --log-level debug

  Uninstall using short flags

    $ nex app -u -i a1b2c3d4e5f6 -s x_my_custom_app -a dev-instance
```

_See code: [src/commands/app/index.ts](https://github.com/sonisoft-cnanda/nowsdk-ext-cli/blob/v2.3.2/src/commands/app/index.ts)_

## `nex app install`

Install or upgrade multiple ServiceNow applications from a batch definition file.

```
USAGE
  $ nex app install [--json] [-a <value>] [--log-level debug|warn|error|info|trace] [-b] [-d <value>]

FLAGS
  -a, --auth=<value>            Auth alias to use.
  -b, --batch                   Enable batch installation mode from definition file
  -d, --definitionPath=<value>  Path to JSON batch definition file containing applications to install

GLOBAL FLAGS
  --json                Format output as json.
  --log-level=<option>  [default: info] Specify level for logging.
                        <options: debug|warn|error|info|trace>

DESCRIPTION
  Install or upgrade multiple ServiceNow applications from a batch definition file.

  This command enables automated installation and upgrade of multiple applications using a JSON definition file. Perfect
  for setting up new environments, deploying application bundles, or managing application dependencies. The batch file
  can specify multiple applications with their versions, scopes, and installation options.

  Features:
  • Install multiple applications in a single operation
  • Upgrade existing applications to new versions
  • Control demo data loading per application
  • Detailed installation progress and results
  • Automatic dependency resolution
  • Rollback support on failures

  Batch Definition Format:
  The JSON file should contain an "applications" array with objects defining:
  • name: Application name
  • scope: Application scope (e.g., x_my_app)
  • version: Target version number
  • load_demo_data: Whether to load demo data (optional)
  • notes: Installation notes (optional)

EXAMPLES
  Install applications from a batch definition file

    $ nex app install --batch --definitionPath ./apps-to-install.json --auth dev-instance

  Install with short flags

    $ nex app install -b -d ./batch-apps.json -a dev-instance

  Install with debug logging to troubleshoot issues

    $ nex app install -b -d ./apps.json -a dev-instance --log-level debug
```

_See code: [src/commands/app/install.ts](https://github.com/sonisoft-cnanda/nowsdk-ext-cli/blob/v2.3.2/src/commands/app/install.ts)_

## `nex app repo-install`

Install an application from your ServiceNow company repository.

```
USAGE
  $ nex app repo-install -s <value> [--json] [-a <value>] [--log-level debug|warn|error|info|trace] [-w]
    [--poll-interval <value>] [-t <value>] [-v <value>]

FLAGS
  -a, --auth=<value>           Auth alias to use.
  -s, --scope=<value>          (required) Application scope (e.g., x_my_custom_app)
  -t, --timeout=<value>        [default: 1800000] Installation timeout in milliseconds (default: 1800000 = 30 min)
  -v, --version=<value>        Specific version to install (defaults to latest)
  -w, --no-wait                Do not wait for installation to complete
      --poll-interval=<value>  [default: 5000] Polling interval in milliseconds (default: 5000)

GLOBAL FLAGS
  --json                Format output as json.
  --log-level=<option>  [default: info] Specify level for logging.
                        <options: debug|warn|error|info|trace>

DESCRIPTION
  Install an application from your ServiceNow company repository.

  This command installs an application from your company's internal application repository. You can specify the
  application by its scope name, and optionally specify a particular version. The command will automatically look up the
  application details and initiate the installation.

  Features:
  • Install applications by scope name
  • Automatic lookup of application sys_id
  • Optional version specification (defaults to latest)
  • Wait for installation completion with progress monitoring
  • No-wait mode for background installations
  • Configurable polling intervals and timeouts
  • Detailed installation status and error reporting

  Installation Process:
  1. Looks up the application in the company repository by scope
  2. Verifies the application is available and installable
  3. Initiates the installation via CI/CD API
  4. Monitors progress until completion (unless --no-wait specified)
  5. Reports final status and any errors

  Requirements:
  • User must have sn_cicd.sys_ci_automation role
  • Application must exist in company repository
  • Application must not be already installed (or use upgrade)

EXAMPLES
  Install application by scope (latest version)

    $ nex app repo-install --scope x_my_custom_app --auth dev-instance

  Install specific version of an application

    $ nex app repo-install --scope x_my_app --version 2.1.0 --auth dev-instance

  Install without waiting for completion

    $ nex app repo-install --scope x_my_app --no-wait --auth dev-instance

  Install with custom timeout (1 hour)

    $ nex app repo-install -s x_my_app -a dev-instance --timeout 3600000

  Install with debug logging

    $ nex app repo-install -s x_my_app -a dev-instance --log-level debug
```

_See code: [src/commands/app/repo-install.ts](https://github.com/sonisoft-cnanda/nowsdk-ext-cli/blob/v2.3.2/src/commands/app/repo-install.ts)_

## `nex app repo-list`

List applications available in your ServiceNow company repository.

```
USAGE
  $ nex app repo-list [-j] [-a <value>] [--log-level debug|warn|error|info|trace] [-n] [-i]

FLAGS
  -a, --auth=<value>  Auth alias to use.
  -i, --installed     Show only installed applications
  -j, --json          Output results as JSON
  -n, --installable   Show only applications that can be installed (not yet installed)

GLOBAL FLAGS
  --log-level=<option>  [default: info] Specify level for logging.
                        <options: debug|warn|error|info|trace>

DESCRIPTION
  List applications available in your ServiceNow company repository.

  This command retrieves and displays all applications that are available in your company's internal application
  repository. These are applications that have been published internally and are available for installation across your
  ServiceNow instances.

  Features:
  • List all available company repository applications
  • Filter to show only installed applications
  • Filter to show only installable (not yet installed) applications
  • View application details including versions and dependencies
  • JSON output support for automation and scripting
  • Vendor-based filtering

  Use Cases:
  • Discover available applications for installation
  • Audit installed company applications
  • Find applications that can be upgraded
  • Integration with CI/CD pipelines
  • Automated environment setup and configuration

EXAMPLES
  List all company repository applications

    $ nex app repo-list --auth dev-instance

  List only installed applications

    $ nex app repo-list --installed --auth dev-instance

  List only installable (not installed) applications

    $ nex app repo-list --installable --auth dev-instance

  Get JSON output for scripting

    $ nex app repo-list --json --auth dev-instance

  List with short flags

    $ nex app repo-list -a dev-instance
```

_See code: [src/commands/app/repo-list.ts](https://github.com/sonisoft-cnanda/nowsdk-ext-cli/blob/v2.3.2/src/commands/app/repo-list.ts)_

## `nex app uninstall`

Uninstall a ServiceNow application from your instance.

```
USAGE
  $ nex app uninstall -i <value> -s <value> [--json] [-a <value>] [--log-level debug|warn|error|info|trace]

FLAGS
  -a, --auth=<value>           Auth alias to use.
  -i, --applicationId=<value>  (required) Application sys_id
  -s, --scope=<value>          (required) Scope of application

GLOBAL FLAGS
  --json                Format output as json.
  --log-level=<option>  [default: info] Specify level for logging.
                        <options: debug|warn|error|info|trace>

DESCRIPTION
  Uninstall a ServiceNow application from your instance.

  This command provides programmatic control over ServiceNow application removal, allowing you to uninstall applications
  remotely. This is useful for automated environment cleanup, testing workflows, and application lifecycle management.

  Features:
  • Uninstall applications by sys_id and scope
  • Automated application removal in CI/CD pipelines
  • Proper cleanup and rollback handling
  • Detailed logging and error reporting

  Requirements:
  • User must have admin role
  • Application must be in a removable state
  • Both application sys_id and scope are required

EXAMPLES
  Uninstall an application by sys_id and scope

    $ nex app uninstall --applicationId a1b2c3d4e5f6 --scope x_my_custom_app --auth dev-instance

  Uninstall with enhanced debug logging

    $ nex app uninstall -i a1b2c3d4e5f6 -s x_my_custom_app --auth dev-instance --log-level debug

  Uninstall using short flags

    $ nex app uninstall -i a1b2c3d4e5f6 -s x_my_custom_app -a dev-instance
```

_See code: [src/commands/app/uninstall.ts](https://github.com/sonisoft-cnanda/nowsdk-ext-cli/blob/v2.3.2/src/commands/app/uninstall.ts)_

## `nex atf`

Execute ATF (Automated Test Framework) tests or test suites on a ServiceNow instance.

```
USAGE
  $ nex atf [-j] [-a <value>] [--log-level debug|warn|error|info|trace] [-t <value> | -s <value> | -n
    <value>] [-w] [-p <value>] [-b <value>] [--browser-version <value>] [--os-name <value>] [--os-version <value>]
    [--performance] [--cloud]

FLAGS
  -a, --auth=<value>             Auth alias to use.
  -b, --browser=<value>          Browser name for test execution (e.g., chrome, firefox)
  -j, --json                     Output results as JSON
  -n, --suite-name=<value>       Test Suite name to execute
  -p, --poll-interval=<value>    [default: 5000] Polling interval in milliseconds when waiting for completion
  -s, --suite-id=<value>         Test Suite sys_id to execute
  -t, --test-id=<value>          Test sys_id to execute
  -w, --wait                     Wait for test suite execution to complete and return results
      --browser-version=<value>  Browser version for test execution
      --cloud                    Run in cloud
      --os-name=<value>          Operating system name for test execution
      --os-version=<value>       Operating system version for test execution
      --performance              Run as performance test

GLOBAL FLAGS
  --log-level=<option>  [default: info] Specify level for logging.
                        <options: debug|warn|error|info|trace>

DESCRIPTION
  Execute ATF (Automated Test Framework) tests or test suites on a ServiceNow instance.

  This command allows you to run automated tests and test suites remotely, making it perfect for CI/CD pipelines and
  automated testing workflows. You can execute individual tests, entire test suites, and configure execution parameters
  such as browser type, OS, and performance mode.

  Features:
  • Execute individual tests or complete test suites
  • Real-time progress monitoring
  • JSON output for CI/CD integration
  • Detailed test results and summaries
  • Browser and environment configuration
  • Performance testing mode support

EXAMPLES
  Execute a single ATF test by sys_id

    $ nex atf --test-id f717a8c783103210621e78c6feaad396 --auth dev-instance

  Execute a test suite by sys_id and wait for completion

    $ nex atf --suite-id e077e00b83103210621e78c6feaad383 --auth dev-instance --wait

  Execute a test suite by name

    $ nex atf --suite-name "Smoke Tests" --auth dev-instance

  Execute with specific browser configuration

    $ nex atf --suite-id e077e00b83103210621e78c6feaad383 --browser chrome --auth dev-instance

  Execute as performance test with JSON output for CI/CD

    $ nex atf --suite-id e077e00b83103210621e78c6feaad383 --performance --json --auth dev-instance

  Execute with custom poll interval (10 seconds)

    $ nex atf --suite-id e077e00b83103210621e78c6feaad383 --poll-interval 10000 --auth dev-instance
```

_See code: [src/commands/atf/index.ts](https://github.com/sonisoft-cnanda/nowsdk-ext-cli/blob/v2.3.2/src/commands/atf/index.ts)_

## `nex attachment get`

Get metadata for a specific attachment.

```
USAGE
  $ nex attachment get -s <value> [--json] [-a <value>] [--log-level debug|warn|error|info|trace]

FLAGS
  -a, --auth=<value>    Auth alias to use.
  -s, --sys-id=<value>  (required) Sys ID of the attachment

GLOBAL FLAGS
  --json                Format output as json.
  --log-level=<option>  [default: info] Specify level for logging.
                        <options: debug|warn|error|info|trace>

DESCRIPTION
  Get metadata for a specific attachment.

EXAMPLES
  Get attachment metadata by sys_id

    $ nex attachment get --sys-id att123 --auth dev

  Get attachment metadata as JSON

    $ nex attachment get -s att123 --json --auth dev
```

_See code: [src/commands/attachment/get.ts](https://github.com/sonisoft-cnanda/nowsdk-ext-cli/blob/v2.3.2/src/commands/attachment/get.ts)_

## `nex attachment list`

List attachments on a ServiceNow record.

```
USAGE
  $ nex attachment list -r <value> -t <value> [--json] [-a <value>] [--log-level debug|warn|error|info|trace]
    [--limit <value>]

FLAGS
  -a, --auth=<value>       Auth alias to use.
  -r, --record-id=<value>  (required) Sys ID of the record
  -t, --table=<value>      (required) Table name
      --limit=<value>      [default: 20] Maximum number of attachments to return

GLOBAL FLAGS
  --json                Format output as json.
  --log-level=<option>  [default: info] Specify level for logging.
                        <options: debug|warn|error|info|trace>

DESCRIPTION
  List attachments on a ServiceNow record.

EXAMPLES
  List attachments on an incident

    $ nex attachment list --table incident --record-id abc123 --auth dev

  List up to 50 attachments as JSON

    $ nex attachment list -t incident -r abc123 --limit 50 --json --auth dev
```

_See code: [src/commands/attachment/list.ts](https://github.com/sonisoft-cnanda/nowsdk-ext-cli/blob/v2.3.2/src/commands/attachment/list.ts)_

## `nex attachment upload`

Upload a file as an attachment to a ServiceNow record.

```
USAGE
  $ nex attachment upload -f <value> -r <value> -t <value> [--json] [-a <value>] [--log-level
    debug|warn|error|info|trace] [--content-type <value>]

FLAGS
  -a, --auth=<value>          Auth alias to use.
  -f, --file=<value>          (required) Path to the file to upload
  -r, --record-id=<value>     (required) Sys ID of the target record
  -t, --table=<value>         (required) Target table name
      --content-type=<value>  MIME content type of the file

GLOBAL FLAGS
  --json                Format output as json.
  --log-level=<option>  [default: info] Specify level for logging.
                        <options: debug|warn|error|info|trace>

DESCRIPTION
  Upload a file as an attachment to a ServiceNow record.

EXAMPLES
  Upload a PDF to an incident record

    $ nex attachment upload --table incident --record-id abc123 --file ./report.pdf --auth dev

  Upload a CSV with explicit content type

    $ nex attachment upload -t incident -r abc123 -f ./data.csv --content-type text/csv --auth dev
```

_See code: [src/commands/attachment/upload.ts](https://github.com/sonisoft-cnanda/nowsdk-ext-cli/blob/v2.3.2/src/commands/attachment/upload.ts)_

## `nex autocomplete [SHELL]`

Display autocomplete installation instructions.

```
USAGE
  $ nex autocomplete [SHELL] [-r]

ARGUMENTS
  [SHELL]  (zsh|bash|powershell) Shell type

FLAGS
  -r, --refresh-cache  Refresh cache (ignores displaying instructions)

DESCRIPTION
  Display autocomplete installation instructions.

EXAMPLES
  $ nex autocomplete

  $ nex autocomplete bash

  $ nex autocomplete zsh

  $ nex autocomplete powershell

  $ nex autocomplete --refresh-cache
```

_See code: [@oclif/plugin-autocomplete](https://github.com/oclif/plugin-autocomplete/blob/v3.2.40/src/commands/autocomplete/index.ts)_

## `nex batch create`

Batch create records on a ServiceNow instance from a JSON file.

```
USAGE
  $ nex batch create -f <value> [--json] [-a <value>] [--log-level debug|warn|error|info|trace] [--transaction]

FLAGS
  -a, --auth=<value>  Auth alias to use.
  -f, --file=<value>  (required) Path to JSON file with create operations
      --transaction   Stop on first error (transactional)

GLOBAL FLAGS
  --json                Format output as json.
  --log-level=<option>  [default: info] Specify level for logging.
                        <options: debug|warn|error|info|trace>

DESCRIPTION
  Batch create records on a ServiceNow instance from a JSON file.

EXAMPLES
  Create records from a JSON file

    $ nex batch create --file ./records.json --auth dev

  Create records without transactional mode

    $ nex batch create --file ./records.json --no-transaction --auth dev
```

_See code: [src/commands/batch/create.ts](https://github.com/sonisoft-cnanda/nowsdk-ext-cli/blob/v2.3.2/src/commands/batch/create.ts)_

## `nex batch update`

Batch update records on a ServiceNow instance from a JSON file.

```
USAGE
  $ nex batch update -f <value> [--json] [-a <value>] [--log-level debug|warn|error|info|trace] [--stop-on-error]

FLAGS
  -a, --auth=<value>   Auth alias to use.
  -f, --file=<value>   (required) Path to JSON file with update operations
      --stop-on-error  Stop processing on first error

GLOBAL FLAGS
  --json                Format output as json.
  --log-level=<option>  [default: info] Specify level for logging.
                        <options: debug|warn|error|info|trace>

DESCRIPTION
  Batch update records on a ServiceNow instance from a JSON file.

EXAMPLES
  Update records from a JSON file

    $ nex batch update --file ./updates.json --auth dev

  Update records and stop on first error

    $ nex batch update --file ./updates.json --stop-on-error --auth dev
```

_See code: [src/commands/batch/update.ts](https://github.com/sonisoft-cnanda/nowsdk-ext-cli/blob/v2.3.2/src/commands/batch/update.ts)_

## `nex bulk delete`

Bulk delete records matching an encoded query.

```
USAGE
  $ nex bulk delete -t <value> -q <value> [-j] [-a <value>] [--log-level debug|warn|error|info|trace] [--confirm]
    [-l <value>]

FLAGS
  -a, --auth=<value>   Auth alias to use.
  -j, --json           Output results as JSON
  -l, --limit=<value>  [default: 200] Maximum number of records to delete (default 200, max 10000)
  -q, --query=<value>  (required) Encoded query to match records for deletion
  -t, --table=<value>  (required) Table name to delete records from
      --confirm        Execute the delete (without this flag, performs a dry run)

GLOBAL FLAGS
  --log-level=<option>  [default: info] Specify level for logging.
                        <options: debug|warn|error|info|trace>

DESCRIPTION
  Bulk delete records matching an encoded query.

  Finds all records in a table matching the given query, then deletes each one. Defaults to dry-run mode — use --confirm
  to execute.

  Features:
  • Safe dry-run by default (shows match count without deleting)
  • Encoded query filtering
  • Configurable record limit (default 200, max 10000)
  • Progress reporting for large operations
  • Error collection — operation continues even if individual records fail

EXAMPLES
  Dry run — see how many records would be deleted

    $ nex bulk delete --table u_temp_import --query "sys_created_on<2024-01-01" --auth dev

  Execute the delete (requires --confirm)

    $ nex bulk delete --table u_temp_import --query "sys_created_on<2024-01-01" --confirm --auth dev

  Delete with custom limit

    $ nex bulk delete --table incident --query "active=false^closed_at<2023-01-01" --limit 1000 --confirm --auth dev

  Delete as JSON output

    $ nex bulk delete --table u_staging --query "processed=true" --confirm --json --auth dev
```

_See code: [src/commands/bulk/delete.ts](https://github.com/sonisoft-cnanda/nowsdk-ext-cli/blob/v2.3.2/src/commands/bulk/delete.ts)_

## `nex bulk update`

Bulk update records matching an encoded query.

```
USAGE
  $ nex bulk update -t <value> -q <value> -d <value> [-j] [-a <value>] [--log-level debug|warn|error|info|trace]
    [--confirm] [-l <value>]

FLAGS
  -a, --auth=<value>   Auth alias to use.
  -d, --data=<value>   (required) JSON object of field=value pairs to apply (e.g. '{"priority":"4","state":"2"}')
  -j, --json           Output results as JSON
  -l, --limit=<value>  [default: 200] Maximum number of records to update (default 200, max 10000)
  -q, --query=<value>  (required) Encoded query to match records
  -t, --table=<value>  (required) Table name to update records in
      --confirm        Execute the update (without this flag, performs a dry run)

GLOBAL FLAGS
  --log-level=<option>  [default: info] Specify level for logging.
                        <options: debug|warn|error|info|trace>

DESCRIPTION
  Bulk update records matching an encoded query.

  Finds all records in a table matching the given query, then applies field updates to each one. Defaults to dry-run
  mode — use --confirm to execute.

  Features:
  • Safe dry-run by default (shows match count without modifying data)
  • Encoded query filtering
  • JSON field=value pairs for update data
  • Configurable record limit (default 200, max 10000)
  • Progress reporting for large operations
  • Error collection — operation continues even if individual records fail

EXAMPLES
  Dry run — see how many records would be updated

    $ nex bulk update --table incident --query "active=true^priority=5" --data '{"priority":"4"}' --auth dev

  Execute the update (requires --confirm)

    $ nex bulk update --table incident --query "active=true^priority=5" --data '{"priority":"4"}' --confirm --auth \
      dev

  Update with custom limit

    $ nex bulk update --table incident --query "state=1" --data '{"assignment_group":"group-sys-id"}' --limit 500 \
      --confirm --auth dev

  Update as JSON output

    $ nex bulk update --table incident --query "active=true" --data '{"state":"6"}' --confirm --json --auth dev
```

_See code: [src/commands/bulk/update.ts](https://github.com/sonisoft-cnanda/nowsdk-ext-cli/blob/v2.3.2/src/commands/bulk/update.ts)_

## `nex exec SCOPE [FILE]`

Execute JavaScript on a ServiceNow instance remotely using Scripts - Background.

```
USAGE
  $ nex exec SCOPE [FILE] [--json] [-a <value>] [--log-level debug|warn|error|info|trace] [-p <value>]

ARGUMENTS
  SCOPE   Scope to execute script in. Use "global" for global scope.
  [FILE]  File to execute in scripts background. If omitted, starts REPL mode.

FLAGS
  -a, --auth=<value>    Auth alias to use.
  -p, --params=<value>  JSON object of parameters to replace in script file. Use {paramName} syntax in your script.

GLOBAL FLAGS
  --json                Format output as json.
  --log-level=<option>  [default: info] Specify level for logging.
                        <options: debug|warn|error|info|trace>

DESCRIPTION
  Execute JavaScript on a ServiceNow instance remotely using Scripts - Background.

  This command allows you to run JavaScript either from files or interactively via REPL mode. It mimics the
  functionality of the Scripts - Background interface in ServiceNow, providing a way to execute scripts programmatically
  without manual interaction. The output is returned in real-time and can be piped to other commands or saved to files.

  Modes:
  • File Mode: Provide a file path to execute scripts from a file
  • REPL Mode: Omit the file path to start an interactive session

  Features:
  • Execute local JavaScript files remotely
  • Interactive REPL for ad-hoc script execution
  • Script parameterization with {placeholder} replacement
  • Multi-line script support in REPL
  • Scope-aware execution (global or custom scope)
  • Real-time console output capture
  • Pipe-able output for command chaining
  • Debug logging support
  • Useful for data migration, testing, and administrative tasks

  Script Parameterization:
  Use {paramName} placeholders in your script files, then provide values via --params:
  • Supports any JSON-serializable values (strings, numbers, booleans)
  • Multiple parameters supported
  • All occurrences of each placeholder are replaced
  • Example: {token}, {username}, {environment}

  REPL Controls:
  • Press Enter to add a new line
  • Type .exec or press Ctrl+D to execute the script
  • Type .clear to clear the current input
  • Type .exit or press Ctrl+C twice to exit REPL

  ⚠️  IMPORTANT SECURITY WARNING:
  This command executes scripts with the same permissions and risks as using Scripts - Background directly
  in ServiceNow. Always:
  • Review scripts before execution
  • Test in non-production environments first
  • Use appropriate scoping to limit access
  • Be aware of data modification risks
  • Follow your organization's security policies
  • Never execute untrusted scripts

  Script Capabilities:
  Scripts run with full GlideSystem API access and can:
  • Query and modify database records
  • Create, update, and delete data
  • Execute business rules and workflows
  • Access all APIs available in Scripts - Background
  • Use gs, GlideRecord, GlideAggregate, and other server-side APIs

EXAMPLES
  Start REPL in global scope

    $ nex exec global --auth dev-instance

  Start REPL in custom application scope

    $ nex exec x_my_custom_app --auth dev-instance

  Execute a script file in global scope

    $ nex exec global ./scripts/cleanup.js --auth dev-instance

  Execute a script file in a custom application scope

    $ nex exec x_my_custom_app ./scripts/app-config.js --auth dev-instance

  Execute a parameterized script with single parameter

    $ nex exec global ./scripts/query-user.js --auth dev-instance --params '{"username":"admin"}'

  Execute a parameterized script with multiple parameters

    $ nex exec global ./scripts/update-record.js --auth dev-instance --params \
      '{"table":"incident","field":"priority","value":"1"}'

  Execute and save output to a file

    $ nex exec global ./scripts/report.js --auth dev-instance > report.txt

  Execute and pipe output to grep for filtering

    $ nex exec global ./scripts/list-users.js --auth dev-instance | grep "admin"

  Execute with debug logging to troubleshoot issues

    $ nex exec global ./script.js --auth dev-instance --log-level debug

  Execute with parameters for template replacement

    $ nex exec global ./script.js --auth dev-instance --params '{"token":"abc123","env":"dev"}'
```

_See code: [src/commands/exec/index.ts](https://github.com/sonisoft-cnanda/nowsdk-ext-cli/blob/v2.3.2/src/commands/exec/index.ts)_

## `nex flow action`

Execute a Flow Designer action by scoped name.

```
USAGE
  $ nex flow action -n <value> [-j] [-a <value>] [--log-level debug|warn|error|info|trace] [-i <value>] [-m
    foreground|background] [--scope <value>] [--quick]

FLAGS
  -a, --auth=<value>    Auth alias to use.
  -i, --inputs=<value>  JSON object of input name-value pairs
  -j, --json            Output results as JSON
  -m, --mode=<option>   [default: foreground] Execution mode
                        <options: foreground|background>
  -n, --name=<value>    (required) Scoped name of the action (e.g. global.create_record)
      --quick           Skip execution detail records for better performance
      --scope=<value>   Scope context for script execution

GLOBAL FLAGS
  --log-level=<option>  [default: info] Specify level for logging.
                        <options: debug|warn|error|info|trace>

DESCRIPTION
  Execute a Flow Designer action by scoped name.

  Runs an action using the sn_fd.FlowAPI ScriptableFlowRunner.

  Features:
  • Execute actions by scoped name
  • Pass input values as JSON
  • Foreground or background execution mode
  • Returns context ID, outputs, and debug information

EXAMPLES
  Run an action

    $ nex flow action --name global.create_record --inputs \
      '{"table":"incident","values":{"short_description":"Test"}}' --auth dev
```

_See code: [src/commands/flow/action.ts](https://github.com/sonisoft-cnanda/nowsdk-ext-cli/blob/v2.3.2/src/commands/flow/action.ts)_

## `nex flow cancel`

Cancel a running or paused flow execution.

```
USAGE
  $ nex flow cancel -c <value> [-j] [-a <value>] [--log-level debug|warn|error|info|trace] [-r <value>] [--scope
    <value>]

FLAGS
  -a, --auth=<value>        Auth alias to use.
  -c, --context-id=<value>  (required) Flow execution context sys_id
  -j, --json                Output results as JSON
  -r, --reason=<value>      Cancellation reason
      --scope=<value>       Scope context for script execution

GLOBAL FLAGS
  --log-level=<option>  [default: info] Specify level for logging.
                        <options: debug|warn|error|info|trace>

DESCRIPTION
  Cancel a running or paused flow execution.

  Cancels a flow context that is in QUEUED, IN_PROGRESS, or WAITING state.

EXAMPLES
  Cancel a running flow

    $ nex flow cancel --context-id abc123def456 --auth dev

  Cancel with a reason

    $ nex flow cancel --context-id abc123def456 --reason "No longer needed" --auth dev
```

_See code: [src/commands/flow/cancel.ts](https://github.