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

$3

Install globally from npm:

`bash
npm install -g ns-cli-runner
`

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

$3

For development or contributing:

1. Clone the repository:

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

2. Install dependencies:

`bash
npm install
`

3. Link CLI for global usage:

`bash
npm link
`

Setup

$3

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:

`bash
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:
`bash
ns-cli init
`

$3

If you prefer manual configuration:

1. Create .env file:

`bash
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:
`json
{
"proxyPort": 9292,
"proxyInactivityTimeout": 900000,
"defaultLogCount": 20
}
`

Usage

$3

Interactive credential configuration:

`bash
ns-cli setup
`

View current configuration (secrets masked):

`bash
ns-cli setup --show
`

Update existing configuration:

`bash
ns-cli setup --update
`

$3

Execute inline code:

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

Execute code from file:

`bash
ns-cli run --file script.js
`

$3

Get logs from RESTlet runner (default):

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

Get logs for a specific script:

`bash
ns-cli logs --script-id customscript_your_script
`

With filters:

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

$3

Stop the proxy server:

`bash
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:

`bash
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):

`json
{
"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