@sonisoft/now-sdk-ext-cli

v5.2.0

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.

Headless and non-interactive use

now-sdk stores credentials in the OS keyring, which a non-interactive session cannot unlock — even running as the same user. Worse, the failure is silent: the SDK's KeyChain.getPassword() swallows the error and returns null, so you get Default Credential has not been set rather than a keyring error.

If you run nex over SSH, from a systemd service, from CI, or from an AI agent, install @sonisoft/sn-credstore and pass --cred-store. The SDK then reads from a headless-safe store that many concurrent processes can share:

npm install -g @sonisoft/sn-credstore

# One-time migration of existing keyring credentials.
# Run this from a desktop session — the keyring will prompt to unlock.
sn-credstore import --from keyring

nex auth doctor                                    # confirm what is where
nex aggregate count --table incident --auth my-dev-instance --cred-store

This is opt-in. Without --cred-store, nex uses the ServiceNow SDK's OS keyring exactly as it always has, whether or not sn-credstore is installed. To opt in for a whole session instead of per command, export SN_CRED_STORE_ENABLE=1.

By default the store is encrypted with systemd-creds --user, which binds it to this host. Containers without systemd should set SN_CRED_STORE=file.

| Variable | Description | |---|---| | SN_CRED_STORE_ENABLE | Opt in without passing --cred-store on every command | | SN_CRED_STORE_DISABLE | Hard off switch; wins over the flag and everything else | | SN_CRED_STORE | Backend: systemd-creds (default), file, or auto | | SN_CRED_STORE_PATH | Override the store location | | SN_CRED_STORE_DEBUG | Verbose diagnostics on stderr |

Managing stored credentials

nex auth list                # list aliases (secrets are never printed)
nex auth use my-dev-instance # set the default alias
nex auth delete old-alias    # remove one alias
nex auth doctor              # diagnose credential storage

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/5.2.0 linux-x64 node-v26.5.0
$ nex --help [COMMAND]
USAGE
  $ nex COMMAND
...

Restricting what can be changed

Changes to a ServiceNow instance are permitted by default. Two ways to take that away, in priority order:

| | | Reachable by an agent? | |---|---|---| | NEX_POLICY_DENY=write,execute (or all) | environment | No | | --read-only, --deny-write, --deny-execute | per invocation | Yes |

Reads are never gated. nex policy status prints what is permitted and which layer decided — use it first when something is refused, since the fix differs completely between an environment variable and a flag.

A malformed value fails closed: NEX_POLICY_DENY=wrtie denies everything and warns, rather than silently denying nothing.

NEX_POLICY_DENY holds only when set somewhere an agent cannot write — a shell profile, a systemd unit, or a container environment. Not a committed .env or a project-local config file, which anything with file access can edit.
This is a guardrail, not a security boundary. Anything holding the credential can reach the instance directly.

Commands

`nex aggregate count`

Count records in a ServiceNow table.

USAGE
  $ nex aggregate count -t <value> [-j] [-a <value>] [--cred-store] [--deny-execute] [--deny-write] [--log-dir
    <value>] [--log-file] [--log-level debug|warn|error|info|trace] [--read-only] [-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
  --cred-store          Read credentials from @sonisoft/sn-credstore instead of the OS keyring. Use this in headless
                        sessions (SSH, systemd, CI, agents) where the keyring cannot be unlocked.
  --deny-execute        Refuse background scripts, flow runs and ATF runs for this invocation.
  --deny-write          Refuse any change to instance data for this invocation.
  --log-dir=<value>     Directory to write log files to. Implies --log-file.
  --log-file            Write logs to a file. Defaults to $XDG_STATE_HOME/now-sdk-ext/logs
                        (~/.local/state/now-sdk-ext/logs). Off by default; without this, nex logs warnings and errors to
                        stderr only.
  --log-level=<option>  [default: info] Specify level for logging.
                        <options: debug|warn|error|info|trace>
  --read-only           Refuse every change to the instance — equivalent to --deny-write --deny-execute. Reads are
                        unaffected.

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>] [--cred-store] [--deny-execute] [--deny-write]
    [--log-dir <value>] [--log-file] [--log-level debug|warn|error|info|trace] [--read-only] [-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
  --cred-store          Read credentials from @sonisoft/sn-credstore instead of the OS keyring. Use this in headless
                        sessions (SSH, systemd, CI, agents) where the keyring cannot be unlocked.
  --deny-execute        Refuse background scripts, flow runs and ATF runs for this invocation.
  --deny-write          Refuse any change to instance data for this invocation.
  --log-dir=<value>     Directory to write log files to. Implies --log-file.
  --log-file            Write logs to a file. Defaults to $XDG_STATE_HOME/now-sdk-ext/logs
                        (~/.local/state/now-sdk-ext/logs). Off by default; without this, nex logs warnings and errors to
                        stderr only.
  --log-level=<option>  [default: info] Specify level for logging.
                        <options: debug|warn|error|info|trace>
  --read-only           Refuse every change to the instance — equivalent to --deny-write --deny-execute. Reads are
                        unaffected.

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>] [--cred-store] [--deny-execute] [--deny-write] [--log-dir
    <value>] [--log-file] [--log-level debug|warn|error|info|trace] [--read-only] [-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
  --cred-store          Read credentials from @sonisoft/sn-credstore instead of the OS keyring. Use this in headless
                        sessions (SSH, systemd, CI, agents) where the keyring cannot be unlocked.
  --deny-execute        Refuse background scripts, flow runs and ATF runs for this invocation.
  --deny-write          Refuse any change to instance data for this invocation.
  --log-dir=<value>     Directory to write log files to. Implies --log-file.
  --log-file            Write logs to a file. Defaults to $XDG_STATE_HOME/now-sdk-ext/logs
                        (~/.local/state/now-sdk-ext/logs). Off by default; without this, nex logs warnings and errors to
                        stderr only.
  --log-level=<option>  [default: info] Specify level for logging.
                        <options: debug|warn|error|info|trace>
  --read-only           Refuse every change to the instance — equivalent to --deny-write --deny-execute. Reads are
                        unaffected.

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>] [--cred-store] [--deny-execute] [--deny-write] [--log-dir <value>]
    [--log-file] [--log-level debug|warn|error|info|trace] [--read-only] [-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
  --cred-store          Read credentials from @sonisoft/sn-credstore instead of the OS keyring. Use this in headless
                        sessions (SSH, systemd, CI, agents) where the keyring cannot be unlocked.
  --deny-execute        Refuse background scripts, flow runs and ATF runs for this invocation.
  --deny-write          Refuse any change to instance data for this invocation.
  --json                Format output as json.
  --log-dir=<value>     Directory to write log files to. Implies --log-file.
  --log-file            Write logs to a file. Defaults to $XDG_STATE_HOME/now-sdk-ext/logs
                        (~/.local/state/now-sdk-ext/logs). Off by default; without this, nex logs warnings and errors to
                        stderr only.
  --log-level=<option>  [default: info] Specify level for logging.
                        <options: debug|warn|error|info|trace>
  --read-only           Refuse every change to the instance — equivalent to --deny-write --deny-execute. Reads are
                        unaffected.

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>] [--cred-store] [--deny-execute] [--deny-write] [--log-dir <value>]
    [--log-file] [--log-level debug|warn|error|info|trace] [--read-only] [-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
  --cred-store          Read credentials from @sonisoft/sn-credstore instead of the OS keyring. Use this in headless
                        sessions (SSH, systemd, CI, agents) where the keyring cannot be unlocked.
  --deny-execute        Refuse background scripts, flow runs and ATF runs for this invocation.
  --deny-write          Refuse any change to instance data for this invocation.
  --json                Format output as json.
  --log-dir=<value>     Directory to write log files to. Implies --log-file.
  --log-file            Write logs to a file. Defaults to $XDG_STATE_HOME/now-sdk-ext/logs
                        (~/.local/state/now-sdk-ext/logs). Off by default; without this, nex logs warnings and errors to
                        stderr only.
  --log-level=<option>  [default: info] Specify level for logging.
                        <options: debug|warn|error|info|trace>
  --read-only           Refuse every change to the instance — equivalent to --deny-write --deny-execute. Reads are
                        unaffected.

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>] [--cred-store] [--deny-execute] [--deny-write] [--log-dir
    <value>] [--log-file] [--log-level debug|warn|error|info|trace] [--read-only] [-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
  --cred-store          Read credentials from @sonisoft/sn-credstore instead of the OS keyring. Use this in headless
                        sessions (SSH, systemd, CI, agents) where the keyring cannot be unlocked.
  --deny-execute        Refuse background scripts, flow runs and ATF runs for this invocation.
  --deny-write          Refuse any change to instance data for this invocation.
  --json                Format output as json.
  --log-dir=<value>     Directory to write log files to. Implies --log-file.
  --log-file            Write logs to a file. Defaults to $XDG_STATE_HOME/now-sdk-ext/logs
                        (~/.local/state/now-sdk-ext/logs). Off by default; without this, nex logs warnings and errors to
                        stderr only.
  --log-level=<option>  [default: info] Specify level for logging.
                        <options: debug|warn|error|info|trace>
  --read-only           Refuse every change to the instance — equivalent to --deny-write --deny-execute. Reads are
                        unaffected.

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>] [--cred-store] [--deny-execute] [--deny-write] [--log-dir <value>]
    [--log-file] [--log-level debug|warn|error|info|trace] [--read-only] [-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
  --cred-store          Read credentials from @sonisoft/sn-credstore instead of the OS keyring. Use this in headless
                        sessions (SSH, systemd, CI, agents) where the keyring cannot be unlocked.
  --deny-execute        Refuse background scripts, flow runs and ATF runs for this invocation.
  --deny-write          Refuse any change to instance data for this invocation.
  --log-dir=<value>     Directory to write log files to. Implies --log-file.
  --log-file            Write logs to a file. Defaults to $XDG_STATE_HOME/now-sdk-ext/logs
                        (~/.local/state/now-sdk-ext/logs). Off by default; without this, nex logs warnings and errors to
                        stderr only.
  --log-level=<option>  [default: info] Specify level for logging.
                        <options: debug|warn|error|info|trace>
  --read-only           Refuse every change to the instance — equivalent to --deny-write --deny-execute. Reads are
                        unaffected.

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>] [--cred-store] [--deny-execute] [--deny-write]
    [--log-dir <value>] [--log-file] [--log-level debug|warn|error|info|trace] [--read-only]

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

GLOBAL FLAGS
  --cred-store          Read credentials from @sonisoft/sn-credstore instead of the OS keyring. Use this in headless
                        sessions (SSH, systemd, CI, agents) where the keyring cannot be unlocked.
  --deny-execute        Refuse background scripts, flow runs and ATF runs for this invocation.
  --deny-write          Refuse any change to instance data for this invocation.
  --json                Format output as json.
  --log-dir=<value>     Directory to write log files to. Implies --log-file.
  --log-file            Write logs to a file. Defaults to $XDG_STATE_HOME/now-sdk-ext/logs
                        (~/.local/state/now-sdk-ext/logs). Off by default; without this, nex logs warnings and errors to
                        stderr only.
  --log-level=<option>  [default: info] Specify level for logging.
                        <options: debug|warn|error|info|trace>
  --read-only           Refuse every change to the instance — equivalent to --deny-write --deny-execute. Reads are
                        unaffected.

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>] [--cred-store] [--deny-execute] [--deny-write] [--log-dir <value>]
    [--log-file] [--log-level debug|warn|error|info|trace] [--read-only] [-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
  --cred-store          Read credentials from @sonisoft/sn-credstore instead of the OS keyring. Use this in headless
                        sessions (SSH, systemd, CI, agents) where the keyring cannot be unlocked.
  --deny-execute        Refuse background scripts, flow runs and ATF runs for this invocation.
  --deny-write          Refuse any change to instance data for this invocation.
  --log-dir=<value>     Directory to write log files to. Implies --log-file.
  --log-file            Write logs to a file. Defaults to $XDG_STATE_HOME/now-sdk-ext/logs
                        (~/.local/state/now-sdk-ext/logs). Off by default; without this, nex logs warnings and errors to
                        stderr only.
  --log-level=<option>  [default: info] Specify level for logging.
                        <options: debug|warn|error|info|trace>
  --read-only           Refuse every change to the instance — equivalent to --deny-write --deny-execute. Reads are
                        unaffected.

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>] [--cred-store] [--deny-execute] [--deny-write] [--log-dir
    <value>] [--log-file] [--log-level debug|warn|error|info|trace] [--read-only]

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

GLOBAL FLAGS
  --cred-store          Read credentials from @sonisoft/sn-credstore instead of the OS keyring. Use this in headless
                        sessions (SSH, systemd, CI, agents) where the keyring cannot be unlocked.
  --deny-execute        Refuse background scripts, flow runs and ATF runs for this invocation.
  --deny-write          Refuse any change to instance data for this invocation.
  --json                Format output as json.
  --log-dir=<value>     Directory to write log files to. Implies --log-file.
  --log-file            Write logs to a file. Defaults to $XDG_STATE_HOME/now-sdk-ext/logs
                        (~/.local/state/now-sdk-ext/logs). Off by default; without this, nex logs warnings and errors to
                        stderr only.
  --log-level=<option>  [default: info] Specify level for logging.
                        <options: debug|warn|error|info|trace>
  --read-only           Refuse every change to the instance — equivalent to --deny-write --deny-execute. Reads are
                        unaffected.

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>] [--cred-store] [--deny-execute] [--deny-write]
    [--log-dir <value>] [--log-file] [--log-level debug|warn|error|info|trace] [--read-only] [--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
  --cred-store          Read credentials from @sonisoft/sn-credstore instead of the OS keyring. Use this in headless
                        sessions (SSH, systemd, CI, agents) where the keyring cannot be unlocked.
  --deny-execute        Refuse background scripts, flow runs and ATF runs for this invocation.
  --deny-write          Refuse any change to instance data for this invocation.
  --json                Format output as json.
  --log-dir=<value>     Directory to write log files to. Implies --log-file.
  --log-file            Write logs to a file. Defaults to $XDG_STATE_HOME/now-sdk-ext/logs
                        (~/.local/state/now-sdk-ext/logs). Off by default; without this, nex logs warnings and errors to
                        stderr only.
  --log-level=<option>  [default: info] Specify level for logging.
                        <options: debug|warn|error|info|trace>
  --read-only           Refuse every change to the instance — equivalent to --deny-write --deny-execute. Reads are
                        unaffected.

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>] [--cred-store] [--deny-execute]
    [--deny-write] [--log-dir <value>] [--log-file] [--log-level debug|warn|error|info|trace] [--read-only]
    [--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
  --cred-store          Read credentials from @sonisoft/sn-credstore instead of the OS keyring. Use this in headless
                        sessions (SSH, systemd, CI, agents) where t

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

Headless and non-interactive use

Managing stored credentials

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

Restricting what can be changed

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

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`