CLI tool for executing SuiteScript code against NetSuite
npm install ns-cli-runnerA command-line interface (CLI) tool for executing ad-hoc SuiteScript 2.1 code directly against NetSuite accounts.
✅ Production Ready - All 21 implementation steps complete (100%)
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.
✅ 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
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)
- 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
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.
All project documentation is in the Blueprints/ directory:
- methodology.md - Three-stage research approachproduct.md
- - Product definition and use casestech-research.md
- - Technical decisions and architectureimplementation-plan.md
- - 21 atomic implementation steps with verificationimplementation-actual.md
- - Complete implementation log with verification results
Install globally from npm:
`bash`
npm install -g ns-cli-runner
After installation, the ns-cli command will be available globally.
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
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
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 keyNS_CONSUMER_SECRET
- - OAuth consumer secretNS_TOKEN_ID
- - OAuth token IDNS_TOKEN_SECRET
- - OAuth token secretNS_RESTLET_URL
- - Deployed RESTlet URL
3. (Optional) Customize configuration:
Create config.json to override defaults:`
json`
{
"proxyPort": 9292,
"proxyInactivityTimeout": 900000,
"defaultLogCount": 20
}
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
Execute inline code:
`bash`
ns-cli run --code "return 2 + 2"
Execute code from file:
`bash`
ns-cli run --file script.js
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
Stop the proxy server:
`bash`
ns-cli stop
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
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.
``
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
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
- 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