@sonisoft/now-sdk-ext-cli 1.1.0-alpha.2 → 2.0.0-alpha.0

package/README.md

@@ -1,27 +1,411 @@
-@sonisoft/now-sdk-ext-cli
-=================
+# @sonisoft/now-sdk-ext-cli
+
+[![npm version](https://img.shields.io/npm/v/@sonisoft/now-sdk-ext-cli.svg)](https://www.npmjs.com/package/@sonisoft/now-sdk-ext-cli)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+> A powerful CLI toolkit that extends the ServiceNow SDK with advanced automation capabilities for development, testing, and operations.
+
+## 🚀 Overview
+
+`now-sdk-ext-cli` (command: `nex`) is a comprehensive command-line interface that enhances the official ServiceNow SDK with powerful features for developers and administrators. It provides seamless integration with ServiceNow instances to automate common tasks, execute tests, manage applications, and run scripts remotely.
+
+### Why Use `nex`?
+
+- **💪 Powerful Automation**: Automate ServiceNow operations that would otherwise require manual UI interaction
+- **⚡ Fast Development**: Interactive REPL mode for rapid script development and testing
+- **🔧 DevOps Ready**: Built for CI/CD with JSON output, exit codes, and scriptable operations
+- **🎯 Developer Friendly**: Intuitive commands, autocomplete, and extensive documentation
+- **🔒 Secure**: Uses ServiceNow SDK's secure keychain storage for credentials
+
+### Key Features
+
+#### 🧪 ATF Test Automation
+Execute individual ATF tests or entire test suites with detailed results, perfect for CI/CD pipelines.
+
+#### 📦 Application Lifecycle Management
+- **Install** applications from batch definitions
+- **Uninstall** applications programmatically
+- **Repository Management**: List and install apps from your company repository
+- Automated deployment workflows
+
+#### ⚡ Script Execution (Enhanced)
+- **File Mode**: Execute JavaScript files on ServiceNow instances
+- **REPL Mode**: Interactive script executor (like node REPL, but for ServiceNow!)
+- **Parameterization**: Template scripts with `{placeholder}` replacement
+- **Scope-Aware**: Execute in global or custom application scopes
+
+#### 🎨 Advanced Features
+- **Dynamic Autocomplete**: Tab completion that queries your ServiceNow instance for scopes
+- **Batch Operations**: Install multiple applications from JSON definitions
+- **Progress Monitoring**: Real-time progress for long-running operations
+- **JSON Output**: Perfect for parsing and automation
+
+#### 🔄 CI/CD Integration
+- Proper exit codes (0 = success, 1 = failure)
+- JSON output mode for all commands
+- Environment variable support
+- Scriptable and automatable
+
+## 📋 Table of Contents
+
+- [Installation](#-installation)
+- [Prerequisites](#-prerequisites)
+- [Quick Start](#-quick-start)
+- [Core Capabilities](#-core-capabilities)
+  - [ATF Testing](#atf-testing)
+  - [Application Management](#application-management)
+  - [Script Execution with REPL](#script-execution-with-repl)
+  - [Company Repository](#company-repository-integration)
+- [All Commands](#-commands)
+- [Authentication](#-authentication)
+- [Advanced Features](#-advanced-features)
+  - [Interactive REPL](#interactive-repl-mode)
+  - [Script Parameterization](#script-parameterization)
+  - [Shell Autocomplete](#shell-autocomplete)
+- [CI/CD Integration](#-cicd-integration)
+- [Examples](#-examples)
+- [Troubleshooting](#-troubleshooting)
+- [Documentation](#-documentation)
+- [Support & Contributing](#-support--contributing)
+
+## 💾 Installation
+
+### Global Installation (Recommended)
+
+```bash
+npm install -g @sonisoft/now-sdk-ext-cli
+```
+
+### Local Installation
+
+```bash
+npm install @sonisoft/now-sdk-ext-cli
+```
+
+### Verify Installation
+
+```bash
+nex --version
+nex --help
+```
+
+## 📚 Prerequisites
+
+### ServiceNow SDK
+
+**Required**: This CLI extension leverages the official ServiceNow SDK for authentication management. You must install and configure the ServiceNow SDK first.
+
+```bash
+npm install -g @servicenow/sdk
+```
+
+Verify installation:
+
+```bash
+now-sdk --version
+```
+
+**Important**: The `now-sdk-ext-cli` does not manage credentials directly. It uses authentication credentials configured via the ServiceNow SDK (`now-sdk auth` command). This provides:
+- Secure credential storage in your system's keychain
+- Centralized authentication management across ServiceNow tools
+- Support for multiple instance profiles
+- OAuth and basic authentication methods
+
+### Node.js
+
+- **Minimum Version**: Node.js 18.0.0 or higher
+- **Recommended**: Node.js 20.x or later
+
+### ServiceNow Instance
+
+- ServiceNow instance with appropriate permissions
+- API access enabled
+- User account with required roles:
+  - `admin` or `atf_test_runner` for ATF operations
+  - `admin` or `sn_cicd.sys_ci_automation` for application management
+  - Script execution requires appropriate scope access
+
+## 🎯 Quick Start
+
+### 1. Configure Authentication
+
+First, set up your ServiceNow instance credentials using the ServiceNow SDK:
+
+```bash
+# Add credentials (interactive - will prompt for username/password)
+now-sdk auth --add your-instance.service-now.com --type basic --alias my-dev-instance
+
+# Set as default (optional)
+now-sdk auth --use my-dev-instance
+
+# List configured authentication profiles
+now-sdk auth --list
+```
+
+**Note**: Credentials configured via `now-sdk auth` are automatically available to `nex` commands through the `--auth` flag.
+
+### 2. Run Your First Command
+
+```bash
+# Start interactive REPL
+nex exec global --auth my-dev-instance
+
+# Execute an ATF test
+nex atf --test-id <test-sys-id> --auth my-dev-instance
+
+# List repository applications
+nex app:repo-list --auth my-dev-instance
 
-A CLI extending the functionality of the ServiceNow SDK.
+# Install from repository
+nex app:repo-install --scope x_my_app --auth my-dev-instance
+```
+
+---
+
+## 🎯 Core Capabilities
+
+### ATF Testing
+
+Execute Automated Test Framework tests and suites directly from the command line.
+
+```bash
+# Execute a single test
+nex atf --test-id f717a8c783103210621e78c6feaad396 --auth dev
+
+# Execute a test suite by ID
+nex atf --suite-id e077e00b83103210621e78c6feaad383 --auth dev --wait
+
+# Execute by name with JSON output (perfect for CI/CD)
+nex atf --suite-name "Smoke Tests" --auth dev --json > results.json
+
+# Configure browser and performance settings
+nex atf --suite-id abc123 --browser chrome --performance --auth dev
+```
+
+**Key Features:**
+- Execute individual tests or complete suites
+- Wait for completion or run async
+- JSON output for CI/CD integration
+- Browser/OS configuration
+- Performance testing mode
+- Real-time progress monitoring
+
+### Application Management
+
+Comprehensive application lifecycle management tools.
+
+```bash
+# Install applications from batch definition
+nex app:install --batch --definitionPath ./apps.json --auth dev
+
+# Uninstall an application
+nex app:uninstall -i <sys_id> -s x_my_app --auth dev
+
+# List repository applications (what's available to install)
+nex app:repo-list --installable --auth dev
+
+# Install from company repository
+nex app:repo-install --scope x_my_app --version 2.1.0 --auth dev
+
+# List installed repository apps
+nex app:repo-list --installed --json --auth dev
+```
+
+**Key Features:**
+- Batch installation from JSON definitions
+- Repository browsing and installation
+- Progress monitoring with configurable timeouts
+- Post-installation verification
+- JSON output for automation
+
+### Script Execution with REPL
+
+Execute JavaScript on ServiceNow instances - now with three powerful modes!
+
+#### Mode 1: Execute Script Files
+```bash
+nex exec global ./cleanup.js --auth dev
+nex exec x_my_app ./app-config.js --auth dev
+```
+
+#### Mode 2: Interactive REPL ⭐ NEW!
+```bash
+$ nex exec global --auth dev
+
+sn> var gr = new GlideRecord('sys_user');
+... gr.addQuery('active', true);
+... gr.query();
+... gs.info('Active users: ' + gr.getRowCount());
+... .exec
+
+*** Script: Active users: 142
+
+sn> .exit
+```
+
+**REPL Features:**
+- Multi-line script input
+- Execute with `.exec` or Ctrl+D
+- Clear buffer with `.clear`
+- Command history within session
+- Beautiful, intuitive interface
+
+#### Mode 3: Parameterized Scripts ⭐ NEW!
+```bash
+# Script with placeholders: {username}, {table}
+nex exec global ./query-user.js \
+  --auth dev \
+  --params '{"username":"admin","table":"sys_user"}'
+```
 
-Future capabilities will be expanded, but currently this CLI will allow you to execute a javascript file that resides on your local computer in a ServiceNow instance remotely.
-This mimicks the functionality of using Scripts - Background and has all of the caveats and warnings carried in doing so.
+**Parameterization Features:**
+- `{placeholder}` syntax in scripts
+- JSON parameter object
+- Multiple parameters supported
+- All data types (string, number, boolean)
+- Perfect for environment-specific scripts
 
-This library extends the ServiceNow SDK published originally in Washington DC.  Currently you must use the ServiceNow SDK to configure your authentication credentials for a particular ServiceNow instance. Then the credential alias configured using the ServiceNow SDK can be passed
-to the command(s) below.
+### Company Repository Integration
 
-The library has a built in dependency for @servicenow/sdk version 2.0.1. 
-You will need to install the SDK globally separately in order to use the now-sdk command.
+Discover and install applications from your company's internal repository.
 
-Note: 
-One of the current limitations of the ServiceNow SDK is that it does not work if Multifactor Authentication is enable on the user that is being used with the SDK. 
-Either MFA on the instance needs to be turned off, or the local user account being used needs to be excluded from the MFA configuration.
--- Future work of this CLI is intended to overcome this issue.
+```bash
+# See what's available
+nex app:repo-list --auth prod
 
+# Filter for installable apps
+nex app:repo-list --installable --json --auth prod
+
+# Install by scope (automatic lookup)
+nex app:repo-install --scope x_custom_app --auth prod
+
+# Install specific version
+nex app:repo-install --scope x_custom_app --version 1.2.0 --auth prod
+
+# Background installation
+nex app:repo-install --scope x_custom_app --no-wait --auth prod
+```
+
+**Key Features:**
+- Browse company repository applications
+- Filter by installation status
+- Install by scope name (no need to look up sys_id)
+- Version control
+- Wait for completion or run async
+- Post-installation verification
+
+## 📖 Commands
 
 <!-- toc -->
+* [@sonisoft/now-sdk-ext-cli](#sonisoftnow-sdk-ext-cli)
+* [Add credentials (interactive - will prompt for username/password)](#add-credentials-interactive---will-prompt-for-usernamepassword)
+* [Set as default (optional)](#set-as-default-optional)
+* [List configured authentication profiles](#list-configured-authentication-profiles)
+* [Start interactive REPL](#start-interactive-repl)
+* [Execute an ATF test](#execute-an-atf-test)
+* [List repository applications](#list-repository-applications)
+* [Install from repository](#install-from-repository)
+* [Execute a single test](#execute-a-single-test)
+* [Execute a test suite by ID](#execute-a-test-suite-by-id)
+* [Execute by name with JSON output (perfect for CI/CD)](#execute-by-name-with-json-output-perfect-for-cicd)
+* [Configure browser and performance settings](#configure-browser-and-performance-settings)
+* [Install applications from batch definition](#install-applications-from-batch-definition)
+* [Uninstall an application](#uninstall-an-application)
+* [List repository applications (what's available to install)](#list-repository-applications-whats-available-to-install)
+* [Install from company repository](#install-from-company-repository)
+* [List installed repository apps](#list-installed-repository-apps)
+* [Script with placeholders: {username}, {table}](#script-with-placeholders-username-table)
+* [See what's available](#see-whats-available)
+* [Filter for installable apps](#filter-for-installable-apps)
+* [Install by scope (automatic lookup)](#install-by-scope-automatic-lookup)
+* [Install specific version](#install-specific-version)
+* [Background installation](#background-installation)
 * [Usage](#usage)
 * [Commands](#commands)
+* [Global scope](#global-scope)
+* [Custom application scope](#custom-application-scope)
+* [Development](#development)
+* [Production](#production)
+* [GitHub Actions](#github-actions)
+* [1. Enable autocomplete](#1-enable-autocomplete)
+* [2. Follow shell-specific instructions (bash/zsh/fish)](#2-follow-shell-specific-instructions-bashzshfish)
+* [3. Reload shell](#3-reload-shell)
+* [4. Start using it!](#4-start-using-it)
+* [Autocomplete queries ServiceNow and shows:](#autocomplete-queries-servicenow-and-shows)
+* [Ready to execute!](#ready-to-execute)
+* [Add credentials interactively (will prompt for username/password)](#add-credentials-interactively-will-prompt-for-usernamepassword)
+* [For OAuth authentication](#for-oauth-authentication)
+* [List all configured authentication profiles](#list-all-configured-authentication-profiles)
+* [Set default authentication profile (optional)](#set-default-authentication-profile-optional)
+* [Delete an authentication profile](#delete-an-authentication-profile)
+* [Use specific authentication profile via --auth flag](#use-specific-authentication-profile-via---auth-flag)
+* [Use default profile (if set with --use)](#use-default-profile-if-set-with---use)
+* [All commands support the --auth flag](#all-commands-support-the---auth-flag)
+* [Set credentials in environment](#set-credentials-in-environment)
+* [Add authentication profile (will use environment variables)](#add-authentication-profile-will-use-environment-variables)
+* [1. List available repository apps](#1-list-available-repository-apps)
+* [2. Install application from repository](#2-install-application-from-repository)
+* [3. Configure using REPL](#3-configure-using-repl)
+* [4. Run tests](#4-run-tests)
+* [5. Deploy to production with parameterized script](#5-deploy-to-production-with-parameterized-script)
+* [6. Verify deployment](#6-verify-deployment)
+* [Execute a single test](#execute-a-single-test)
+* [Execute a test suite and wait for results](#execute-a-test-suite-and-wait-for-results)
+* [Execute by name (no need to look up sys_id)](#execute-by-name-no-need-to-look-up-sys_id)
+* [Performance test with specific browser](#performance-test-with-specific-browser)
+* [CI/CD integration with JSON output](#cicd-integration-with-json-output)
+* [Custom polling for long tests](#custom-polling-for-long-tests)
+* [Browse company repository](#browse-company-repository)
+* [Install from repository](#install-from-repository)
+* [Batch install multiple apps](#batch-install-multiple-apps)
+* [Uninstall application](#uninstall-application)
+* [Execute script file](#execute-script-file)
+* [Execute in custom scope](#execute-in-custom-scope)
+* [Pipe output](#pipe-output)
+* [Start REPL](#start-repl)
+* [Execute multi-line scripts interactively](#execute-multi-line-scripts-interactively)
+* [Single parameter](#single-parameter)
+* [Multiple parameters](#multiple-parameters)
+* [From environment variables](#from-environment-variables)
+* [daily-tests.sh](#daily-testssh)
+* [setup-environment.sh](#setup-environmentsh)
+* [Install required apps from repository](#install-required-apps-from-repository)
+* [Configure via parameterized script](#configure-via-parameterized-script)
+* [Validate with ATF](#validate-with-atf)
+* [migrate-data.sh](#migrate-datash)
+* [Export from source](#export-from-source)
+* [Transform data](#transform-data)
+* [Import to target with parameters](#import-to-target-with-parameters)
+* [Validate](#validate)
+* [List all configured authentication profiles](#list-all-configured-authentication-profiles)
+* [Delete and re-add credentials if needed](#delete-and-re-add-credentials-if-needed)
+* [Set as default](#set-as-default)
+* [Verify installation](#verify-installation)
+* [Reinstall if needed](#reinstall-if-needed)
+* [Check PATH includes npm global binaries](#check-path-includes-npm-global-binaries)
+* [Increase poll interval](#increase-poll-interval)
+* [Check instance performance](#check-instance-performance)
+* [Check test suite complexity](#check-test-suite-complexity)
+* [Review ServiceNow logs](#review-servicenow-logs)
+* [Verify user has required roles:](#verify-user-has-required-roles)
+* [- atf_test_runner for ATF operations](#--atf_test_runner-for-atf-operations)
+* [- admin for app management](#--admin-for-app-management)
+* [- appropriate scope access for scripts](#--appropriate-scope-access-for-scripts)
+* [General help](#general-help)
+* [Command-specific help](#command-specific-help)
+* [Command-specific help](#command-specific-help)
+* [Enable autocomplete](#enable-autocomplete)
+* [Clone the repository](#clone-the-repository)
+* [Install dependencies](#install-dependencies)
+* [Build](#build)
+* [Run tests (48 unit tests)](#run-tests-48-unit-tests)
+* [Run linter](#run-linter)
+* [Test locally](#test-locally)
+* [All tests](#all-tests)
+* [Specific test file](#specific-test-file)
+* [With coverage](#with-coverage)
 <!-- tocstop -->
+
 # Usage
 <!-- usage -->
 ```sh-session
@@ -29,19 +413,26 @@ $ npm install -g @sonisoft/now-sdk-ext-cli
 $ nex COMMAND
 running command...
 $ nex (--version)
-@sonisoft/now-sdk-ext-cli/1.1.0-alpha.2 darwin-arm64 node-v22.6.0
+@sonisoft/now-sdk-ext-cli/2.0.0-alpha.0 darwin-arm64 node-v22.6.0
 $ nex --help [COMMAND]
 USAGE
   $ nex COMMAND
 ...
 ```
 <!-- usagestop -->
+
 # Commands
 <!-- commands -->
 * [`nex app`](#nex-app)
 * [`nex app install`](#nex-app-install)
-* [`nex exec SCOPE FILE`](#nex-exec-scope-file)
+* [`nex app repo-install`](#nex-app-repo-install)
+* [`nex app repo-list`](#nex-app-repo-list)
+* [`nex app uninstall`](#nex-app-uninstall)
+* [`nex atf`](#nex-atf)
+* [`nex autocomplete [SHELL]`](#nex-autocomplete-shell)
+* [`nex exec SCOPE [FILE]`](#nex-exec-scope-file)
 * [`nex help [COMMAND]`](#nex-help-command)
+* [`nex log`](#nex-log)
 * [`nex plugins`](#nex-plugins)
 * [`nex plugins add PLUGIN`](#nex-plugins-add-plugin)
 * [`nex plugins:inspect PLUGIN...`](#nex-pluginsinspect-plugin)
@@ -55,6 +446,8 @@ USAGE
 
 ## `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>]
@@ -70,14 +463,40 @@ GLOBAL FLAGS
   --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
-  $ nex app exec global test.js --auth sn_alias
-  test
+  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
 ```
 
 ## `nex app install`
 
-Install or Upgrade application(s) from batch definition file
+Install or upgrade multiple ServiceNow applications from a batch definition file.
 
 ```
 USAGE
@@ -85,8 +504,8 @@ USAGE
 
 FLAGS
   -a, --auth=<value>            Auth alias to use.
-  -b, --batch                   Install from batch definition file
-  -d, --definitionPath=<value>  Batch definition file
+  -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.
@@ -94,27 +513,341 @@ GLOBAL FLAGS
                         <options: debug|warn|error|info|trace>
 
 DESCRIPTION
-  Install or Upgrade application(s) from batch definition file
+  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
-  $ nex app install exec global test.js --auth sn_alias
-  test
+  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
 ```
 
-## `nex exec SCOPE FILE`
+## `nex app repo-install`
 
-Execute a local javascript file on a ServiceNow instance using Scripts - Background remotely. Returns the output/raw console output that Scripts - Background outputs to the browser in order to support the execution and result being piped to another command.
+Install an application from your ServiceNow company repository.
 
 ```
 USAGE
-  $ nex exec SCOPE FILE [--json] [-a <value>] [--log-level debug|warn|error|info|trace]
+  $ nex app repo-install -s <value> [--json] [-a <value>] [--log-level debug|warn|error|info|trace] [-w]
+    [--poll-interval <value>] [-t <value>] [-v <value>]
 
-ARGUMENTS
-  SCOPE  Scope to execute file in.
-  FILE   File to execute in scripts background.
+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
+```
+
+## `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
+```
+
+## `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
+```
+
+## `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
+```
+
+## `nex autocomplete [SHELL]`
+
+Display autocomplete installation instructions.
+
+```
+USAGE
+  $ nex autocomplete [SHELL] [-r]
+
+ARGUMENTS
+  SHELL  (zsh|bash|powershell) Shell type
+
+FLAGS
+  -r, --refresh-cache  Refresh cache (ignores displaying instructions)
+
+DESCRIPTION
+  Display autocomplete installation instructions.
+
+EXAMPLES
+  $ nex autocomplete
+
+  $ nex autocomplete bash
+
+  $ nex autocomplete zsh
+
+  $ nex autocomplete powershell
+
+  $ nex autocomplete --refresh-cache
+```
+
+_See code: [@oclif/plugin-autocomplete](https://github.com/oclif/plugin-autocomplete/blob/v3.2.35/src/commands/autocomplete/index.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.
@@ -122,13 +855,99 @@ GLOBAL FLAGS
                         <options: debug|warn|error|info|trace>
 
 DESCRIPTION
-  Execute a local javascript file on a ServiceNow instance using Scripts - Background remotely. Returns the output/raw
-  console output that Scripts - Background outputs to the browser in order to support the execution and result being
-  piped to another command.
+  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
-  $ nex exec exec global test.js --auth sn_alias
-  test
+  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"}'
 ```
 
 ## `nex help [COMMAND]`
@@ -151,6 +970,109 @@ DESCRIPTION
 
 _See code: [@oclif/plugin-help](https://github.com/oclif/plugin-help/blob/v6.2.32/src/commands/help.ts)_
 
+## `nex log`
+
+Tail and monitor ServiceNow system logs in real-time with beautiful formatting.
+
+```
+USAGE
+  $ nex log [--json] [-a <value>] [--log-level debug|warn|error|info|trace] [-o <value>] [-i <value>]
+    [--no-color] [-f <value>...]
+
+FLAGS
+  -a, --auth=<value>       Auth alias to use.
+  -f, --filter=<value>...  Filter logs by field and value. Syntax: field OPERATOR value. Operators: CONTAINS,
+                           CONTAINS_CI (case-insensitive), EQUALS, EQUALS_CI, STARTS_WITH, STARTS_WITH_CI, ENDS_WITH,
+                           ENDS_WITH_CI, REGEX, NOT_CONTAINS, NOT_EQUALS. Field defaults to "message" if omitted.
+                           Multiple filters are combined with AND logic.
+  -i, --interval=<value>   [default: 1000] Polling interval in milliseconds
+  -o, --output=<value>     Output file path to save logs. Creates parent directories if needed.
+      --no-color           Disable colored output
+
+GLOBAL FLAGS
+  --json                Format output as json.
+  --log-level=<option>  [default: info] Specify level for logging.
+                        <options: debug|warn|error|info|trace>
+
+DESCRIPTION
+  Tail and monitor ServiceNow system logs in real-time with beautiful formatting.
+
+  This command provides real-time log monitoring with enhanced visual formatting using color-coded output that makes
+  logs easy to scan and understand at a glance. Automatically highlights errors, warnings, success messages, and
+  important keywords.
+
+  Key Features:
+  • Real-time log tailing (like Unix tail -f)
+  • Powerful filtering with multiple operators (CONTAINS, REGEX, EQUALS, etc.)
+  • Smart keyword highlighting (errors in red, warnings in yellow, etc.)
+  • Beautiful color-coded console output with chalk
+  • Export logs to file with automatic appending
+  • Fast 1-second default polling interval
+  • Timestamps and sequence numbers for each log
+  • Graceful shutdown with Ctrl+C
+  • Clean output without colors (--no-color flag)
+
+  Smart Highlighting:
+  • Error terms (error, exception, failed) - highlighted in RED
+  • Warning terms (warn, warning, deprecated) - highlighted in YELLOW
+  • Success terms (success, completed, done) - highlighted in GREEN
+  • System terms (system, user, transaction) - highlighted in BLUE
+
+  Filtering:
+  • Apply filters using --filter flag with syntax: "field OPERATOR value"
+  • Supports case-sensitive and case-insensitive operations
+  • Multiple filters are combined with AND logic
+  • Operators: CONTAINS, CONTAINS_CI, EQUALS, EQUALS_CI, STARTS_WITH, STARTS_WITH_CI,
+  ENDS_WITH, ENDS_WITH_CI, REGEX, NOT_CONTAINS, NOT_CONTAINS_CI, NOT_EQUALS, NOT_EQUALS_CI
+
+  Use Cases:
+  • Monitor logs during application development
+  • Debug issues in real-time
+  • Track system events during deployments
+  • Filter logs for specific application or component
+  • Quickly spot errors and warnings
+  • Collect logs for analysis or audit trails
+
+  ⚠️  IMPORTANT NOTES:
+  • Press Ctrl+C to stop tailing and exit gracefully
+  • Log files are created/appended automatically
+  • Uses ChannelAjax when available for better performance
+  • Default poll interval is 1 second for real-time monitoring
+
+EXAMPLES
+  Tail all logs in real-time
+
+    $ nex log --auth dev-instance
+
+  Tail logs and save to a file
+
+    $ nex log --output ./logs/instance-logs.txt --auth dev-instance
+
+  Tail logs with custom polling interval (500ms for faster updates)
+
+    $ nex log --interval 500 --auth dev-instance
+
+  Filter logs containing specific text (case-insensitive)
+
+    $ nex log --filter "message CONTAINS_CI error" --auth dev-instance
+
+  Filter logs with multiple conditions (AND logic)
+
+    $ nex log --filter "message CONTAINS x_taniu_tan_core" --filter "message CONTAINS error" --auth dev-instance
+
+  Filter logs using regex pattern
+
+    $ nex log --filter "message REGEX .*exception.*" --auth dev-instance
+
+  Filter logs by message starting with a pattern
+
+    $ nex log --filter "message STARTS_WITH [ERROR]" --auth dev-instance
+
+  Tail logs without colored output
+
+    $ nex log --no-color --auth dev-instance
+```
+
 ## `nex plugins`
 
 List installed plugins.
@@ -441,3 +1363,872 @@ DESCRIPTION
 
 _See code: [@oclif/plugin-plugins](https://github.com/oclif/plugin-plugins/blob/v5.4.46/src/commands/plugins/update.ts)_
 <!-- commandsstop -->
+
+---
+
+## 🚀 Advanced Features
+
+### Interactive REPL Mode
+
+The ServiceNow Script Executor REPL provides an interactive environment for executing scripts without creating files - perfect for quick queries, debugging, and exploration.
+
+#### Starting the REPL
+
+```bash
+# Global scope
+nex exec global --auth dev
+
+# Custom application scope  
+nex exec x_my_custom_app --auth dev
+```
+
+#### REPL Interface
+
+```
+╔═══════════════════════════════════════════════════════════════╗
+║  ServiceNow Script Executor REPL                              ║
+╚═══════════════════════════════════════════════════════════════╝
+  Scope: global
+  Instance: dev12345.service-now.com
+
+  Commands:
+    .exec    - Execute the current script
+    .clear   - Clear the current input
+    .exit    - Exit REPL
+    Ctrl+D   - Execute the current script
+    Ctrl+C   - Cancel current input or exit (press twice)
+
+  Type your script below (press Enter for new lines):
+
+sn> var gr = new GlideRecord('incident');
+... gr.addQuery('priority', 1);
+... gr.setLimit(5);
+... gr.query();
+... while (gr.next()) {
+...   gs.info(gr.number + ': ' + gr.short_description);
+... }
+... .exec
+
+  Executing script (7 lines)...
+
+  ───────────────────────────────────────────────────────────────
+
+*** Script: INC0001234: Server down
+*** Script: INC0001235: Network issue
+*** Script: INC0001236: Database error
+
+  ───────────────────────────────────────────────────────────────
+  ✓ Script executed successfully
+
+sn>
+```
+
+#### REPL Commands
+
+| Command | Description |
+|---------|-------------|
+| `.exec` | Execute the current script buffer |
+| `.clear` | Clear the current input |
+| `.exit` | Exit REPL |
+| `Ctrl+D` | Execute and continue |
+| `Ctrl+C` (once) | Clear input |
+| `Ctrl+C` (twice) | Exit REPL |
+
+#### Use Cases
+
+- **Quick Queries**: Test GlideRecord queries without creating files
+- **Debugging**: Explore API behavior interactively
+- **Learning**: Learn ServiceNow APIs hands-on
+- **Prototyping**: Test logic before adding to applications
+- **Admin Tasks**: One-off administrative operations
+
+📚 **Full Documentation**: [REPL Mode Guide](./docs/REPL_MODE.md)
+
+---
+
+### Script Parameterization
+
+Create reusable script templates with runtime parameter replacement - perfect for multi-environment deployments and CI/CD.
+
+#### Basic Usage
+
+**1. Create a template script:**
+
+**File: `deploy.js`**
+```javascript
+// Deploy to {environment}
+var config = {
+  environment: '{environment}',
+  apiEndpoint: '{api_endpoint}',
+  debugMode: {debug_mode},
+  timeout: {timeout}
+};
+
+gs.setProperty('app.config', JSON.stringify(config));
+gs.info('Deployed to: ' + config.environment);
+```
+
+**2. Execute with parameters:**
+
+```bash
+# Development
+nex exec global ./deploy.js \
+  --auth dev \
+  --params '{"environment":"dev","api_endpoint":"https://dev-api.com","debug_mode":true,"timeout":60000}'
+
+# Production  
+nex exec global ./deploy.js \
+  --auth prod \
+  --params '{"environment":"prod","api_endpoint":"https://api.com","debug_mode":false,"timeout":30000}'
+```
+
+#### Parameter Syntax
+
+Use `{paramName}` in your scripts:
+
+```javascript
+var username = '{username}';           // String
+var retries = {max_retries};           // Number
+var enabled = {feature_enabled};       // Boolean
+var endpoint = '{api_endpoint}';       // URL
+```
+
+Provide values via `--params` flag:
+
+```bash
+--params '{"username":"admin","max_retries":3,"feature_enabled":true,"api_endpoint":"https://api.example.com"}'
+```
+
+#### Advanced Examples
+
+**API Integration:**
+```javascript
+var request = new sn_ws.RESTMessageV2();
+request.setEndpoint('{endpoint}');
+request.setRequestHeader('Authorization', 'Bearer {token}');
+var response = request.execute();
+```
+
+**Bulk Operations:**
+```javascript
+var gr = new GlideRecord('{table}');
+gr.addQuery('{field}', '{value}');
+gr.query();
+while (gr.next()) {
+  gr.setValue('{update_field}', '{update_value}');
+  gr.update();
+}
+```
+
+**CI/CD Integration:**
+```yaml
+# GitHub Actions
+- name: Deploy Script
+  run: |
+    nex exec global ./deploy.js \
+      --auth ci \
+      --params "{\"env\":\"${{ vars.ENVIRONMENT }}\",\"token\":\"${{ secrets.API_TOKEN }}\"}"
+```
+
+📚 **Full Documentation**: [Script Parameterization Guide](./docs/SCRIPT_PARAMETERIZATION.md)
+
+---
+
+### Shell Autocomplete
+
+Intelligent tab completion that dynamically queries your ServiceNow instance for available scopes.
+
+#### Setup (One-Time)
+
+```bash
+# 1. Enable autocomplete
+nex autocomplete
+
+# 2. Follow shell-specific instructions (bash/zsh/fish)
+
+# 3. Reload shell
+source ~/.zshrc  # or ~/.bashrc
+
+# 4. Start using it!
+```
+
+#### Usage
+
+```bash
+$ nex exec --auth dev x_tan[TAB]
+
+# Autocomplete queries ServiceNow and shows:
+x_taniu_ai_itsm      x_taniu_tan_core      x_tanium_integration
+
+$ nex exec --auth dev x_taniu_tan_core
+# Ready to execute!
+```
+
+#### How It Works
+
+1. **You type** and press Tab
+2. **CLI extracts** the `--auth` flag value
+3. **Queries ServiceNow** `sys_scope` table for matching scopes
+4. **Returns suggestions** from your actual instance
+5. **Caches results** for 5 minutes (fast subsequent lookups)
+
+#### Features
+
+- ✅ Real-time querying of your ServiceNow instance
+- ✅ Works with multiple instances (different cache per instance)
+- ✅ Intelligent caching (5-minute TTL)
+- ✅ Supports Basic Auth and OAuth
+- ✅ Graceful fallback if query fails
+- ✅ No configuration needed
+
+📚 **Full Documentation**: [Autocomplete Guide](./docs/AUTOCOMPLETE.md) | [Quick Start](./docs/AUTOCOMPLETE_QUICKSTART.md)
+
+---
+
+## 🔐 Authentication
+
+### How Authentication Works
+
+`now-sdk-ext-cli` uses the ServiceNow SDK's authentication system. You configure credentials once using the `now-sdk auth` command, and they're automatically available to all `nex` commands.
+
+### Setting Up Authentication
+
+```bash
+# Add credentials interactively (will prompt for username/password)
+now-sdk auth --add your-instance.service-now.com --type basic --alias prod
+
+# For OAuth authentication
+now-sdk auth --add your-instance.service-now.com --type oauth --alias prod-oauth
+
+# List all configured authentication profiles
+now-sdk auth --list
+
+# Set default authentication profile (optional)
+now-sdk auth --use prod
+
+# Delete an authentication profile
+now-sdk auth --delete old-instance
+```
+
+### Credential Storage
+
+Credentials are securely stored in your operating system's keychain:
+- **macOS**: Keychain
+- **Linux**: Secret Service API (libsecret)
+- **Windows**: Credential Vault
+
+Only authentication metadata (alias, instance URL, type) is stored in plain text configuration files.
+
+### Using Authentication in Commands
+
+```bash
+# Use specific authentication profile via --auth flag
+nex atf --test-id xyz123 --auth prod
+
+# Use default profile (if set with --use)
+nex atf --test-id xyz123
+
+# All commands support the --auth flag
+nex exec global ./script.js --auth prod
+nex app uninstall -i app-id -s x_scope --auth prod
+```
+
+### Environment Variables for CI/CD
+
+For automated environments, you can use environment variables:
+
+```bash
+# Set credentials in environment
+export NOWSDK_INSTANCE=your-instance.service-now.com
+export NOWSDK_USER=admin
+export NOWSDK_PASSWORD=your-password
+
+# Add authentication profile (will use environment variables)
+now-sdk auth --add $NOWSDK_INSTANCE --type basic --alias ci
+```
+
+### For ServiceNow SDK Documentation
+
+For complete authentication documentation, see:
+**ServiceNow SDK CLI Commands**: https://www.servicenow.com/docs/bundle/zurich-application-development/page/build/servicenow-sdk/reference/servicenow-sdk-cli-commands.html
+
+## 🔄 CI/CD Integration
+
+### GitHub Actions Example
+
+```yaml
+name: ServiceNow ATF Tests
+
+on:
+  push:
+    branches: [ main, develop ]
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    
+    steps:
+      - uses: actions/checkout@v3
+      
+      - name: Setup Node.js
+        uses: actions/setup-node@v3
+        with:
+          node-version: '20'
+      
+      - name: Install Dependencies
+        run: |
+          npm install -g @servicenow/sdk
+          npm install -g @sonisoft/now-sdk-ext-cli
+      
+      - name: Configure ServiceNow Authentication
+        env:
+          NOWSDK_INSTANCE: ${{ secrets.SN_INSTANCE }}
+          NOWSDK_USER: ${{ secrets.SN_USER }}
+          NOWSDK_PASSWORD: ${{ secrets.SN_PASSWORD }}
+        run: |
+          now-sdk auth --add $NOWSDK_INSTANCE --type basic --alias ci-instance
+      
+      - name: Run ATF Test Suite
+        run: |
+          nex atf \
+            --suite-id ${{ vars.TEST_SUITE_ID }} \
+            --auth ci-instance \
+            --json > test-results.json
+      
+      - name: Upload Test Results
+        if: always()
+        uses: actions/upload-artifact@v3
+        with:
+          name: test-results
+          path: test-results.json
+```
+
+### GitLab CI Example
+
+```yaml
+servicenow-tests:
+  image: node:20
+  stage: test
+  before_script:
+    - npm install -g @servicenow/sdk
+    - npm install -g @sonisoft/now-sdk-ext-cli
+    - export NOWSDK_INSTANCE=$SN_INSTANCE NOWSDK_USER=$SN_USER NOWSDK_PASSWORD=$SN_PASSWORD
+    - now-sdk auth --add $SN_INSTANCE --type basic --alias ci
+  script:
+    - nex atf --suite-id $TEST_SUITE_ID --auth ci --json > test-results.json
+  artifacts:
+    when: always
+    reports:
+      junit: test-results.json
+    paths:
+      - test-results.json
+```
+
+### Jenkins Pipeline Example
+
+```groovy
+pipeline {
+    agent any
+    
+    environment {
+        SN_INSTANCE = credentials('servicenow-instance')
+        SN_CREDENTIALS = credentials('servicenow-credentials')
+    }
+    
+    stages {
+        stage('Setup') {
+            steps {
+                sh '''
+                    npm install -g @servicenow/sdk
+                    npm install -g @sonisoft/now-sdk-ext-cli
+                    export NOWSDK_INSTANCE=$SN_INSTANCE NOWSDK_USER=$SN_CREDENTIALS_USR NOWSDK_PASSWORD=$SN_CREDENTIALS_PSW
+                    now-sdk auth --add $SN_INSTANCE --type basic --alias jenkins
+                '''
+            }
+        }
+        
+        stage('Run Tests') {
+            steps {
+                sh '''
+                    nex atf --suite-id ${TEST_SUITE_ID} --auth jenkins --json > test-results.json
+                '''
+            }
+        }
+        
+        stage('Publish Results') {
+            steps {
+                archiveArtifacts artifacts: 'test-results.json'
+                publishHTML([
+                    reportDir: '.',
+                    reportFiles: 'test-results.json',
+                    reportName: 'ATF Test Results'
+                ])
+            }
+        }
+    }
+}
+```
+
+## 💡 Examples
+
+### Complete Workflow: Development to Production
+
+```bash
+# 1. List available repository apps
+nex app:repo-list --installable --auth dev
+
+# 2. Install application from repository
+nex app:repo-install --scope x_my_app --auth dev
+
+# 3. Configure using REPL
+nex exec x_my_app --auth dev
+sn> gs.setProperty('x_my_app.api_key', 'dev_key_123');
+... .exec
+
+# 4. Run tests
+nex atf --suite-name "My App Tests" --auth dev --wait
+
+# 5. Deploy to production with parameterized script
+nex exec global ./deploy.js \
+  --auth prod \
+  --params '{"env":"production","api_key":"prod_key_456"}'
+
+# 6. Verify deployment
+nex atf --suite-name "Smoke Tests" --auth prod --json > results.json
+```
+
+### ATF Testing Examples
+
+```bash
+# Execute a single test
+nex atf --test-id f717a8c783103210621e78c6feaad396 --auth dev
+
+# Execute a test suite and wait for results
+nex atf --suite-id e077e00b83103210621e78c6feaad383 --auth dev --wait
+
+# Execute by name (no need to look up sys_id)
+nex atf --suite-name "Regression Tests" --auth dev
+
+# Performance test with specific browser
+nex atf --suite-id abc123 --browser chrome --performance --auth dev
+
+# CI/CD integration with JSON output
+nex atf --suite-name "CI Tests" --auth ci --json > test-results.json
+
+# Custom polling for long tests
+nex atf --suite-id xyz789 --poll-interval 10000 --auth dev
+```
+
+### Application Management Examples
+
+```bash
+# Browse company repository
+nex app:repo-list --auth prod
+nex app:repo-list --installable --json --auth prod
+
+# Install from repository
+nex app:repo-install --scope x_custom_app --auth prod
+nex app:repo-install --scope x_custom_app --version 2.0.0 --auth prod
+nex app:repo-install --scope x_custom_app --no-wait --auth prod
+
+# Batch install multiple apps
+nex app:install --batch --definitionPath ./production-apps.json --auth prod
+
+# Uninstall application
+nex app:uninstall -i a1b2c3d4e5f6 -s x_my_app --auth dev
+```
+
+### Script Execution Examples
+
+#### File Mode
+```bash
+# Execute script file
+nex exec global ./cleanup.js --auth dev
+
+# Execute in custom scope
+nex exec x_my_app ./app-setup.js --auth dev
+
+# Pipe output
+nex exec global ./report.js --auth dev > report.txt
+nex exec global ./list-users.js --auth dev | grep "admin"
+```
+
+#### REPL Mode
+```bash
+# Start REPL
+$ nex exec global --auth dev
+
+# Execute multi-line scripts interactively
+sn> var gr = new GlideRecord('incident');
+... gr.addQuery('priority', 1);
+... gr.query();
+... gs.info('Critical incidents: ' + gr.getRowCount());
+... .exec
+
+*** Script: Critical incidents: 5
+
+sn> .exit
+```
+
+#### Parameterized Scripts
+```bash
+# Single parameter
+nex exec global ./query-user.js \
+  --auth dev \
+  --params '{"username":"admin"}'
+
+# Multiple parameters
+nex exec global ./deploy.js \
+  --auth prod \
+  --params '{"env":"production","token":"secret","debug":false,"timeout":30000}'
+
+# From environment variables
+export API_TOKEN="secret_token"
+nex exec global ./api-call.js \
+  --auth prod \
+  --params "{\"token\":\"$API_TOKEN\",\"endpoint\":\"https://api.example.com\"}"
+```
+
+### Batch Application Installation
+
+Create a `batch-install.json` file:
+
+```json
+{
+  "applications": [
+    {
+      "name": "Core Application",
+      "scope": "x_core_app",
+      "version": "2.0.0",
+      "load_demo_data": false,
+      "notes": "Production release"
+    },
+    {
+      "name": "Integration Module",
+      "scope": "x_integration",
+      "version": "1.5.0",
+      "load_demo_data": false
+    }
+  ]
+}
+```
+
+Execute:
+
+```bash
+nex app:install --batch --definitionPath ./batch-install.json --auth prod
+```
+
+### Real-World Scenarios
+
+#### Scenario 1: Daily Smoke Tests
+```bash
+#!/bin/bash
+# daily-tests.sh
+
+nex atf \
+  --suite-name "Daily Smoke Tests" \
+  --auth prod \
+  --json > test-results-$(date +%Y%m%d).json
+
+if [ $? -eq 0 ]; then
+  echo "✓ All tests passed!"
+else
+  echo "✗ Tests failed!"
+  exit 1
+fi
+```
+
+#### Scenario 2: Environment Setup
+```bash
+#!/bin/bash
+# setup-environment.sh
+
+# Install required apps from repository
+nex app:repo-install --scope x_core_app --auth new-env
+nex app:repo-install --scope x_integration --auth new-env
+
+# Configure via parameterized script
+nex exec global ./configure.js \
+  --auth new-env \
+  --params '{"env":"staging","debug":true}'
+
+# Validate with ATF
+nex atf --suite-name "Environment Validation" --auth new-env
+```
+
+#### Scenario 3: Data Migration
+```bash
+#!/bin/bash
+# migrate-data.sh
+
+# Export from source
+nex exec global ./export-data.js --auth source > data.json
+
+# Transform data
+cat data.json | jq '.records' > transformed.json
+
+# Import to target with parameters
+nex exec global ./import-data.js \
+  --auth target \
+  --params "{\"data\":\"$(cat transformed.json)\"}"
+
+# Validate
+nex atf --suite-name "Data Validation" --auth target
+```
+
+## 🔧 Troubleshooting
+
+### Common Issues
+
+#### Authentication Errors
+
+```bash
+# List all configured authentication profiles
+now-sdk auth --list
+
+# Delete and re-add credentials if needed
+now-sdk auth --delete your-alias
+now-sdk auth --add instance.service-now.com --type basic --alias your-alias
+
+# Set as default
+now-sdk auth --use your-alias
+```
+
+#### Command Not Found
+
+```bash
+# Verify installation
+npm list -g @sonisoft/now-sdk-ext-cli
+
+# Reinstall if needed
+npm install -g @sonisoft/now-sdk-ext-cli
+
+# Check PATH includes npm global binaries
+npm config get prefix
+```
+
+#### Test Execution Timeouts
+
+```bash
+# Increase poll interval
+nex atf --suite-id xyz --auth dev --poll-interval 15000
+
+# Check instance performance
+# Check test suite complexity
+# Review ServiceNow logs
+```
+
+#### Permission Errors
+
+```bash
+# Verify user has required roles:
+# - atf_test_runner for ATF operations
+# - admin for app management
+# - appropriate scope access for scripts
+```
+
+### Debug Mode
+
+Enable debug logging for detailed troubleshooting:
+
+```bash
+nex atf --test-id xyz --auth dev --log-level debug
+```
+
+### Getting Help
+
+```bash
+# General help
+nex --help
+
+# Command-specific help
+nex atf --help
+nex app --help
+nex exec --help
+```
+
+## 📝 Best Practices
+
+### Security
+
+- **Never commit credentials** to version control
+- Use environment variables or secure credential stores in CI/CD
+- Regularly rotate passwords
+- Use least-privilege accounts for automation
+- Audit script execution logs
+
+### Testing
+
+- Always test scripts in development environments first
+- Use ATF for automated regression testing
+- Implement proper error handling in scripts
+- Validate batch installation definitions before production use
+
+### CI/CD
+
+- Use JSON output mode for parsing results
+- Check exit codes (0 = success, 1 = failure)
+- Archive test results as artifacts
+- Implement proper secret management
+- Use dedicated service accounts
+
+### Performance
+
+- Adjust poll intervals based on test duration
+- Use batch operations when possible
+- Monitor instance performance during test execution
+- Consider off-peak hours for large operations
+
+## 📚 Documentation
+
+### Comprehensive Guides
+
+| Guide | Description |
+|-------|-------------|
+| [Getting Started](./docs/GETTING_STARTED.md) | Complete setup and first steps guide |
+| [REPL Mode](./docs/REPL_MODE.md) | Interactive script executor documentation |
+| [Script Parameterization](./docs/SCRIPT_PARAMETERIZATION.md) | Template scripts with parameter replacement |
+| [Autocomplete Setup](./docs/AUTOCOMPLETE.md) | Full autocomplete documentation |
+| [Autocomplete Quick Start](./docs/AUTOCOMPLETE_QUICKSTART.md) | 3-step setup guide |
+| [ATF Command](./docs/ATF_COMMAND.md) | Detailed ATF testing documentation |
+| [Summary](./docs/SUMMARY.md) | Feature overview and capabilities |
+
+### Quick References
+
+```bash
+# Command-specific help
+nex --help
+nex atf --help
+nex app --help
+nex app:repo-list --help
+nex app:repo-install --help
+nex app:uninstall --help
+nex exec --help
+
+# Enable autocomplete
+nex autocomplete
+```
+
+### API Reference
+
+All commands are built on `@sonisoft/now-sdk-ext-core`. For low-level API documentation:
+- [Core Library Documentation](https://www.npmjs.com/package/@sonisoft/now-sdk-ext-core)
+- [ServiceNow SDK Documentation](https://www.servicenow.com/docs/bundle/zurich-application-development/page/build/servicenow-sdk/reference/servicenow-sdk-cli-commands.html)
+
+---
+
+## 📞 Support & Contributing
+
+### Getting Help
+
+- 📖 **Documentation**: Start with [Getting Started Guide](./docs/GETTING_STARTED.md)
+- 💬 **Issues**: [GitHub Issues](https://github.com/sonisoft/now-sdk-ext-cli/issues)
+- 📦 **NPM**: [@sonisoft/now-sdk-ext-cli](https://www.npmjs.com/package/@sonisoft/now-sdk-ext-cli)
+- ❓ **Questions**: Open a GitHub Discussion
+
+### Contributing
+
+Contributions are welcome! We appreciate:
+
+- 🐛 Bug reports and fixes
+- ✨ Feature requests and implementations
+- 📖 Documentation improvements
+- 🧪 Additional test coverage
+- 💡 Usage examples and tutorials
+
+#### Development Setup
+
+```bash
+# Clone the repository
+git clone https://github.com/sonisoft/now-sdk-ext-cli.git
+cd now-sdk-ext-cli
+
+# Install dependencies
+npm install
+
+# Build
+npm run build
+
+# Run tests (48 unit tests)
+npm test
+
+# Run linter
+npm run lint
+
+# Test locally
+./bin/run.js exec global --auth your-instance
+```
+
+#### Running Tests
+
+```bash
+# All tests
+npm test
+
+# Specific test file
+npm test -- test/commands/exec/parameterization.test.ts
+
+# With coverage
+npm test -- --coverage
+```
+
+---
+
+## 📄 License
+
+MIT License - see [LICENSE](LICENSE) file for details.
+
+## 🔗 Related Projects
+
+- [@servicenow/sdk](https://www.npmjs.com/package/@servicenow/sdk) - Official ServiceNow SDK
+- [@sonisoft/now-sdk-ext-core](https://www.npmjs.com/package/@sonisoft/now-sdk-ext-core) - Core library powering this CLI
+
+---
+
+## ⭐ Why Choose `nex`?
+
+### vs. Manual ServiceNow UI
+
+| Task | Manual UI | With `nex` |
+|------|-----------|------------|
+| Run 10 ATF tests | Click each test, wait, check results (30+ min) | `nex atf --suite-id xyz --json` (5 min) |
+| Install 5 apps | Navigate, click, wait for each (20+ min) | `nex app:install --batch apps.json` (10 min) |
+| Test a script idea | Create file, upload, run, download (5 min) | `nex exec global` type & run (30 sec) |
+| Deploy to 3 envs | Repeat manually 3 times (1+ hour) | `./deploy.sh` with params (15 min) |
+
+### vs. ServiceNow REST API
+
+| Feature | REST API | With `nex` |
+|---------|----------|------------|
+| Authentication | Manage yourself | Uses ServiceNow SDK (secure keychain) |
+| ATF Execution | Complex multi-step process | Single command |
+| Progress Monitoring | Manual polling | Automatic with progress display |
+| Error Handling | Parse HTTP responses | Clear error messages |
+| Output Formatting | Parse JSON yourself | Beautiful console or JSON mode |
+
+### vs. Other Tools
+
+- ✅ **Built for ServiceNow**: Purpose-built, not a generic tool adapted for ServiceNow
+- ✅ **Modern CLI**: Uses industry-standard oclif framework
+- ✅ **Extensible**: Plugin support for custom commands
+- ✅ **Well-Tested**: 48+ unit tests, production-ready
+- ✅ **Actively Maintained**: Regular updates and improvements
+- ✅ **Open Source**: MIT licensed, community-driven
+
+### What Makes It Special
+
+1. **🎨 Interactive REPL**: Only CLI with interactive ServiceNow script execution
+2. **🎯 Smart Autocomplete**: Only CLI that queries your instance for scopes
+3. **📝 Parameterization**: Template scripts for any environment
+4. **📦 Repository Integration**: Direct company repository access
+5. **🔄 Complete Lifecycle**: From installation to testing to uninstallation
+6. **🚀 DevOps First**: Built for automation, CI/CD, and modern workflows
+
+---
+
+Made with ❤️ for the ServiceNow Developer Community
+
+**Ready to get started?** → [Jump to Quick Start](#-quick-start)