NetSuite CLI Runner

A command-line interface (CLI) tool for executing ad-hoc SuiteScript 2.1 code directly against NetSuite accounts.

Project Status

✅ Production Ready - All 21 implementation steps complete (100%)

Overview

This project provides a CLI alternative to the NetSuite Instant Runner VS Code extension. It allows developers to execute SuiteScript code from the command line, get structured results, and retrieve execution logs - perfect for automation, testing, and AI agent integration.

Features

✅ Code Execution

• Execute inline SuiteScript 2.1 code or from files
• All NetSuite modules pre-loaded (23 modules available by default)
• Includes: log, search, record, runtime, format, query, transaction, file, https, http, email, error, url, encode, crypto, currency, render, xml, config, task, redirect, cache, certificateControl, workflow
• Real-time governance tracking
• Formatted output with execution time and logs

✅ Log Retrieval

• Retrieve script execution logs from NetSuite
• Defaults to RESTlet runner logs when no script-id specified
• Filter by date range, log type (ERROR, DEBUG, AUDIT)
• Pagination support
• Automatic script ID to internal ID conversion

✅ Proxy Management

• Start/stop local OAuth proxy server (port 9292)
• Runs continuously until manually stopped
• Health check endpoint
• Detached process management

✅ Error Handling

• Semantic exit codes (0-6) for programmatic error detection
• Clear error messages with actionable guidance
• Network, authentication, and validation error categorization

✅ Configuration

• Centralized config.json for customization
• Graceful fallback to defaults
• OAuth credentials via .env file

✅ Interactive Setup

• Zero-friction onboarding with ns-cli setup
• Interactive prompts for OAuth credentials
• Input validation (account ID format, URL format)
• Secret masking during input
• View config with --show option (secrets masked)
• Update config with --update option

Architecture

Similar to the VS Code extension, this uses a 3-tier architecture:

CLI Tool ←→ Local Express Proxy ←→ NetSuite RESTlet
(Commands)  (OAuth 1.0 Signing)    (Code Execution)

Key Differences from VS Code Extension

• CLI-first: Designed for command-line usage, scripting, and automation
• Structured Output: JSON/text output suitable for piping and AI agent consumption
• No UI: Terminal-based interaction only
• Same Integration: Reuses OAuth proxy and NetSuite RESTlet patterns

Methodology

This project follows the three-stage research methodology:

1. product.md - Product vision, users, use cases (no technical decisions)
2. tech-research.md - Technical decisions, architecture choices, dependencies
3. implementation-plan.md - Atomic implementation steps with verification

See Blueprints/methodology.md for details.

Documentation

All project documentation is in the Blueprints/ directory:

• methodology.md - Three-stage research approach
• product.md - Product definition and use cases
• tech-research.md - Technical decisions and architecture
• implementation-plan.md - 21 atomic implementation steps with verification
• implementation-actual.md - Complete implementation log with verification results

Installation

From npm (Recommended)

Install globally from npm:

npm install -g ns-cli-runner

After installation, the ns-cli command will be available globally.

From Source (Development)

For development or contributing:

1. Clone the repository:

   git clone https://github.com/Project-X-Innovation/ns-cli-code-runner.git
   cd ns_cli_runner

2. Install dependencies:

   npm install

3. Link CLI for global usage:

   npm link

Setup

Quick Start

1. Deploy RESTlet to NetSuite:

   • Download ns_cli_runner_restlet.js from the GitHub repository
   • Upload it to NetSuite File Cabinet
   • Create Script record (RESTlet type)
   • Create Script Deployment
   • Note the RESTlet URL

2. Run interactive setup:

   ns-cli setup

   The setup command will prompt you for:

   • NetSuite Account ID (e.g., 123456_SB1)
   • Consumer Key and Secret
   • Token ID and Secret
   • RESTlet URL

   Your credentials will be validated and saved to .env automatically.

3. Start the proxy:

   ns-cli init

Manual Setup (Alternative)

If you prefer manual configuration:

1. Create .env file:

   cp .env.example .env

2. Fill in OAuth credentials in .env:

   • NS_ACCOUNT_ID - Your NetSuite account ID (e.g., 123456_SB1)
   • NS_CONSUMER_KEY - OAuth consumer key
   • NS_CONSUMER_SECRET - OAuth consumer secret
   • NS_TOKEN_ID - OAuth token ID
   • NS_TOKEN_SECRET - OAuth token secret
   • NS_RESTLET_URL - Deployed RESTlet URL

3. (Optional) Customize configuration: Create config.json to override defaults:

   {
     "proxyPort": 9292,
     "proxyInactivityTimeout": 900000,
     "defaultLogCount": 20
   }

Usage

Setup Command

Interactive credential configuration:

ns-cli setup

View current configuration (secrets masked):

ns-cli setup --show

Update existing configuration:

ns-cli setup --update

Execute Code

Execute inline code:

ns-cli run --code "return 2 + 2"

Execute code from file:

ns-cli run --file script.js

Retrieve Logs

Get logs from RESTlet runner (default):

ns-cli logs --type error --page-size 10

Get logs for a specific script:

ns-cli logs --script-id customscript_your_script

With filters:

ns-cli logs --script-id customscript_your_script --date-from 2025-12-01 --date-to 2025-12-14 --type error

Stop Proxy

Stop the proxy server:

ns-cli stop

Exit Codes

The CLI uses semantic exit codes for programmatic error handling:

| Code | Name | Description | | ---- | ---------------- | ----------------------------------------------------- | | 0 | SUCCESS | Command completed successfully | | 1 | GENERAL_ERROR | Unknown or general error | | 2 | CONFIG_ERROR | Configuration error (port conflict, missing .env) | | 3 | NETWORK_ERROR | Network error (proxy unreachable, connection failed) | | 4 | VALIDATION_ERROR | Validation error (missing parameters, file not found) | | 5 | EXECUTION_ERROR | Code execution failed in NetSuite | | 6 | AUTH_ERROR | OAuth authentication failed |

Example usage in scripts:

ns-cli run --code "return 2 + 2"
if [ $? -eq 0 ]; then
  echo "Success!"
else
  echo "Failed with exit code: $?"
fi

Configuration

The CLI supports configuration via config.json (optional):

{
  "proxyPort": 9292,
  "proxyInactivityTimeout": 900000,
  "defaultLogCount": 20
}

If config.json is not found, the CLI uses these defaults automatically.

Project Structure

ns_cli_runner/
├── server/
│   ├── app.js                    # Express proxy server
│   └── nsConnect.js              # OAuth 1.0 signing
├── src/
│   ├── cli.js                    # CLI entry point
│   ├── commands/
│   │   ├── init.js              # Start proxy command
│   │   ├── run.js               # Execute code command
│   │   ├── logs.js              # Retrieve logs command
│   │   ├── stop.js              # Stop proxy command
│   │   └── setup.js             # Interactive setup command
│   └── utils/
│       ├── config.js            # Configuration loader
│       └── exitCodes.js         # Semantic exit codes
├── ns_cli_runner_restlet.js     # NetSuite RESTlet
├── config.json                   # Configuration (optional)
├── .env                          # OAuth credentials (required)
└── package.json                  # Dependencies and scripts

Testing

The project has been tested with:

• NetSuite Sandbox Account (123456_SB1)
• Node.js 20.19.0+
• Windows 10/11
• Full end-to-end integration tests completed

Security

• OAuth 1.0 token-based authentication
• Credentials stored locally in .env file (never transmitted to cloud)
• Proxy runs on localhost only
• You execute code as yourself with your NetSuite role permissions
• All actions are audited in NetSuite

Related Projects:

• NetSuite Instant Runner (VS Code) - VS Code extension version

Last Updated: 2025-12-20 Status: Production Ready - All 21 implementation steps complete