@sonisoft/now-sdk-ext-cli

v2.3.2

Published

5 days ago

A CLI extending the functionality of the ServiceNow SDK.

0High
0Medium
0Low

servicenow servicenow-sdk cli automation atf automated-testing testing cicd devops scripts application-management now-sdk oclif

@sonisoft/now-sdk-ext-cli

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

⚠️ 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:
# 1. Update the global CLI
npm install -g @servicenow/[email protected]

# 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)

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

Local Installation

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

Verify Installation

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.

npm install -g @servicenow/sdk

Verify installation:

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:

# 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

# 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.

# 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.

# 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

nex exec global ./cleanup.js --auth dev
nex exec x_my_app ./app-config.js --auth dev

Mode 2: Interactive REPL ⭐ NEW!

$ 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!

# 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.

# 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.

# 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.

# 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.

# 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.

# 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.

# 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

Usage

$ 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
...

Commands

`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

`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

`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

`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

`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

`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

`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

`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

`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

`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

`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

`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

`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

`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

`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

`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

`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

`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

`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

`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.

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

@sonisoft/now-sdk-ext-cli

🚀 Overview

Why Use nex?

Key Features

🧪 ATF Test Automation

📦 Application Lifecycle Management

⚡ Script Execution (Enhanced)

🔍 Query & Search

📊 Aggregate & Analytics

🏥 Instance Health & Diagnostics

🔀 Flow Designer Operations

🗑️ Bulk Record Operations

🎨 Advanced Features

🔄 CI/CD Integration

📋 Table of Contents

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

💾 Installation

Global Installation (Recommended)

Local Installation

Verify Installation

📚 Prerequisites

ServiceNow SDK

Node.js

ServiceNow Instance

🎯 Quick Start

1. Configure Authentication

2. Run Your First Command

🎯 Core Capabilities

ATF Testing

Application Management

Script Execution with REPL

Mode 1: Execute Script Files

Mode 2: Interactive REPL ⭐ NEW!

Mode 3: Parameterized Scripts ⭐ NEW!

Company Repository Integration

Query & Search

Aggregate & Analytics

Instance Health Check

Flow Designer Operations

Bulk Record Operations

📖 Commands

Usage

Commands

nex aggregate count

nex aggregate group

nex aggregate query

nex app

nex app install

nex app repo-install

nex app repo-list

nex app uninstall

nex atf

nex attachment get

nex attachment list

nex attachment upload

nex autocomplete [SHELL]

nex batch create

nex batch update

nex bulk delete

nex bulk update

nex exec SCOPE [FILE]

nex flow action

nex flow cancel

Why Use `nex`?

`nex aggregate count`

`nex aggregate group`

`nex aggregate query`

`nex app`

`nex app install`

`nex app repo-install`

`nex app repo-list`

`nex app uninstall`

`nex atf`

`nex attachment get`

`nex attachment list`

`nex attachment upload`

`nex autocomplete [SHELL]`

`nex batch create`

`nex batch update`

`nex bulk delete`

`nex bulk update`

`nex exec SCOPE [FILE]`

`nex flow action`

`nex flow cancel`